Skip to main content
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:

​
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 for background on coverage profiles.

​
Item model and statuses

Each item in a session has a status from the following set:
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.

​
Working a session

Use this set of commands to navigate and resolve items:
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

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:
The fullyResolved field becomes true once every item in the session has a terminal status, which exits the loop cleanly.

​
Operational notes

Session names may contain A–Z, a–z, 0–9, ., _, and -. They must not start with ..
  • 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 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.
  • 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.