---
name: doc-review
description: Review Infiquetra plans, requirements, and SDLC documents for implementation readiness.
---

# Doc Review

Use this when a plan, requirements document, strategy document, or formal Infiquetra SDLC
artifact is about to guide implementation.

The core question is:

> Can this document safely drive implementation without the agent inventing missing decisions
> or acting on unverified assumptions?

This is not a copy-editing workflow and it is not a replacement for code review.

## Target Resolution

1. **If a path was supplied, review that document, as given.** An explicit submission is always
   reviewed: never redirect it to a different target, never widen it to a directory, and never
   substitute a document you judge more relevant. A caller who names a path has already made the
   decision this step would otherwise re-make, and a review of the wrong document reads exactly
   like a review of the right one.
2. If no path was supplied, look for an obvious active plan or requirements document under
   `docs/plans/` or `docs/brainstorms/`.
3. If the target is still ambiguous, ask for the document path before reviewing.

Do not create a `/ce-doc-review` alias. The Infiquetra command surface is `/doc-review`.

## Classification

Classify by explicit context first, then evidence. Use this precedence:

1. Explicit user command context, such as "review this spec" or "review this issue".
2. Known SDLC paths or identifiers:
   - Blueprint sections or ADRs -> run the idea-phase rubrics inline in this skill.
   - GitHub issue references or issue-derived documents -> run the issue-phase rubrics
     inline in this skill.
   - Specs under `specs/` or documents with spec-phase metadata -> route to `/spec`,
     which runs the spec-phase rubrics.
3. Content-shape signals:
   - Plan signals: `origin:`, `Implementation Units`, `Key Technical Decisions`, `U1`,
     file lists, test scenarios, verification sections.
   - Requirements signals: goals, non-goals, acceptance examples, flows, success criteria,
     problem framing, `docs/brainstorms/`.
   - Strategy/scope signals: `STRATEGY.md`, strategy updates, founder-scope documents,
     scope or ambition decisions that are about to drive implementation.
4. Path tie-breakers:
   - `docs/plans/` -> plan
   - `docs/brainstorms/` -> requirements
   - `docs/specs/` -> requirements
   - `STRATEGY.md` -> strategy/scope

When classification remains ambiguous, ask before routing. Do not silently guess on a formal
SDLC artifact because routing determines which review responsibilities run.

## Formal SDLC Rubric Review

Formal SDLC artifacts get the Infiquetra rubric review first, run inline via the rubric engine
at `plugins/saga/scripts/lifecycle_review.py` — **a repository-root-relative path, so every
invocation below resolves from any working directory**. The engine finds its own rubrics under
`plugins/saga/references/rubrics/{idea,spec,issue}/{core,extras}/` from its own file location, so
the rubrics were never the fragile part; the invocation was. Map artifact to phase:

- Blueprint sections and ADRs -> `idea` phase.
- GitHub issues and issue-derived documents -> `issue` phase.
- Specifications -> `spec` phase, owned by `/spec`; route there rather than running it here.

For the resolved phase, run the engine like so. **Read each rubric's applicability condition
before deciding whether it applies** — the condition governs the selection, so a selection made
before reading it is a guess wearing a rule's clothes:

1. List the always-apply core rubrics and the conditional extras:
   - `python3 plugins/saga/scripts/lifecycle_review.py rubrics list-cores --phase <idea|issue>`
   - `python3 plugins/saga/scripts/lifecycle_review.py rubrics list-extras --phase <idea|issue>`
2. Read each listed rubric's content, which is where its applicability condition is stated:
   - `python3 plugins/saga/scripts/lifecycle_review.py rubrics read --phase <idea|issue> --slug <slug>`
3. Apply every `core` rubric for the phase. Apply each `extras` rubric whose applicability
   condition — now read — fits the artifact, by judgment.

After the rubric review finishes, run the readiness-skeptic pass. Re-read the target document,
collect any appended review log when present, and include unresolved rubric findings in the
readiness summary. Do not reclassify rubric findings as readiness findings.

**A rubric that cannot be loaded stops the review.** If the engine will not run, or a rubric the
phase requires will not read, say which one and stop — do not continue on the readiness pass
alone and do not substitute a different or weaker rubric for the missing one. This review can
block `/work`, so a run that silently drops a rubric reports success while having removed the
protection it reports: there is no signal an operator could use to tell a thorough review from a
degraded one. Stopping is recoverable; a degraded pass is not.

## Readiness-Skeptic Pass

Always check:

