tomevault-io Spec Review
Execution Context: This skill runs in a subagent session, delegated by the PAW orchestrator. Return structured feedback (pass/fail + issues) to the orchestrator—do not make orchestration decisions.
Review specifications for quality, completeness, and clarity before planning proceeds. Return structured feedback—do not make orchestration decisions.
Reference: Follow Core Implementation Principles from
paw-workflowskill.
Capabilities
- Review Spec.md for quality, completeness, and clarity
- Validate against specification quality criteria
- Identify specific sections needing revision
- Return structured feedback with pass/fail status
Desired End State
After review, the PAW agent receives:
- Pass/fail determination
- For passing specs: confirmation of readiness for planning (with optional polish suggestions)
- For failing specs: specific issues by criterion, affected sections, and suggestions for fixing
Review Process
Evaluate the specification at .paw/work/<work-id>/Spec.md against the Quality Criteria Checklist below. For failing items, note the specific issue, identify affected section(s), and suggest what needs to change without prescribing exact wording.
Quality Criteria Checklist
Content Quality
- User value focus: Describes WHAT & WHY, no implementation details
- No code artifacts: No code snippets, file paths, API signatures, class names
- Story priorities: Clear priority order (P1 highest, descending)
- Testable stories: Each user story is independently testable
- Acceptance scenarios: Each story has ≥1 acceptance scenario (Given/When/Then)
- Edge cases: Edge conditions and error modes enumerated
Narrative Quality
- Overview present: 2-4 paragraphs of flowing prose (not bullets)
- Objectives present: Bulleted behavioral goals (not implementation)
- User perspective: Overview and Objectives focus on WHAT/WHY from user viewpoint
- Specific content: Uses measurable language, not vague terms
- No duplication: Overview doesn't duplicate User Stories/FRs/SCs verbatim
Requirement Completeness
- FRs testable: All functional requirements are observable and testable
- FRs mapped: Each FR linked to supporting user stories
- SCs measurable: Success criteria are measurable and technology-agnostic
- SCs linked: Success criteria reference relevant FR IDs
- Assumptions documented: No silently implied assumptions
- Dependencies listed: External dependencies and constraints captured
Ambiguity Control
- No unresolved questions: No clarification markers or TBDs in spec body
- Precise language: No vague adjectives without metrics (e.g., "fast", "easy")
Scope & Risk
- Boundaries defined: Clear In Scope and Out of Scope sections
- Risks captured: Known risks with impact and mitigation noted
Research Integration (if SpecResearch.md exists)
- Research incorporated: System research questions answered or converted to assumptions
- External questions listed: Optional external questions preserved for manual completion
Feedback Guidance
For passing specs: Indicate readiness for planning. Include minor polish suggestions if any.
For failing specs: List each failing criterion with the specific issue, affected section(s), and a suggestion for what to fix. Include count of passing vs total criteria.
Review Guidelines
Be Specific
Instead of: "FRs are incomplete" Say: "FR-003 lacks story mapping. Add (Stories: P2) reference."
Focus on Criteria
Only flag issues that violate a checklist item. Personal preferences don't count unless they affect testability or clarity.
Don't Rewrite
Identify what's wrong and suggest direction. Don't prescribe exact wording—the Spec Agent makes those decisions.
Context Matters
Consider workflow mode when reviewing:
- Full mode: Expect comprehensive coverage
- Minimal mode: Accept lighter spec with core FRs only
- Custom mode: Reference Custom Workflow Instructions for expected depth
Completion Response
Report to PAW agent: pass/fail result, criteria passing count, issues found count, and detailed feedback per Feedback Guidance above. Do NOT make orchestration decisions—return status only.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.