Skip to main content
When you edit a specification, the ripple effects can be wide: ancestors gain a changed subtree, nodes that depend on the edited requirement may need review, and code that references those requirements could be stale. xspec impact surfaces all of that in a single report by comparing your current workspace against a baseline at any git ref.
The command is purely informational — it exits 0 regardless of what it finds. Use --json to get machine-readable output suitable for CI annotations or downstream tooling.

​
Change categories

The report groups impacted specification nodes into four categories: Every non-root category entry includes an attributed to field that traces the change back to the originating node in one hop, so you never have to chase a chain of cascades manually.

​
Impacted code

Beyond specification nodes, the report identifies code locations affected by the change:
  • Directly impacted — the code location has an edge to a node whose subtreeHash changed. The text it points at is genuinely different.
  • Transitively impacted — the code location has an edge to a node whose effectiveHash changed but whose subtreeHash is unchanged. The node reads the same, but one of its dependencies moved or changed beneath it.

​
Reading a human report

The header line shows the resolved commit hash of the baseline, confirming exactly what you are diffing against. Each section then lists nodes or code locations in that category, with attribution.

​
JSON output shape

Pass --json to get a structured payload you can pipe into other tools:
The deleted flag on each requirement entry distinguishes removed nodes (where no current state exists) from nodes that still exist but changed.

​
Baselines and refactoring

Journaled renames and moves are invisible to impact. If you rename auth.lockout to auth.throttling using xspec rename, the journal records the mapping and xspec impact produces an empty report — the identity is preserved across the baseline boundary.
Hand-editing IDs directly in MDX files bypasses the journal. xspec treats this as a deletion of the old ID and an addition of a new one, producing a noisy impact report. Always use xspec rename or xspec move for structural changes. See Renaming and Moving Requirements Safely for details.
If the baseline commit cannot be reconstructed (e.g., the commit is unreachable), xspec impact exits with code 2 rather than producing a partial or misleading report.

​
Use cases

Pre-merge PR annotation Run impact against the main branch in CI and feed the JSON output into your PR tooling to annotate which requirements and code locations are affected:
Review scoping Turn an impact report directly into a structured review checklist. The --base flag on xspec review create runs the same analysis and populates a session with items for every affected node:
See Running Staged Review Sessions for how to work through the resulting session. Change auditing The attribution field in every impact entry traces each cascaded effect back to the node that originated it. This makes audit trails straightforward: every upstream-changed or descendant-changed entry tells you exactly which content edit triggered it.