1. **Verification.** Claims, requirements, and actions must be supported by cited evidence,
   the document itself, linked source, or local repository evidence.
2. **Assumptions.** Surface stale, wrong, or unstated assumptions that would affect execution.
3. **Requirement mapping.** Check origin requirements, acceptance criteria, schema requirements,
   implementation units, and gates map correctly. For a plan with an attached issue, whether every
   acceptance criterion has a functional check is decided by the blocking check in the next
   section, not by judgment.
4. **Completeness.** Detect missing fields, schema requirements, gates, decisions, or review
   artifacts the document already implies.
5. **Open-choice pressure.** Flag implementation choices that should be defaults, decisions, or
   explicit evidence-gathering tasks.
6. **Adversarial failure modes.** Ask what breaks if an agent follows the document literally.

Triggered lenses:

- Use security/ops scrutiny when the document touches secrets, authorization, deployment,
  infrastructure, data, or external integrations.
- Suggest `/founder-review` as an additional lens when strategy, product scope, ambition, or
  user-facing behavior is prominent.
- Use deployment readiness scrutiny when the document includes deploy, rollback, release,
  environment, or CI/CD behavior.

## Acceptance-criteria mapping — a blocking check

A plan must prove every acceptance criterion on its issue with a functional check: a test that runs
the change, written in the plan's `functional-checks` blocks or its plan-level `scenario-smoke`
block (the grammar is in `plugins/saga/skills/plan/references/plan-sections.md`). This check applies
when the target classifies as a plan and an issue is attached: `/plan` dispatched the review with
the issue number, or the plan names its issue. Run it:

```bash
python3 plugins/saga/scripts/functional_checks.py map --plan <plan path> --issue <N>
```

- **Exit 1 is not ready.** Report each unmapped criterion as a finding record that names its `AC-<n>`
  and quotes its text, so the repair is "add a check that proves this criterion". The mapping result
  is not a finding the author answers: it is never recorded, and it clears only when the mapping
  passes. A check that cites an `AC-<n>` the issue does not have is reported the same way, and so
  is each malformed check entry the output lists. `AC-<n>` is the criterion's position in the issue's
  `### Acceptance criteria` list, so a renumbered issue shows up here as a mismatch rather than
  passing silently.
- **Exit 0 with status `waived`** means functional testing is waived for this run. Write: functional
  testing is waived for this run (`<level>` level: `<reason>`); the mapping check was skipped. A
  `repository`-level waiver is the operator's, recorded at admission, and is not yours to question
  here. A `run`-level waiver is the Planner's, written in the plan: check that the change carries
  no code and that the waiver states its reason. A run-level waiver on a code-bearing change is a
  finding record, because no role but the operator may waive functional testing for code.
- **Exit 2 stops the review**, as a rubric that cannot be loaded does: the plan or the issue could
  not be read, or the issue has no `### Acceptance criteria` section with items. Say which.
- When no issue is attached, say in one line that the mapping check did not apply.

## Reviewer-session transport

**The operator is the transport.** A reviewer session is launched by the operator or by Orchestrate,
never by this capability: this skill starts no reviewer process by any route, under any name, and a
script that would start one is prohibited whatever it is called — the prohibition is general,
because naming a particular script protects nothing the day someone adds a differently-named
equivalent. `engine-registry.yaml` is **capability metadata and never launch authority**: it
records what an engine can do, not permission to start one. If a requested reviewer is not already
a named unit in the Orchestrate run record, HALT rather than inventing a custom review. This
applies to Plan review reviewers exactly as it does to Code review reviewers.

## Findings

Report remaining findings as C1 finding records (`plugins/saga/references/review-records.md`):
subject `plan` with a `section` location naming the document and section for plans, and the
reviewed document's own subject with its section for requirements, strategy, and issue documents.
Each record carries a one-sentence statement, closed-list labels, and proof — the failing test or
command output when reproduced, the file-and-line steps when traced.

Lead with findings. A short readiness summary is useful, but finding records are the primary
output language.

The reviewer never edits the reviewed document. Inventing acceptance criteria, choosing
architecture without evidence, changing scope on preference, resolving product decisions without
input, and adding requirements the source material does not imply each become a finding, never an
edit — and choosing the test becomes a finding, never an edit, even when the right test is evident.

## Durable Review Artifacts

Write a review artifact under `docs/reviews/` when any trigger is true:

- any finding is recorded
- a formal SDLC rubric review ran
- an issue-attached lifecycle flow is active
- more than three findings remain

Every significant review artifact should include:

