Claude Code Plugins

Community-maintained marketplace

Feedback

spec-review

@c-daly/dotclaude
0
0

This skill should be used to validate a design spec before implementation begins. Use when the orchestrator invokes the spec-review phase (after design, before implement) or when you need to verify a spec is implementation-ready.

Install Skill

1Download skill
2Enable skills in Claude

Open claude.ai/settings/capabilities and find the "Skills" section

3Upload to Claude

Click "Upload skill" and select the downloaded ZIP file

Note: Please verify skill by going through its instructions before using it.

SKILL.md

name spec-review
description This skill should be used to validate a design spec before implementation begins. Use when the orchestrator invokes the spec-review phase (after design, before implement) or when you need to verify a spec is implementation-ready.

Phase: Spec Review

Purpose

Validate the design spec before any code is written. Catch spec quality issues and practical implementation gaps while changes are still cheap.

Process

1. Locate the Spec

Find the approved design spec:

  • Location: docs/plans/YYYY-MM-DD-<topic>-design.md
  • Must have been approved in the Design phase checkpoint

If spec not found, escalate: "Design spec not found. Expected file matching pattern YYYY-MM-DD-*-design.md in docs/plans/"

2. Checklist Validation

Evaluate the spec against each quality criterion. For each item, record PASS or FAIL with specific evidence.

Checklist:

Criterion What to Check
No pronouns without referents Search for "it", "this", "that" - each must have clear antecedent
No vague quantities No "multiple", "several", "many" without specific numbers or ranges
No implied behavior Every behavior explicitly stated; nothing left to "obvious" interpretation
Concrete examples Each behavior has at least one input/output example
Explicit edge cases Empty input, null, errors, boundaries all addressed
Defined interfaces Function signatures, types, API shapes written out
Testable success criteria Each criterion can be verified with a specific test

Output format:

## Checklist Validation

| Criterion | Status | Evidence |
|-----------|--------|----------|
| No pronouns without referents | PASS/FAIL | "<quote>" or "MISSING: <what>" |
| No vague quantities | PASS/FAIL | ... |
| No implied behavior | PASS/FAIL | ... |
| Concrete examples | PASS/FAIL | ... |
| Explicit edge cases | PASS/FAIL | ... |
| Defined interfaces | PASS/FAIL | ... |
| Testable success criteria | PASS/FAIL | ... |

**Checklist Result:** X/7 passed

3. Implementer Dry-Run

Review the spec from an implementer's perspective. For each behavior, mentally trace the implementation:

For each behavior in the spec:

  1. Identify the target file(s) from "Files Affected"
  2. Ask: "To implement this, I would..."
  3. Note any gaps:
    • Unclear location: "Where exactly does this code go?"
    • Missing interface: "What type is this parameter?"
    • Flow gap: "What happens between X and Y?"
    • Implicit dependency: "This requires Z which isn't mentioned"

For each edge case:

  1. Trace the error handling path
  2. Verify the spec is specific enough to implement

Output format:

## Implementer Dry-Run

### Behaviors Traced
| Behavior | Target File | Implementable? | Gaps |
|----------|-------------|----------------|------|
| <name> | <path> | YES/NO | "<gap>" or "None" |

### Questions for Spec Author
1. <specific question>
2. ...

### Implicit Dependencies Found
- <dependency not in spec>
- ...

**Dry-Run Result:** READY / NEEDS CLARIFICATION (N questions)

4. Determine Status

Combine results to determine overall status:

Checklist Dry-Run Status
7/7 pass READY APPROVED
Any fail Any NEEDS REVISION
7/7 pass Questions exist NEEDS REVISION

5. Write Review Results

Write combined results to docs/scratch/<task>/spec-review.md

Checkpoint

Present the spec review summary to the user:

## Spec Review Checkpoint

**Status:** APPROVED / NEEDS REVISION

### Summary
- Checklist: N/7 passed
- Dry-run: N behaviors traced, M questions, K implicit dependencies

### Issues Requiring Resolution (if NEEDS REVISION)
1. [CHECKLIST] <criterion>: <issue>
2. [DRY-RUN] <question>
...

### Recommendation
- **If APPROVED:** "Spec validated. Proceed to implementation."
- **If NEEDS REVISION:** "Return to design phase to address N issues before implementation."

After checkpoint:

  • APPROVED: Proceed to Implement phase
  • NEEDS REVISION: Return to Design phase with specific issues to address
  • User overrides NEEDS REVISION: Record "Approved with known issues: ", proceed to Implement

Escalation

  • Spec file not found or malformed
  • Spec has fundamental structural problems (missing required sections)
  • User and spec author disagree on whether an issue needs resolution