Agent skill
implementation-plan-reviewer
Use when reviewing implementation plans before execution, especially plans derived from design documents
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/other/implementation-plan-reviewer
SKILL.md
Invariant Principles
-
Parallel agents hallucinate incompatible interfaces when contracts are implicit. Every handoff point between work streams must specify exact data shapes, protocols, error formats.
-
Assumed behavior causes debugging loops. Plans referencing existing code must cite source, not infer from method names. Parameters like
partial=Trueorstrict=Falseare fabricated until verified. -
Implementation plans must exceed design doc specificity. Design says "user endpoint"; impl plan specifies method, path, request/response schema, error codes, auth mechanism.
-
Test quality claims require verification. Passing tests prove nothing without green-mirage-audit. Test failures require systematic-debugging, not ad-hoc fixes.
Inputs
| Input | Required | Description |
|---|---|---|
| Implementation plan | Yes | Document specifying work items, phases, interfaces |
| Parent design doc | No | Source design document (if exists, higher confidence) |
| Codebase access | Yes | Ability to verify behavior claims against source |
Outputs
| Output | Type | Description |
|---|---|---|
| Review summary | Inline | Interface/behavior counts, escalation list |
| Critical findings | Inline | Blocking issues with location, problem, required fix |
| Remediation plan | Inline | Prioritized list of fixes before execution |
Review Protocol
Phase 1: Inventory
| Element | Check |
|---|---|
| Parent design doc | EXISTS / NONE (if none: higher risk, explicit justification needed) |
| Work items | Count sequential vs parallel |
| Interfaces between parallel tracks | List ALL cross-track handoffs |
| Setup/skeleton work | Must complete before parallel execution |
Phase 2: Interface Contract Audit
For EACH interface between parallel work:
Interface: [A] <-> [B]
Contract location: [section/line or MISSING]
Request format: SPECIFIED / MISSING
Response format: SPECIFIED / MISSING
Error format: SPECIFIED / MISSING
Protocol: SPECIFIED / MISSING
If ANY missing: Flag as CRITICAL. Agents will produce incompatible code.
Phase 3: Behavior Verification Audit
Flag as RED when plan:
- Assumes convenience parameters (
partial=True,strict=False) without source citation - Infers behavior from method names without reading implementation
- Describes "try X, if fails try Y" (signals unverified behavior)
- Claims test utility behavior without source reference
Require: "Behavior verified at [file:line]. Actual signature: [sig]. Constraints: [list]."
Phase 4: Completeness Checks
| Category | Required |
|---|---|
| Definition of done per work item | Testable, measurable, pass/fail clear |
| Risk assessment per phase | Identified + mitigations + rollback points |
| QA checkpoints | Test types, pass criteria, failure procedure |
| Skill integrations | green-mirage-audit after tests pass; systematic-debugging on failures |
| Agent responsibility matrix | Inputs, outputs, interfaces owned |
Phase 5: Escalation
Claims requiring fact-checking skill (do NOT self-verify):
- Security claims ("sanitized", "cryptographically random")
- Performance claims ("O(n)", "optimized", "cached")
- Concurrency claims ("thread-safe", "atomic")
- Test utility behavior claims
If NO to any: incomplete review. Continue.
Output Format
## Summary
- Interfaces: X total, Y fully specified, Z MISSING (must be 100%)
- Behavior verifications: A verified, B assumed (assumed = CRITICAL)
- Claims escalated to fact-checking: N
## Critical Findings (blocks execution)
**Finding N: [Title]**
Location: [section/line]
Problem: [what's missing or wrong]
What agent would guess: [specific decisions left unspecified]
Required: [exact addition needed]
## Remediation Plan
Priority 1 (interface contracts): [list]
Priority 2 (behavior verification): [list]
Priority 3 (QA/testing): [list]
Fact-checking required: [list claims with depth: SHALLOW/MEDIUM/DEEP]
Forbidden
Self-Check
Before completing:
- Every interface between parallel work streams has complete contract specification
- All existing code behavior claims cite file:line, not method name inference
- Fabricated parameters and try-if-fail patterns flagged with remediation
- Every finding includes exact location and specific required addition
- Remediation plan is prioritized and actionable
If ANY unchecked: STOP and complete the audit.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?