Spec Review

Spec Review: Critique & Iterate

Validate generated specifications, provide critical analysis, and collect user feedback.

Purpose

This skill provides the human feedback loop for feature specifications:

1. Validate spec completeness (automated)
2. Critique quality (automated)
3. Present findings to user
4. Iterate based on feedback

Workflow

Phase 1: Validate Structure

Run automated validation to catch errors early:

Bash: python3 ~/.claude/skills/spec-plan/scripts/validate_spec.py /path/to/job-queue/feature-{name}

Checks performed:

• ✅ All required files exist (FRD, FRS, GS, TR, task-list)
• ✅ Files not empty (> 100 bytes)
• ✅ Gherkin syntax valid
• ✅ Task list has actionable items
• ✅ .gitignore includes /job-queue
• ✅ Cross-references consistent

Output: JSON with errors, warnings, completeness score

Phase 2: Critique Quality

Run automated critique for quality analysis:

Bash: python3 ~/.claude/skills/spec-plan/scripts/critique_plan.py /path/to/job-queue/feature-{name}

Analysis performed:

• Requirement Quality:

  • Are requirements specific or vague?
  • Are acceptance criteria measurable?
  • Are edge cases covered?

• Task Breakdown:

  • Are tasks atomic and actionable?
  • Is sequencing logical?
  • Are dependencies identified?

• Technical Design:

  • Are APIs well-defined?
  • Are data models complete?
  • Are error scenarios handled?
  • Are security concerns addressed?

• Testability:

  • Can Gherkin scenarios be automated?
  • Are test data requirements clear?

Output: JSON with critique score, critical issues, warnings, recommendations

Phase 2b: Judge-Panel Deep Critique (optional)

critique_plan.py is fast but coarse: several of its checks are file-level, not per-requirement — e.g. _check_acceptance_criteria looks for an "Acceptance Criteria" heading and one measurable value anywhere in the file, so one well-specified requirement can mask two adjacent requirements that have no acceptance criteria at all. See skills/spec-review/evals/fixtures/weak-spec-standard/ for a worked, planted-gap example of exactly this failure mode.

For a spec that is about to gate real implementation work, run the deeper judge-panel workflow (workflows/spec-review-judge-panel.js, FRS FR-15 / Task 16 of feature-graph-orchestration):

Workflow({
  scriptPath: '~/.claude/workflows/spec-review-judge-panel.js',
  args: { feature_path: '/path/to/job-queue/feature-{name}', tier: '<tier from Phase 1>' },
})

What it does: three independent critique agents read the spec from distinct angles (completeness, testability, over-specification), a panel of judges scores every angle against the whole critique set, and one synthesis node writes a final report starting from the winning angle and grafting the runners-up's best distinct points. It stays tier-aware throughout — it validates only against the tier's own expected deliverables (mirroring validate_spec.py's quick/standard/full file sets), so a quick-tier spec missing FRS/GS/TR is never treated as a defect.

When to reach for it vs the single-pass critique above:

The judge panel is additive, not a replacement — run Phase 2 first regardless; it is much cheaper and catches most structural problems before spending agents on a deeper pass.

Phase 3: Present Findings

Summarize validation and critique results for user:

If Validation FAILED (errors found):

⚠️ Spec Validation Failed

Critical Errors:
- [List errors from validation tool]

Warnings:
- [List warnings]

Completeness Score: [X%]

Action Required:
These issues must be fixed before proceeding. Would you like me to:
1. Fix these issues automatically
2. Re-run spec-writer agent with corrections
3. Guide you to fix them manually

If Validation PASSED but Critique Found Issues:

✅ Spec Structure Valid

Quality Analysis (Score: [X%]):

Critical Issues:
- [File] - [Issue] → Suggestion: [fix]

Warnings:
- [File] - [Issue] → Suggestion: [improvement]

Recommendations:
- [List recommendations]

---

The specs are structurally valid but have quality concerns.
Would you like me to iterate on these issues?

If Everything PASSED:

✅ Spec Validation Passed
✅ Quality Critique Passed (Score: [X%])

Generated Specifications:
📁 /job-queue/feature-{name}/docs/
  ├── FRD.md - Business requirements ✅
  ├── FRS.md - Functional specs ✅
  ├── GS.md - Gherkin scenarios ✅
  ├── TR.md - Technical requirements ✅
  └── task-list.md - Development tasks ✅

Completeness: [X%]
Quality Score: [X%]

Minor Recommendations:
- [Optional improvements]

Ready to proceed with development?

Phase 4: Collect User Feedback

Ask the user for their assessment:

Questions:

1. Are these specifications acceptable?
2. Any changes or clarifications needed?
3. Should I iterate on any specific areas?

User Options:

A) Approve Specs → Mark as complete, ready for development

B) Request Changes → Collect specific feedback, re-run spec-writer agent with updates

C) Manual Edits → User will edit files directly, re-run validation after

D) Focus on Specific Area → Re-run critique with --focus on specific concerns

Phase 5: Iterate if Needed

If user requests changes:

1. Collect specific feedback:

   • Which documents need changes?
   • What's missing or incorrect?
   • Any new requirements?

2. Re-run spec-writer agent:

   Task tool with subagent_type="spec-writer"
   
   Prompt: "Update feature specifications based on feedback:
   
   **Previous Specs:** /job-queue/feature-{name}/docs/
   
   **User Feedback:**
   [List specific changes requested]
   
   **Focus Areas:**
   [Which documents to update]
   
   Please update the specifications addressing this feedback."
   

3. Re-run validation and critique:

   • Validate structure again
   • Critique quality again
   • Present updated findings

4. Repeat until approved

Tools Used

Python Scripts

1. validate_spec.py - Structural validation

   • File existence and completeness
   • Gherkin syntax
   • Cross-references

2. critique_plan.py - Quality critique

   • Requirement clarity
   • Task quality
   • Technical completeness
   • Testability

Workflow

3. workflows/spec-review-judge-panel.js - Optional judge-panel deep critique (Phase 2b above): N distinct-angle critiques, parallel judges, grafted synthesis, tier-aware throughout.

Decision Tree

Start → Run Validation
  ├─ Errors? → Present errors → User fixes → Re-validate
  └─ Valid → Run Critique
      ├─ Critical Issues? → Present issues → User decides
      │   ├─ Iterate → Re-run agent → Re-validate
      │   └─ Accept → Done
      └─ No Critical Issues → (optionally) Run judge panel → Present summary → User approves → Done

Expected Outcomes

After this skill completes:

1. ✅ Specs validated for structure
2. ✅ Specs critiqued for quality
3. ✅ Findings presented to user
4. ✅ User feedback collected
5. ✅ Specs iterated if needed
6. ✅ Final specs approved by user

Next Steps

Once specs are approved:

1. Update Memory Bank:

   /memorybank sync
   

2. Begin Development:

   • Follow task-list.md
   • Reference TR.md for technical details
   • Use GS.md for test scenarios

Important Notes

• Human-in-loop: User approval required before proceeding
• Automated validation: No manual checklists
• Critical analysis: Quality gate before development
• Iteration support: Easy to refine based on feedback

Estimated time: 2-5 minutes for validation + user review (add ~5-10 minutes if the Phase 2b judge panel is invoked) Token usage: ~600 tokens for validation + feedback (Phase 2b's judge panel spends several additional agents — see workflows/spec-review-judge-panel.js meta.whenToUse)