Analyzing the Impact of Specification Changes

Use xspec impact to discover which requirements, ancestors, and code locations are affected by spec changes relative to any git baseline.

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.

xspec impact --base <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:

Category	Meaning
changed	Node was added or deleted, or its own content changed
metadata-changed	The node’s dependency targets, coverage setting, or tags changed
descendant-changed	At least one node in the subtree changed (the node itself is structurally affected)
upstream-changed	A dependency target of this node changed effectively — the node reads the same, but what it points at is different

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

$ xspec impact --base HEAD
baseline 56b30aaab448c0a1b0207b9c67dd8a0571485501
changed:
  specs/AUTH.mdx#auth.lockout — attributed to: specs/AUTH.mdx#auth.lockout
descendant-changed:
  specs/AUTH.mdx, specs/AUTH.mdx#auth — attributed to: specs/AUTH.mdx#auth.lockout
upstream-changed:
  specs/OVERVIEW.mdx — attributed to: specs/AUTH.mdx#auth.lockout
  specs/OVERVIEW.mdx#overview — attributed to: specs/AUTH.mdx#auth.lockout
directly impacted code:
  test/auth.test.ts#testInvalidLogin — via references specs/AUTH.mdx#auth.login.invalid; path: specs/AUTH.mdx#auth.login.invalid

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:

xspec impact --base origin/main --json

{
  "baseline": "56b30aa…",
  "requirements": [
    {
      "nodes": ["specs/AUTH.mdx#auth.lockout"],
      "deleted": false,
      "categories": [
        { "category": "changed", "attributedTo": ["specs/AUTH.mdx#auth.lockout"] }
      ]
    }
  ],
  "code": {
    "direct": [
      {
        "location": "test/auth.test.ts#testInvalidLogin",
        "edge": {
          "from": "test/auth.test.ts#testInvalidLogin",
          "kind": "references",
          "to": "specs/AUTH.mdx#auth.login.invalid"
        },
        "path": ["specs/AUTH.mdx#auth.login.invalid"]
      }
    ],
    "transitive": []
  }
}

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:

xspec impact --base origin/main --json

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:

xspec review create --base origin/main --name pre-merge-review

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.