doc-review

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, implementation-spec folder, 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 the user supplied a path, read that document.
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.
   • Multi-document implementation spec folders under platform-specs/06-* -> use buildability-probe mode when the target profile defines exact probe inputs and pass criteria.
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 ../../scripts/lifecycle_review.py (relative to this skill) against the rubrics under saga/references/rubrics/{idea,spec,issue}/{core,extras}/. 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:

1. List the always-apply core rubrics and the conditional extras:
   • python3 ../../scripts/lifecycle_review.py rubrics list-cores --phase <idea|issue>
   • python3 ../../scripts/lifecycle_review.py rubrics list-extras --phase <idea|issue>
2. Apply every core rubric for the phase. Apply each extras rubric only when its applicability condition fits the artifact, by judgment.
3. Read each selected rubric's content and apply it to the document:
   • python3 ../../scripts/lifecycle_review.py rubrics read --phase <idea|issue> --slug <slug>

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.

If the rubric engine or its rubrics are unavailable, say so clearly and continue with the readiness review where safe.

Buildability-Probe Mode

Use buildability-probe mode for a profile-backed, multi-document implementation spec set that is about to drive a build. Normal readiness review is still the right gate for single docs, plans, requirements, issues, and strategy.

The probe is a fresh-context cold-builder simulation. Do not run it inline in the same context that authored or remediated the spec. Prefer verified-workflow delegated mode when it can provide a clean review context; otherwise tell the operator that a new session is required for the probe to be valid.

Probe inputs are profile-owned. For the service-implementation profile, pass only:

• the service folder set;
• platform-specs/05-technical-specifications/;
• accepted ADRs from the target library's ADR index;
• PRD-0001 when present;
• the target library's acceptance matrix when present.

Do not add authoring notes, prior probe artifacts, remediation notes, or unrelated repo memory to the probe input set.

The probe artifact must include:

1. implementation breakdown: repos, stacks, endpoints, tables, events, and test plan;
2. exhaustive assumptions and questions by category: product, architecture, data, API, operations;
3. per-question boundary-test classification;
4. VERDICT: PASS only when there are zero spec defects.

Boundary test: if two reasonable implementers could answer a question differently and the difference is visible in API behavior, data shape, or user experience, it is a spec defect. Otherwise it is an execution-time discovery.

Write probe artifacts under docs/reviews/YYYY-MM-DD-<target>-buildability-probe[-rN].md. A failed probe maps boundary-test defects to P0/P1 findings and blocks /plan or /work unless the operator explicitly overrides with a rationale. Remediation closes the defect class across the folder set; it does not patch only the cited line. After remediation, run a fresh probe. Escalate after three failed rounds.

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

External-reviewer panel (opt-in)

For a high-stakes artifact you may add cross-family adversarial depth by dispatching the cross-family-review-panel composing role from the external-engine registry (../../references/engine-registry.yaml, R16; dispatch policy in ../../references/engine-dispatch.md). This is opt-in, never automatic — invoke it only when the operator asks for a cross-engine pass or the artifact clearly warrants one.

• Expand the role with engine_resolver.resolve_role("cross-family-review-panel", registry=...); each external member (Gemini Pro/Flash via agy) is dispatched with its own prompting protocol. The native Codex reviewer remains the root verifier and never enters the external registry.
• If engine_resolver.panel_halt(...) returns a reason, a member is unavailable — halt the panel and surface it rather than substituting the host agent for the missing reviewer (R17): the host reviewing its own family defeats the purpose.
• Every finding is advisory (R15). The host driving session verifies each one against the document or repo source before adopting it; the gated readiness verdict stays the host's alone (R13). Nothing an external engine returns blocks or persists a gate on its own say-so. On the Codex host, Claude-only autonomous panel surfaces (Workflow/TeamCreate) are negative-gated — dispatch runs inline/serially.

External Harness

Use an external engine only after the operator chooses the exact registry route and context. Build one closed saga.harness.request.v1 request and run python3 plugins/saga/scripts/external_action_adapters.py --request <json> --repo-root .. Doc-review calls use mode=direct and an empty write_set. Codex accounts for and independently verifies every advisory finding before its own readiness verdict.

Safe In-Place Fixes

Safe fixes are enabled by default and edit the reviewed document in place.

Safe means the document itself, linked source, or local repository evidence clearly supports the change. Examples:

• add missing schema fields already implied elsewhere in the document
• correct origin requirement mappings when the right mapping is evident
• move follow-up work out of canonical schema and into prose or runbook sections
• fill in gates or checklist items already required by the surrounding section
• fix stale internal references, broken headings, wrong counts, or inconsistent naming

Unsafe changes become findings instead of edits:

• inventing acceptance criteria
• choosing architecture without evidence
• changing scope based on preference
• resolving product decisions without user input
• adding requirements not implied by source material

Findings

Report remaining findings using priorities:

• P0: The document would cause unsafe, incorrect, destructive, or materially wrong execution.
• P1: The document is not ready to drive implementation because a core assumption, mapping, requirement, default, or gate is missing or wrong.
• P2: The document can probably drive work, but the issue creates meaningful rework, ambiguity, or review risk.
• P3: Nice-to-fix clarity, maintainability, or polish issue.

Lead with findings. A short readiness summary is useful, but P-level findings are the primary output language.

Durable Review Artifacts

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

• any P0 or P1 finding remains
• any safe fix edits the document
• a formal SDLC rubric review ran
• an issue-attached lifecycle flow is active
• more than three findings remain after safe fixes

Every significant review artifact should include:

• This review-result contract:
• target path
• reviewed revision when available, such as a commit SHA or explicit "working tree"
• blocked status
• finding priorities and statuses
• applied fixes
• review artifact path
• override rationale when applicable
• linked issue, plan, or work-session path when available

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

Loop And Work Integration

/doc-review is explicit by default. /work should ask whether to run it before executing from a plan or requirements document.

If /doc-review runs and unresolved P0 or P1 findings remain, /work blocks unless the user explicitly overrides. /work may consume same-session review output or the latest matching docs/reviews/ artifact. Overrides need a rationale that can be carried into issue progress or work-session notes.

For issue-attached work, summarize:

• fixes applied
• remaining findings
• blocked status
• override rationale, when present
• 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 by-priority findings as a table (one row per finding, with its P0-P3 priority and status), and keep narrative fields as short (≤3-sentence) blank-line-separated prose.

Use this structure:

1. Applied fixes, if any.
2. Readiness summary.
3. Remaining findings by priority.
4. Review artifact path, when written.
5. Residual risk from limited evidence, if any.

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