ReddRadar
Agent skill
dev-spec-reviewer
Internal skill used by dev-brainstorm at Phase 1 exit gate. Dispatches a reviewer subagent to verify SPEC.md completeness before exploration. NOT user-facing.
Install this agent skill to your Project
npx add-skill https://github.com/edwinhu/workflows/tree/main/skills/dev-spec-reviewer
SKILL.md
Spec Document Reviewer
Purpose: Catch spec gaps BEFORE they survive into exploration, design, and implementation.
When to Dispatch
After Phase 1 (brainstorm) writes .planning/SPEC.md and before Phase 2 (explore) begins.
Phase 1: Brainstorm → SPEC.md written
→ [THIS SKILL] Dispatch spec reviewer subagent
→ Issues found? Fix SPEC.md → re-dispatch reviewer
→ Approved? → Phase 2: Explore
NO EXPLORATION WITHOUT REVIEWED SPEC. This is not negotiable.
A bad spec that survives into exploration means:
- Exploring the wrong areas of the codebase
- Clarifying the wrong ambiguities
- Designing against incomplete requirements
- Implementing the wrong thing
Catching a spec gap NOW costs 1 minute. Catching it during implementation costs hours. </EXTREMELY-IMPORTANT>
Rationalization Table - STOP If You Think:
| Excuse | Reality | Do Instead |
|---|---|---|
| "The spec looks complete to me" | Self-review is rubber-stamping | Dispatch independent reviewer |
| "User already confirmed the spec" | User confirms intent, not completeness | Reviewer checks what user might miss |
| "This will slow us down" | 30-second review saves hours of rework | Dispatch the reviewer |
| "It's a simple feature, no review needed" | Simple specs have the most hidden assumptions | Review it anyway |
| "I'll catch issues during exploration" | You'll explore the wrong things | Review BEFORE exploring |
Dispatch Template
Use this Task invocation to dispatch the spec reviewer:
Agent(
subagent_type="general-purpose",
allowed_tools=["Read", "Glob", "Grep", "Bash(read-only)"],
description="Review spec document",
prompt="""
You are a spec document reviewer. Verify this spec is complete and ready for codebase exploration and implementation planning.
**Tool Restrictions:** You are READ-ONLY. You MUST NOT use Write or Edit tools. You read `.planning/SPEC.md`, evaluate it against the checklist, and return a verdict. If you find issues, you report them — the main chat fixes them.
**Spec to review:** .planning/SPEC.md
Read the spec file, then evaluate against ALL categories below.
## What to Check
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, "TBD", incomplete sections, empty fields |
| Coverage | Missing error handling, edge cases, integration points |
| Consistency | Internal contradictions, conflicting requirements |
| Clarity | Ambiguous requirements that could be interpreted multiple ways |
| YAGNI | Unrequested features, over-engineering, gold-plating |
| Scope | Focused enough for a single implementation — not covering multiple independent features |
| Testing | Testing strategy section filled (not empty or "manual only") |
| Success Criteria | Measurable, specific, with clear pass/fail (not vague) |
## CRITICAL — Look Especially Hard For:
- Any TODO markers or placeholder text
- Sections saying "to be defined later" or "will spec when X is done"
- Sections noticeably less detailed than others
- Testing strategy that says "manual" (this is a BLOCKER in workflows:dev)
- Success criteria that are vague ("works well", "is fast", "handles errors")
- Requirements that contradict each other
- Missing constraints section
## Output Format
## Spec Review
**Status:** APPROVED | ISSUES_FOUND
**Issues (if any):**
- [Section]: [specific issue] - [why it matters for implementation]
**Recommendations (advisory — don't block approval):**
- [suggestions for improvement that aren't blocking]
""")
Handling Reviewer Output
If APPROVED
Proceed immediately to Phase 2 (explore):
Read ${CLAUDE_SKILL_DIR}/../../skills/dev-explore/SKILL.md and follow its instructions.
If ISSUES_FOUND
- Fix the specific issues in
.planning/SPEC.md - Re-dispatch the reviewer (same template)
- Repeat until APPROVED or max 5 iterations
If 5 Iterations Without Approval
Escalate to user:
"Spec reviewer has flagged issues 5 times. Remaining issues:
[list issues]
Should I: (A) Fix these, (B) Proceed with known gaps, (C) Rethink the spec?"
Drive-Aligned Framing
Proceeding to exploration with a flawed spec is NOT HELPFUL — you'll explore the wrong areas and build the wrong thing, creating hours of rework.
You know the spec has gaps. Exploration built on a bad spec produces bad findings. Design built on bad findings produces a bad plan. Implementation of a bad plan wastes everyone's time.
Fix the spec now. It costs minutes, not hours.
Gate Function
1. IDENTIFY: `.planning/SPEC.md` exists
2. DISPATCH: Send to reviewer subagent
3. READ: Reviewer returns APPROVED or ISSUES_FOUND
4. VERIFY: If ISSUES_FOUND, fix and re-dispatch (max 5)
5. CLAIM: Only proceed to explore when APPROVED
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
edwinhu/workflows
audit-fix-loop
This skill should be used when the user asks to 'iteratively improve', 'audit and fix', 'hill-climb quality', 'grade and improve', 'score and fix', 'audit loop', 'quality loop', or needs structured iterative improvement of an artifact using scored independent audits. Also use when the user invokes a ralph loop for quality improvement rather than task completion.
edwinhu/workflows
ds-spec-reviewer
Internal skill used by ds-brainstorm at Phase 1 exit gate. Dispatches a reviewer subagent to verify SPEC.md completeness before planning. NOT user-facing.
edwinhu/workflows
pptx-render
Use when the user asks to "render pptx", "show pptx slide", "compare with pptx", "pptx to image", "export pptx slide", "original slide", "show me the original", "what does the pptx look like", or needs to extract a specific PPTX slide's content for visual comparison.
edwinhu/workflows
obsidian-organize
Organize Obsidian notes according to clawd's preferences. Use when user asks to "organize notes", "move notes to right folder", "clean up vault", "tidy vault", "file this note", or when creating new notes in the Obsidian vault. Also use when moving, renaming, or categorizing notes, or when the vault root has stray files.
edwinhu/workflows
dev-verify
This skill should be used when the user asks to 'verify completion', 'check that tests pass', 'confirm feature works', or REQUIRED Phase 7 of /dev workflow (final). Enforces fresh runtime evidence before claiming completion.
edwinhu/workflows
dev
This skill should be used when the user asks to 'start a feature', 'build a feature', 'implement a feature', 'develop', 'new feature', or needs the full 7-phase development workflow with TDD enforcement.
Didn't find tool you were looking for?