paw-spec-review

name	paw-spec-review
description	Specification review skill for PAW workflow. Validates Spec.md against quality criteria and returns structured feedback for iteration.

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-workflow skill.

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.