Spec Critique

Specification Critique Skill

Overview

Critically review specification documents for accuracy, completeness, and feasibility. Use extended thinking to find issues BEFORE implementation begins.

Core principle: Use extended thinking (deep analysis). Find problems BEFORE implementation.

When to Use

Always:

• After spec writing is complete
• Before implementation planning begins
• When spec involves external integrations
• For complex features with multiple components

Exceptions:

• Simple specs for trivial changes
• Specs already reviewed by another agent

The Iron Law

NO IMPLEMENTATION WITHOUT SPEC CRITIQUE FOR COMPLEX TASKS

Complex tasks (external integrations, multi-service changes) must have spec critique.

Inputs Required

Before critiquing, ensure you have:

1. spec.md - The specification to critique
2. Requirements document - Original user requirements
3. Project context - Tech stack, patterns

Workflow

Phase 1: Load All Context

# Read the spec
cat .claude/context/specs/[task-name]-spec.md

# Read original requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/tech-stack.md

Understand:

• What the spec claims
• What the user originally requested
• What patterns exist in the codebase

Phase 2: Deep Analysis (USE EXTENDED THINKING)

CRITICAL: Use extended thinking for this phase. Think deeply about:

Technical Accuracy

Compare spec against requirements and codebase:

• Package names: Does spec use correct package names?
• Import statements: Do imports match API patterns?
• API calls: Do function signatures match documentation?
• Configuration: Are env vars and config options correct?

Check for common spec errors:

• Wrong package name (e.g., "react-query" vs "@tanstack/react-query")
• Outdated API patterns (e.g., using deprecated functions)
• Incorrect function signatures (e.g., wrong parameter order)
• Missing required configuration (e.g., missing env vars)

Flag any mismatches.

Completeness

Check against requirements:

• All requirements covered? - Each requirement should have implementation details
• All acceptance criteria testable? - Each criterion should be verifiable
• Edge cases handled? - Error conditions, empty states, timeouts
• Integration points clear? - How components connect

Flag any gaps.

Consistency

Check within spec:

• Package names consistent - Same name used everywhere
• File paths consistent - No conflicting paths
• Patterns consistent - Same style throughout
• Terminology consistent - Same terms for same concepts

Flag any inconsistencies.

Feasibility

Check practicality:

• Dependencies available? - All packages exist and are maintained
• Infrastructure realistic? - Setup will work
• Implementation order logical? - Dependencies before dependents
• Scope appropriate? - Not over-engineered, not under-specified

Flag any concerns.

Requirements Alignment

Cross-reference with requirements:

• Verified information used? - Spec should use researched facts
• Unverified claims flagged? - Any assumptions marked clearly
• Gotchas addressed? - Known issues handled
• Recommendations followed? - Requirements suggestions incorporated

Flag any divergences.

Phase 3: Catalog Issues

Create a list of all issues found:

## Issues Found

### 1. [SEVERITY: HIGH] Package name incorrect

- **Spec says**: "[incorrect]"
- **Should be**: "[correct]"
- **Location**: Line 45, Requirements section

### 2. [SEVERITY: MEDIUM] Missing edge case

- **Requirement**: "Handle connection failures"
- **Spec**: No error handling specified
- **Location**: Implementation Notes section

### 3. [SEVERITY: LOW] Inconsistent terminology

- **Issue**: Uses both "memory" and "episode" for same concept
- **Location**: Throughout document

Phase 4: Fix Issues

For each issue found, fix it directly in the spec:

For each fix:

1. Make the change in spec
2. Verify the change was applied
3. Document what was changed

Phase 5: Create Critique Report

# Spec Critique Report

**Spec**: [spec-name]
**Date**: [timestamp]

## Summary

| Category               | Status    | Issues  |
| ---------------------- | --------- | ------- |
| Technical Accuracy     | PASS/FAIL | [count] |
| Completeness           | PASS/FAIL | [count] |
| Consistency            | PASS/FAIL | [count] |
| Feasibility            | PASS/FAIL | [count] |
| Requirements Alignment | PASS/FAIL | [count] |

## Issues Found and Fixed

### High Severity

1. [Issue] - FIXED: [what was changed]

### Medium Severity

1. [Issue] - FIXED: [what was changed]

### Low Severity

1. [Issue] - FIXED: [what was changed]

## No Issues Found (if applicable)

Spec is well-written with no significant issues found.

## Confidence Level

[HIGH/MEDIUM/LOW]

## Recommendations

- [Any remaining concerns or suggestions]

Phase 6: Verify Fixes

After making changes:

# Verify spec is still valid markdown
head -50 .claude/context/specs/[task-name]-spec.md

# Check key sections exist
grep -E "^##? Overview" spec.md
grep -E "^##? Requirements" spec.md
grep -E "^##? Success Criteria" spec.md

Severity Guidelines

HIGH - Will cause implementation failure:

• Wrong package names
• Incorrect API signatures
• Missing critical requirements
• Invalid configuration

MEDIUM - May cause issues:

• Missing edge cases
• Incomplete error handling
• Unclear integration points
• Inconsistent patterns

LOW - Minor improvements:

• Terminology inconsistencies
• Documentation gaps
• Style issues
• Minor optimizations

Category Definitions

• Accuracy: Technical correctness (packages, APIs, config)
• Completeness: Coverage of requirements and edge cases
• Consistency: Internal coherence of the document
• Feasibility: Practical implementability
• Alignment: Match with original requirements

Verification Checklist

Before completing spec critique:

• All sections analyzed with extended thinking
• Technical accuracy verified
• Completeness checked against requirements
• Consistency verified throughout spec
• Feasibility assessed
• All issues cataloged with severity
• All high/medium issues fixed
• Critique report created
• Spec still valid after fixes

Extended Thinking Prompt

When analyzing, think through:

"Looking at this spec, I need to deeply analyze it against the requirements...

First, let me check all package names. The requirements mention [X], but the spec says [Y]. This is a mismatch that needs fixing.

Next, looking at the API patterns. The requirements show initialization requires [steps], but the spec shows [different steps]. Another issue.

For completeness, the requirements mention [X, Y, Z]. The spec covers X and Y but I don't see Z addressed anywhere. This is a gap.

Looking at consistency, I notice '[term1]' and '[term2]' used interchangeably. Should standardize on one term.

For feasibility, the setup seems correct. The configuration matches.

Overall, I found [N] issues that need fixing before this spec is ready for implementation."

Common Mistakes

Surface-Level Review

Why it's wrong: Skimming misses critical issues.

Do this instead: Use extended thinking. Analyze each section deeply.

Reporting Without Fixing

Why it's wrong: Just listing issues doesn't improve the spec.

Do this instead: Fix issues directly. Make the spec better.

Integration with Other Skills

This skill works well with:

• spec-writing: Provides the spec to critique
• complexity-assessment: Helps determine if critique is needed
• debugging: Use if spec critique reveals code issues

Iron Laws

1. NEVER approve a specification that contains contradictions, even minor ones
2. ALWAYS surface hidden assumptions explicitly — they are as important as stated requirements
3. NEVER let scope creep go unquestioned in a spec review
4. ALWAYS validate edge cases and error scenarios before approving
5. NEVER critique implementation approach — focus only on specification completeness and consistency

Anti-Patterns

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md
• Issue found -> .claude/context/memory/issues.md
• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.