review-spec

A route has arrived — a spec about to guide /skill:to-tickets, or a set of tickets about to guide /skill:implement — through the terrain. Before anyone traverses it, inspect the route. A route that reads complete rarely is: claims drift from their ground truth, sources contradict each other silently, and acceptance criteria cover three dimensions when the traverse will touch five. This skill finds those gaps and forces them closed.

Process

1. Locate the route. A file path, a tracker issue, or content the user supplies. Read it fully. Identify the route type: a spec (traverse = /skill:to-tickets) or a set of tickets (traverse = /skill:implement). The type shifts Check 3 and Check 5; Checks 1, 2, 4 are route-agnostic.

   Ticket routes: review only the frontier. The frontier is the open, unblocked (all blockers closed), unclaimed tickets — the edge ready to implement now. Blocked tickets' content may change before they become implementable, so reviewing them wastes the inspect round on a route that will shift. If the frontier is a single ticket, inspect that one; if several, inspect them together as one route.

2. Gather the terrain data. The wayfinder map and its tickets — closed decisions, research outputs, prototype results. The project's ADRs, CONTEXT.md, and the codebase the route proposes to traverse. Fetch ticket bodies and resolution comments; read prototype outputs and research docs the route cites or depends on. Done when: every source the route cites or depends on is read, and its path is listed for the sub-agents.

3. Verify the review agent, then spawn five sub-agents in parallel. Before spawning, confirm the agent you will use actually exists and fits a document-review task (not a code-diff review task):

   • Before the first dispatch, load the pi-subagents skill once (read its SKILL.md and references/execution-controls.md) — it holds the verified runs.run(key, { agent, task }) / runs.all signatures and the workflowScript pitfalls (task text never inside nested template literals). Do not write the dispatch script from memory.
   • Run subagent({ action: "list" }) to confirm doc-reviewer is registered. Agents get added, renamed, or reconfigured between sessions — confirm fresh each run.
   • Read doc-reviewer's config (~/.pi/agent/agents/doc-reviewer.md) and verify its acceptance is disabled and its tools read-only. A code-review agent's checked acceptance gates forever on a document route that produces no diffs.
   • If doc-reviewer is missing or misconfigured, fall back to delegate (no default acceptance), noted in the report — reviewer is code-diff-only and will be acceptance-gated, so it is never a valid fallback here.

   Each sub-agent gets: the route (path or full text), the route type, every terrain-source path it should cross-check against, and the check's body as its brief. For Check 3 and Check 5, pass only the branch matching the route type. Use runs.all with five children, agent: "doc-reviewer", context: 'fresh' each. List every terrain-source path explicitly in each sub-agent's task text — sub-agents have context: 'fresh' and see only what you pass them, so a bare "the terrain sources" with no paths leaves them blind.

4. Aggregate the five reports. Present each check's report under its own heading, verbatim or lightly cleaned — the five axes are separate, so each stays on its own heading. The runs.all return value already carries each child's .output — read it directly from the resolved array; do not find/read sub-agent session files to locate outputs.

5. Classify every gap by the wayfinder ticket type it routes to (see Gap classification).

6. Report per check, then the classification table, then a verdict. On Held, run the Challenger round, then route — see Routing.