> ## Documentation Index
> Fetch the complete documentation index at: https://xspec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```sh theme={null}
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

```sh theme={null}
$ 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:

```sh theme={null}
xspec impact --base origin/main --json
```

```json theme={null}
{
  "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.

<Warning>
  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](/workflows/refactoring) for details.
</Warning>

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:

```sh theme={null}
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:

```sh theme={null}
xspec review create --base origin/main --name pre-merge-review
```

See [Running Staged Review Sessions](/workflows/reviews) 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.