- This review-result contract:
- target path
- reviewed revision: **a real commit SHA whenever the reviewed document is committed.** Record
  `working tree` only for a document that is not yet in a commit, and say so in the same line. A
  verdict bound to "working tree" names no revision anyone can return to, so a later reader cannot
  tell whether it covers what was built.
- blocked status
- finding records and the author's answer to each
- review artifact path
- rejections with their reasons, when any
- linked issue, plan, or work-session path when available

**File naming, and what "the latest matching artifact" means.** The `docs/reviews/` corpus uses
two conventions and this skill adds no third:

| Convention | Shape | Example |
|---|---|---|
| Issue- or target-led | `doc-review-<target>-<YYYY-MM-DD>.md` | `doc-review-issue-996-2026-09-19.md` |
| Date-led | `<YYYY-MM-DD>-<topic>.md` | `2026-09-19-operator-gate-status-card-readiness.md` |

"The latest matching artifact" for a document is: among the artifacts whose review-result contract
names that document's path as its target, the one with the most recent date in its own filename;
where two share that date, the one written later in the file's own recorded order. Resolve by the
**recorded target path**, never by guessing from the filename's topic words.

**When the two conventions disagree about which artifact is latest, surface it as a finding rather
than picking one.** An ambiguity resolved silently is a review bound to a revision nobody chose.

Ignored local state under `.claude/saga/` is not durable review output.

## One pass, and how `/work` reads its result

**`/doc-review` is dispatched, not requested.** `/plan` Phase 5.4 runs this review itself at the
end of planning; `/work` does not ask whether to run it, because by the time `/work` starts it
has already run. A caller may still invoke it directly on any document, and
that invocation is reviewed as given (see "Target Resolution").

**One pass is one completed review result followed by the author's answers.** The author answers
every finding through `plan_review.py answer` — fixed with the section changed, or rejected with a
reason — and the pass is complete when `plan_review.py check` exits 0. There is no second pass, no
cycle allowance, and no override.

**Bind the verdict to the revision you read.** A document amended after this review ruled is
amended at a revision this review did not read — name the revision you read, so a later reader can
tell. For a plan, the amendment is an answer the author records through `plan_review.py answer`,
fixed with the section changed, not a second review.

If any finding is unanswered, or the acceptance-criteria mapping fails, `/work` blocks on the
check. `/work` reads the result from the run record's `review_cycles` first, then same-session
output, then the latest matching `docs/reviews/` artifact. The check's printout is what an
attending operator sees; rejections travel with their reasons into the issue's progress comment.

For issue-attached work, summarize:

- answers given
- rejections with reasons
- blocked status
- review artifact link

## Output Shape

The generated readiness report and the `docs/reviews/` artifact follow the shared formatting contract
in `saga/references/formatting-style.md`: lead the readiness
summary and each section with a one-line plain-language verdict, render the findings as a
table (one row per finding record, with its statement, section, and answer), and keep narrative fields as short
(≤3-sentence) blank-line-separated prose.

Use this structure:

1. Readiness summary.
2. Findings, one row per finding record.
3. Review artifact path, when written.
4. Residual risk from limited evidence, if any.

If no issues are found, say so clearly and name any remaining risk from limited evidence.

## Continue, or return the result

**A review ends by doing the next thing, not by naming it** (issue #1029). Which next thing depends
on who asked, and there are exactly two answers.

**Dispatched by `/plan`'s one pass.** Return the result to §5.4 and stop. `/plan` §5.4 owns
the answers and the check; a review that continued on its own from inside that pass would run the
build in the middle of it.

**Invoked standalone.** Continue into `/work` against the reviewed document in the same turn when
**all three** hold:

1. the document classified as a **plan** (Classification above, or the `docs/plans/` tie-breaker);
2. the review was standalone rather than dispatched by `/plan`; and
3. **the reviewed plan's check exits 0** after the answers.

If any one of the three does not hold, continue into nothing and report. In particular a strategy,
requirements, issue, or blueprint document continues into nothing, because `/work` has no plan to
execute and pointing it at one of those is worse than stopping. An unanswered finding or a failing
mapping continues into nothing either: the readiness gate `/work` enforces is the same check this
review just ran, and a review that walked past its own gate would be no gate at all. Say which of
the three stopped the continuation.

**Continuation never converts a confirmed action into an automatic one.** `/work`'s pull-request
open, review-request, and merge remain explicitly operator-confirmed; a continuation that would
fire one of them without a confirmation is a stop.