ReddRadar
Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/edwinhu/workflows/tree/main/skills/ds-spec-reviewer
SKILL.md
Spec Document Reviewer (Data Science)
Purpose: Catch spec gaps BEFORE they survive into data profiling, planning, and implementation.
When to Dispatch
After Phase 1 (brainstorm) writes .planning/SPEC.md and before Phase 2 (ds-plan) begins.
Phase 1: Brainstorm -> SPEC.md written
-> [THIS SKILL] Dispatch spec reviewer subagent
-> Issues found? Fix SPEC.md -> re-dispatch reviewer
-> Approved? -> Phase 2: ds-plan
NO PLANNING WITHOUT REVIEWED SPEC. This is not negotiable.
A bad spec that survives into planning means:
- Profiling data you don't need
- Missing data sources discovered mid-analysis
- Building analysis against incomplete objectives
- Implementing the wrong methodology
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 analysis, no review needed" | Simple specs have the most hidden assumptions | Review it anyway |
| "I'll catch issues during data profiling" | You'll profile the wrong data | Review BEFORE profiling |
Red Flags - STOP If You Catch Yourself:
| Thought | Why It's Wrong | Do Instead |
|---|---|---|
| "This spec looks complete to me" | Self-assessment is rubber-stamping — check EVERY section against the checklist | Read each section individually, verify none are empty or vague |
| "Spec looks similar to a prior one, should be fine" | Similar structure ≠ complete content — prior specs had different data sources and objectives | Evaluate THIS spec against THIS analysis's requirements |
| "The objectives are obvious, no need to scrutinize" | Obvious objectives hide unstated assumptions — the user's intent may differ from your inference | Verify objectives are specific, measurable, and user-confirmed |
| "Incomplete section is fine, they'll fill it in during planning" | Planning consumes the spec as-is — gaps survive into data profiling and task breakdown | Flag the gap NOW, before it propagates downstream |
Dispatch Template
Use this Task invocation to dispatch the spec reviewer:
Agent(
subagent_type="general-purpose",
description="Review DS spec document",
allowed_tools=["Read", "Glob", "Grep", "Bash(read-only)"],
prompt="""
You are a data science spec document reviewer. Verify this spec is complete and ready for data profiling and analysis planning.
**Tool Restrictions:** The spec reviewer is READ-ONLY. It reads `.planning/SPEC.md`, evaluates against checklist, returns verdict. It MUST NOT use Write or Edit.
**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 |
| Data Sources | All data sources identified with location, format, and time period |
| Analysis Objectives | Clear, specific questions the analysis will answer |
| Output Format | Expected deliverables specified (report, dashboard, model, tables) |
| Success Criteria | Measurable, specific, with clear pass/fail (not vague) |
| Reproducibility | Replication strategy documented if replicating existing work |
| Constraints | Timeline, methodology requirements, computational limits documented |
| Consistency | Internal contradictions, conflicting requirements |
| YAGNI | Unrequested analyses, over-engineering, scope creep |
## CRITICAL - Look Especially Hard For:
- Any TODO markers or placeholder text
- Sections saying "to be defined later" or "will spec when data is explored"
- Sections noticeably less detailed than others
- Data sources listed without location or format
- Analysis objectives that are vague ("explore the data", "find patterns")
- Success criteria that are unmeasurable ("good model", "interesting results")
- Missing replication/reproducibility strategy when replicating existing work
- Missing constraints section
- Output format unspecified (who consumes the results and how?)
## Output Format
## Spec Review
**Status:** APPROVED | ISSUES_FOUND
**Issues (if any):**
- [Section]: [specific issue] - [why it matters for planning]
**Recommendations (advisory - don't block approval):**
- [suggestions for improvement that aren't blocking]
""")
Handling Reviewer Output
If APPROVED
Proceed immediately to Phase 2 (ds-plan). Discover and load:
Read ${CLAUDE_SKILL_DIR}/../../skills/ds-plan/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 data profiling with a flawed spec is NOT HELPFUL — wrong profiling produces wrong plans, which produce wrong analysis, wasting everyone's time.
You know the spec has gaps. Profiling built on a bad spec profiles the wrong data. Plans built on wrong profiling produce wrong analysis. Implementation of a wrong plan wastes everyone's time and produces incorrect results.
Fix the spec now. It costs minutes, not hours.
Gate Function
Checkpoint type: human-verify (spec completeness is machine-verifiable)
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 ds-plan 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
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.
edwinhu/workflows
workflow-creator
This skill should be used when the user asks to 'create a workflow', 'design a workflow', 'edit a workflow', 'audit workflow', 'improve workflow', 'break down a task into phases', or needs to substantially create or edit any multi-phase workflow.
Didn't find tool you were looking for?