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

# xspec review: Staged Review Session Commands

> Reference for xspec review subcommands: create, list, status, next, show, split, resolve, and export — strategies, resolve statuses, and scripting tips.

`review` manages staged review sessions — structured workflows for triaging requirement changes, auditing specs, or verifying coverage. Each session is a persistent file in your workspace that tracks which items have been reviewed and which are still pending.

## Session name rules

Session names may contain `A–Z`, `a–z`, `0–9`, `.`, `_`, and `-`. They must not start with `.`. Session files are stored at `.xspec/reviews/<name>.json`.

Comparisons against session names are byte-wise case-sensitive.

## Subcommands

### create

Create a new review session. You must specify exactly one strategy.

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

<ParamField path="--name" type="string" required>
  The name for the new session. Must follow the session name rules above.
</ParamField>

<ParamField path="--base" type="git-ref">
  Path-blocks strategy. Builds a review queue from requirements whose content changed since the given git ref, traced through the journal.
</ParamField>

<ParamField path="--strategy" type="string">
  Built-in strategy name. Currently only `audit` is supported, which queues every requirement node in the workspace for review.
</ParamField>

<ParamField path="--coverage" type="string">
  Coverage strategy. Builds the queue from uncovered required nodes in the named coverage profile.
</ParamField>

***

### list

List all review sessions in the workspace.

```sh theme={null}
xspec review list
```

***

### status

Show summary counts for a session: total items, resolved, pending, and resolution breakdown.

```sh theme={null}
xspec review status <name>
```

***

### next

Print the next unresolved item in the session queue.

```sh theme={null}
xspec review next <name> [--json]
```

<ParamField path="--json" type="flag">
  Emit the item as a JSON object instead of the human-readable format.
</ParamField>

***

### show

Print the full detail of a specific item by its item ID.

```sh theme={null}
xspec review show <name> <item-id>
```

***

### split

Split one review item into multiple finer-grained items. Useful when a single queue entry covers more ground than can be reviewed in one step.

```sh theme={null}
xspec review split <name> <item-id>
```

Mutating — subject to the workspace concurrency lock.

***

### resolve

Mark an item as reviewed with a resolution status and an optional note.

```sh theme={null}
xspec review resolve <name> <item-id> --status <status> [--note <text>]
```

<ParamField path="--status" type="string" required>
  Resolution status. Accepted values:

  | Value       | Meaning                                                   |
  | ----------- | --------------------------------------------------------- |
  | `updated`   | The requirement was reviewed and changes were made        |
  | `no-change` | The requirement was reviewed and no changes are needed    |
  | `skipped`   | The item is deferred — it remains in the queue as skipped |
</ParamField>

<ParamField path="--note" type="string">
  Optional free-text note to attach to the resolution record.
</ParamField>

Mutating — subject to the workspace concurrency lock.

***

### export

Export the full session as a JSON document. JSON is always emitted for this subcommand — no `--json` flag is needed.

```sh theme={null}
xspec review export <name>
```

The exported document contains the session metadata, strategy, all items with their IDs and source nodes, and all resolution records including statuses and notes.

## Scripting with --json

Use `review next --json` in a loop to process items programmatically:

```sh theme={null}
while true; do
  item=$(xspec review next my-session --json)
  [ $? -ne 0 ] && break          # no more items
  id=$(echo "$item" | jq -r '.id')
  # ... your review logic ...
  xspec review resolve my-session "$id" --status no-change
done
```

## Concurrency

`review create`, `review resolve`, and `review split` are mutating commands and are mutually exclusive per workspace. A second mutating command attempted while one is running exits immediately with code `2`. Non-mutating subcommands (`list`, `status`, `next`, `show`, `export`) can run concurrently.

## Exit codes

| Code | Condition                                                                                  |
| ---- | ------------------------------------------------------------------------------------------ |
| `0`  | Success for all informational subcommands                                                  |
| `1`  | Refused operation (e.g., resolving an already-resolved item); corrupt session (finding 21) |
| `2`  | Unknown session or item ID; invalid flag value; concurrency lock held                      |