Specification activity skill for PAW workflow. Converts issue/brief into structured feature specification with user stories, requirements, and success criteria.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Specification activity skill for PAW workflow. Converts issue/brief into structured feature specification with user stories, requirements, and success criteria.
Specification
Execution Context: This skill runs directly in the PAW session (not a subagent), preserving user interactivity for requirement clarification.
Convert a rough Issue / feature brief into a structured feature specification. Emphasizes prioritized user stories, enumerated requirements, measurable success criteria, explicit assumptions, and traceability.
Reference: Follow Core Implementation Principles from paw-workflow skill.
Capabilities
Create new specification from issue/brief or WorkShaping.md output
Clarify ambiguous requirements through interactive Q&A
Generate research prompt for factual questions about existing system
Integrate research findings into specification
Revise spec based on downstream learnings (e.g., align with implementation plan)
Address PR review comments on specification
Core Principles
User value focus: Describe WHAT & WHY, not implementation details
Independently testable stories: Prioritize user stories (P1 highest) with acceptance scenarios and "Independent Test" statement
Resolve before drafting: Clarification questions answered before drafting—no unresolved critical questions or placeholder markers
Enumerated traceability: Use IDs (FR-001, SC-001) linking stories ↔ FRs ↔ SCs; cite research sources
Research vs design: Research documents existing behavior; design decisions belong in spec based on requirements
Explicit assumptions: Replace low-impact unknowns with documented assumptions
Measurable & tech-agnostic: Success criteria measurable without referencing specific technologies
No speculation: Every feature maps to a defined story—no "future maybe" items
Clarification Phase
Before drafting the specification, identify and resolve gaps that only the user can answer. This phase always runs during initial spec creation regardless of Review Policy—it's the most important step to get right.
When to Clarify
After reading the issue/brief, scan for high-impact gaps:
Scope boundaries: What's explicitly in vs out?
User roles: Who are the distinct users/personas?
Success criteria: How will we know it works? (measurable)
Edge cases: What happens when X fails/is empty/conflicts?
