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

Deliberation contract

When the readiness checks execute as independent strategies, create a manifest and validate separate receipts with multi-agent-consensus/scripts/deliberation.py. Incomplete coverage cannot produce a ready verdict. An inline review remains valid where selected but is not independent coverage.

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

Buildability Probe Mode

Run this mode when the operator explicitly requests a buildability probe, /impl-spec invokes it, or the target is a profile-backed multi-document spec set. This mode is additive: it does not replace the formal readiness review for a later implementation plan.

Read ../../references/buildability-probe-protocol.md in full. Bind the target folder-contract README and the spec-set manifest. Give a fresh native invoke_subagent conversation only the spec set, shared standards, README, and protocol. Native independence requires agy.agent.execution=passed. A separately isolated sequential probe is allowed only with agy.sequential.isolation=passed and its own execution receipt. Same-context roleplay cannot produce a probe verdict.

The result must use saga.buildability-probe.v1 and include the complete implementation breakdown, all five question categories, per-question boundary classifications, reasoning, the bounded round, and PASS or FAIL. Validate it with:

python3 plugins/saga/scripts/impl_spec.py probe-check <probe-result.json>

PASS requires zero spec-defect questions. Return the structured result to /impl-spec so it can perform class-wide remediation and invoke a fresh probe. Write the human report to docs/reviews/YYYY-MM-DD-<subject>-buildability-probe[-rN].md. Do not expose authoring context, prior probes, remediation notes, transcripts, or machine paths to the fresh probe.

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.

Gemini Review Appliance

When the operator asks for Gemini review, second opinion, adversarial review, or high-risk review, load references/gemini-review-appliance.md. Keep the appliance scoped to that review task only.

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.

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

Canonical artifact promotion

An Antigravity brain or runtime copy is staging only. Before claiming durable documentation-review completion, promote the review into docs/reviews/ with scripts/artifact_promotion.py and bind its promotion receipt to the applicable lifecycle transition. A divergent canonical predecessor is preserved and blocks completion until operator adjudication.

Run the executable receipt path before claiming completion. Read $SAGA_PLUGIN_ROOT/references/live-receipt-commands.md for the closed JSON inputs and full flags.

SAGA_PLUGIN_ROOT="${AGY_PLUGIN_ROOT:-$HOME/.gemini/config/plugins/saga}"
CONSENSUS_PLUGIN_ROOT="$(dirname "$SAGA_PLUGIN_ROOT")/multi-agent-consensus"
test -f "$CONSENSUS_PLUGIN_ROOT/scripts/deliberation.py"
test -f "$SAGA_PLUGIN_ROOT/scripts/transition_receipts.py"
test -f "$SAGA_PLUGIN_ROOT/scripts/artifact_promotion.py"