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

# Running Staged Review Sessions with xspec

> Create durable, structured review checklists from impact reports, coverage gaps, or full audits, then work through them item by item at your own pace.

A review session is a staged, durable checklist that lets you systematically work through a set of specification nodes — whether you are reviewing a change, closing coverage gaps, or auditing a codebase for the first time. Sessions are stored as JSON files under `.xspec/reviews/<name>.json`, committed to version control, and survive arbitrary workspace edits between sittings.

## Creating a session

You create a session by choosing a strategy and giving it a name:

```sh theme={null}
xspec review create --base <ref> --name <name>      # path-blocks strategy
xspec review create --strategy audit --name <name>  # audit strategy
xspec review create --coverage <profile> --name <name>  # coverage strategy
```

### Strategies

**`path-blocks` (default with `--base`)**

Generates items based on a change relative to a git baseline — the same analysis as `xspec impact`. Items cover:

* **subtree-coherence** — changed subtree roots that need a human review of their new content
* **parent-consistency** — ancestor nodes, blocked until their children are resolved
* **metadata-consistency** — nodes whose dependency targets, coverage setting, or tags changed
* **dependency-consistency** — nodes that depend on changed targets
* **code-impact** — code locations directly or transitively affected by the change

Use this strategy before merging a branch or after a significant content edit.

**`audit`**

Creates one `subtree-coherence` item per node in the graph, with no baseline. Leaves unlock first; parents unlock only after their children are resolved. This gives you a bottom-up pass through the entire specification. Use it for initial adoption or periodic full audits.

**`coverage`**

Creates one `uncovered-requirement` item per uncovered node in the named coverage profile at the time the session is created. This turns a coverage gap report into a burn-down checklist. See [Measuring and Gating Requirement Coverage](/workflows/coverage) for background on coverage profiles.

## Item model and statuses

Each item in a session has a status from the following set:

| Status        | Meaning                                                        |
| ------------- | -------------------------------------------------------------- |
| `unresolved`  | Not yet reviewed                                               |
| `updated`     | Reviewed and confirmed that the node was intentionally updated |
| `no-change`   | Reviewed and confirmed that no substantive change occurred     |
| `skipped`     | Deliberately deferred without a conclusion                     |
| `invalidated` | Was resolved, but relevant state changed since resolution      |

<Note>
  `invalidated` items are the session's integrity mechanism. If you resolve an item and then a subsequent workspace edit changes the node it covers, xspec marks it `invalidated` so you know the resolution may no longer hold. Re-resolve it to clear the flag.
</Note>

## Working a session

Use this set of commands to navigate and resolve items:

```sh theme={null}
xspec review status lockout-change          # overview of all items and counts
xspec review next lockout-change            # serve the first unblocked item
xspec review next lockout-change --json     # same, as a self-contained JSON payload
xspec review show lockout-change item-1     # show a specific item in full
xspec review split lockout-change item-1    # decompose a large block into smaller items
xspec review resolve lockout-change item-1 --status updated --note "confirmed"
xspec review export lockout-change          # full session as JSON
xspec review list                           # list all sessions in the workspace
```

Items with `blocked=true` cannot be resolved until their dependencies are resolved first. `xspec review next` automatically skips blocked items and serves the first one that is ready.

## Full worked session example

```sh theme={null}
$ xspec review create --base HEAD --name lockout-change
created review session 'lockout-change' (path-blocks): 3 item(s)

$ xspec review status lockout-change
item-1 subtree-coherence specs/AUTH.mdx#auth.lockout unresolved blocked=false
item-2 dependency-consistency specs/OVERVIEW.mdx#overview unresolved blocked=false
item-3 parent-consistency specs/AUTH.mdx#auth unresolved blocked=true
totals: unresolved=3 updated=0 no-change=0 skipped=0 invalidated=0

$ xspec review next lockout-change
item item-1
  kind: subtree-coherence
  reason: the subtree rooted at specs/AUTH.mdx#auth.lockout changed...
  scope: specs/AUTH.mdx#auth.lockout (present)
    text: |
      Five consecutive failed attempts lock the account for 30 minutes.
  origin:
  - specs/AUTH.mdx#auth.lockout
    before: present, text: "Five consecutive failed attempts lock the account for 15 minutes."
    after: present, text: "Five consecutive failed attempts lock the account for 30 minutes."

$ xspec review resolve lockout-change item-1 --status updated --note "30-minute confirmed"
$ xspec review resolve lockout-change item-2 --status no-change
$ xspec review resolve lockout-change item-3 --status no-change  # now unblocked
```

After resolving `item-1` (the leaf), `item-3` (the parent) automatically becomes unblocked.

## Scripting the review loop

For automated or agent-driven review passes, use the `--json` flag with `xspec review next` and drive resolution in a loop:

```sh theme={null}
while item=$(xspec review next my-session --json) && \
      [ "$(jq .fullyResolved <<<"$item")" = "false" ]; do
  xspec review resolve my-session "$(jq -r .item.id <<<"$item")" --status no-change
done
```

The `fullyResolved` field becomes `true` once every item in the session has a terminal status, which exits the loop cleanly.

## Operational notes

<Note>
  **Session names** may contain A–Z, a–z, 0–9, `.`, `_`, and `-`. They must not start with `.`.
</Note>

* **Commit your sessions.** Session files are durable — they are not regenerated from sources. Losing them means losing your review history. See [Managing xspec Workspace Files with Git](/workflows/workspace-files) for commit guidelines.
* **Mutating commands are exclusive.** `create`, `resolve`, and `split` mutate session state and cannot run concurrently. `status`, `next`, `show`, and `export` are read-only and safe to run at any time.
* **Journaled renames and moves never invalidate items.** You can freely restructure your specification mid-review — xspec's identity journal ensures resolved items remain valid after a rename or move. See [Renaming and Moving Requirements Safely](/workflows/refactoring).
* **Corrupt sessions exit 1 on every subcommand.** If a session file is damaged or hand-edited, restore it from version control rather than attempting to repair it manually.