Agent Skills: reviewing-impl-plans

Every gap you miss becomes hours of wasted work downstream. Agents will execute this plan trusting your review caught the problems. That trust is earned by thoroughness, not speed. Your career-defining reviews prevent catastrophic integration failures before they happen. </ROLE>

<CRITICAL_INSTRUCTION> This review protects against implementation failures from underspecified plans.

You MUST:

1. Compare plan to parent design document (if exists)
2. Verify every interface between parallel work streams is explicitly specified
3. Identify every point where executing agents would have to guess or invent
4. Verify existing code behaviors cite source, not method name inference

An implementation plan that sounds organized but lacks interface contracts creates incompatible components. </CRITICAL_INSTRUCTION>

Invariant Principles

1. Parallel agents hallucinate incompatible interfaces when contracts are implicit. Every handoff point must specify exact data shapes, protocols, error formats.

2. Assumed behavior causes debugging loops. Plans referencing existing code must cite source, not infer from method names. Parameters like partial=True or strict=False are fabricated until verified.

3. Implementation plans must exceed design doc specificity. Design says "user endpoint"; impl plan specifies method, path, request/response schema, error codes, auth mechanism.

4. Test quality claims require verification. Passing tests prove nothing without auditing-green-mirage. Test failures require systematic-debugging, not ad-hoc fixes.

Inputs

| Input | Required | Description | |-------|----------|-------------| | impl_plan | Yes | Path to or content of the implementation plan to review | | design_doc | No | Path to parent design document for comparison | | codebase_root | No | Project root for verifying existing code behavior references |

Phase 1: Context and Inventory

Dispatch subagent with review-plan-inventory command. If command unavailable, execute phase criteria directly.

Establishes context: parent design doc comparison, work item counts, parallel vs sequential classification, setup/skeleton work requirements, interface inventory between parallel tracks.

Gate: Proceed only when inventory is complete and all work items are classified.

Phase 2: Interface Contract Audit

Dispatch subagent with review-plan-contracts command. If command unavailable, execute phase criteria directly.

Audits every interface between parallel work streams: request/response/error formats, type/schema contracts, event/message contracts, file/resource contracts.

Optional deep audit: For task descriptions with ambiguous language, run /sharpen-audit (the sharpening-prompts skill) on the task text to get executor-prediction analysis (what an implementing agent would guess for each ambiguity).

Gate: Proceed only when every interface has been audited.

Phase 3: Behavior Verification Audit

Dispatch subagent with review-plan-behavior command. If command unavailable, execute phase criteria directly.

Verifies all references to existing code cite verified source behavior, not assumptions from method names. Flags fabrication anti-patterns, dangerous assumption patterns, and loop detection red flags.

Gate: Proceed only when every existing interface reference has been classified as VERIFIED or ASSUMED.

Phase 4-5: Completeness Checks and Escalation

Dispatch subagent with review-plan-completeness command. If command unavailable, execute phase criteria directly.

Verifies definition of done per work item, risk assessment per phase, QA checkpoints with skill integrations, agent responsibility matrix, and dependency graph. Escalates claims requiring fact-checking skill.

Gate: Proceed only when completeness audit is done and all escalation claims are cataloged.

Re-Review Protocol (round 2 and later)

When this skill runs on a plan it has reviewed before:

1. Delta-only verification. Re-verify ONLY claims, citations, and sections changed since the last verified pass. Record the prior pass's verified set and diff against it. A full-corpus re-verification is permitted only on the first pass, or when the prior pass's record is lost. Re-verifying an unchanged, previously-verified citation is duplicated work, not added rigor.
2. Convergence check. Before scheduling round N+1, classify round N's Critical findings: NEW (pre-existing defect newly found) vs INDUCED (introduced by round N-1's own repairs). If more than half are INDUCED, another same-style round is FORBIDDEN. Switch method: build or extend a mechanical check (a compile check, a symbol-table diff) for the oscillating defect class, run it, and only then resume prose review for what the check cannot cover.
3. Record in the report: Round N: X new / Y induced. Convergence: CONVERGING | OSCILLATING (mechanized: <check name>).

Report Assembly

Assemble the final report from subagent outputs.

The templates — the Summary block, the finding format for Critical/Important/Minor, and the prioritized Remediation Plan — are specified in the review-plan-completeness command, which owns report assembly.

Surface-Level Reviews

• "Plan looks well-organized"
• "Good level of detail"
• Accepting vague interface descriptions
• Skipping interface contract verification

Vague Feedback

• "Needs more interface detail"
• "Consider specifying contracts"
• Findings without exact locations
• Remediation without concrete specifications

Parallel Work Assumptions

• Assuming agents will "coordinate"
• Assuming interfaces are "obvious"
• Assuming data shapes can be "worked out" </FORBIDDEN>

The Interface Behavior Fabrication anti-pattern — assumed method behavior, invented parameters, uncited library claims, "try X, if fails try Y" — is cataloged in the review-plan-behavior command, which audits for it.

[ ] Did I compare to parent design doc (if exists)? [ ] Did I verify impl plan has MORE detail than design doc? [ ] Did I classify every work item as parallel or sequential? [ ] Did I identify all setup/skeleton work? [ ] Did I inventory EVERY interface between parallel work? [ ] Did I verify each interface has complete contracts (request/response/error/protocol)? [ ] Did I verify Type/Schema contracts are complete? [ ] Did I verify Event/Message contracts are complete? [ ] Did I verify File/Resource contracts are complete? [ ] Did I verify existing interface behaviors cite source, not method name inference? [ ] Did I flag fabricated parameters and try-if-fail patterns? [ ] Did I identify claims requiring fact-checking escalation? [ ] Did I check definition of done for each work item? [ ] Did I verify risk assessment exists for each phase? [ ] Did I verify QA checkpoints exist with pass criteria? [ ] Did I check for auditing-green-mirage and systematic-debugging integration? [ ] Did I build the agent responsibility matrix? [ ] Did I verify dependency graph and check for circular dependencies? [ ] Does every finding include exact location? [ ] Does every finding include specific remediation? [ ] Did I separate Critical/Important/Minor findings? [ ] Did I provide prioritized remediation plan? [ ] Could parallel agents execute without guessing interfaces OR behaviors? [ ] If round 2+: did I verify only the delta, and run the convergence check?

If NO to ANY item, go back and complete it. </reflection>

<CRITICAL_REMINDER> The question is NOT "does this plan look organized?"

The question is: "Could multiple agents execute this plan IN PARALLEL and produce COMPATIBLE, INTEGRABLE components?"

For EVERY interface between parallel work, ask: "Is this specified precisely enough that both sides will produce matching code?"

If you can't answer with confidence, it's under-specified. Find it. Flag it. Specify what's needed.

Parallel work without explicit contracts produces incompatible components. This is the primary failure mode. Hunt for it relentlessly. </CRITICAL_REMINDER>

<FINAL_EMPHASIS> Your review is the last line of defense before agents invest hours of work. Miss a gap, and multiple agents produce incompatible code. Catch every gap, and the integration is seamless. There is no middle ground. Thoroughness is not optional. </FINAL_EMPHASIS>