| name | planning |
| description | Clarify requirements, ask high-leverage questions, and produce scoped PRDs with measurable acceptance criteria. Use when handling vague requests, new features, or explicit planning/PRD tasks. |
| allowed-tools | Read, Write, Edit, Glob, Grep |
Planning
Unify discovery, requirements clarification, and PRD drafting before implementation begins.
MANDATORY: For ambiguous or high-impact work, clarify first and write down scope before coding.
<when_to_use>
Use This Skill When
| Scenario | Action |
|---|
| Vague or underspecified request | Ask clarifying questions before implementation |
| New feature or architectural change | Capture goals, constraints, and non-goals |
| User asks for a PRD or feature plan | Draft a structured requirements document |
| Scope changes mid-task | Reconfirm assumptions and update the plan |
</when_to_use>
Phase 1: Discovery
Never skip discovery for unclear or architectural requests.
Minimum Clarification Gate
Ask at least 2-3 high-leverage questions before drafting or implementing:
- Problem: What problem are we solving now?
- Users: Who is this for?
- Scope: What is required for v1 vs. later?
- Success Metrics: How will we measure success?
- Constraints: Stack, deadline, budget, compliance, team size?
Dynamic Questioning Rules
- Ask questions that remove implementation forks
- Prefer trade-off framing over open-ended prompts
- Focus on blocking decisions first, then high-leverage decisions
- If a question will not change implementation, do not ask it
For the full questioning framework, read ./dynamic-questioning.md.
Phase 2: Analysis
Synthesize the answers before drafting:
- Map user flows from trigger to outcome
- Separate goals from non-goals
- Identify technical unknowns and risks
- Research existing codebase patterns when applicable
- Convert assumptions into explicit decisions or TBDs
Phase 3: Draft
Produce a concise PRD or planning artifact with concrete, testable requirements.
- Use measurable targets
- Prefer explicit constraints over implied intent
- Keep scope boundaries visible
- Ask for feedback on unclear or high-risk sections
<prd_schema>
PRD Structure
1. Executive Summary
- Problem Statement: 1-2 sentences
- Proposed Solution: 1-2 sentences
- Success Criteria: 3-5 measurable KPIs
2. User Experience
- Personas: Specific users and needs
- User Stories:
As a [user], I want [action] so that [benefit]
- Acceptance Criteria: Testable done definitions for each story
- Non-Goals: Explicit exclusions for the current phase
3. Technical Specifications
- Architecture: Data flow and component interaction
- Integration Points: APIs, databases, auth, external systems
- Security and Privacy: Data handling and compliance constraints
- Open Questions / TBDs: Unresolved decisions with owner or next step
4. Risks and Rollout
- Phasing: MVP -> follow-up iterations
- Technical Risks: Probability, impact, mitigation
</prd_schema>
Constraints
- Never draft a PRD without clarifying questions first when requirements are incomplete
- Every acceptance criterion must be testable
- Use numbers:
loads in <200ms, not loads quickly
- If the stack is unknown, ask or label it
TBD
- Stay inside requested scope; explicitly list non-goals
Example Acceptance Criteria
As a team lead, I want to see average PR review times by repository so that I can identify review bottlenecks.
Acceptance Criteria:
- Dashboard shows average review time for the last 30 days
- Supports filtering by repository
- Refreshes hourly
- Loads in <2 seconds for up to 50 team members
Example Risk Table
| Risk | Probability | Impact | Mitigation |
|---|
| API rate limiting | Medium | High | Cache responses and batch requests |
| Unclear scope | High | Medium | Lock non-goals and review with stakeholders |
