Scope → PRD¶
Turn a rough feature idea into a structured PRD. Ask clarifying questions before writing — never produce a PRD from an ambiguous description.
How to use¶
Example: /scope add a trending videos section to the homepage
Workflow¶
Step 1 — Parse the input¶
Read $ARGUMENTS. Extract what is already clear:
- Feature name
- Problem being solved (if stated)
- Target users / persona (if stated)
- Success signal (if stated)
- Known constraints (if stated)
Step 2 — Identify gaps and ask questions one at a time¶
Before writing anything, check which of the following are missing or ambiguous. Ask ONLY for what is genuinely unclear — do not re-ask information already in the input.
Required information:
| # | Question | Why it matters |
|---|---|---|
| Q1 | What problem does this solve? Who has this problem and why does it matter? | Problem Statement + Evidence sections |
| Q2 | Who are the primary users / personas? | User Stories section |
| Q3 | How will we measure success? (metrics and targets) | Goals & Success Metrics section |
| Q4 | What is explicitly IN scope for v1? | Scope section |
| Q5 | What is explicitly OUT of scope (defer to v2+)? | Scope section |
| Q6 | Any known technical constraints, dependencies, or risks? | Dependencies + Risks sections |
Rules: - Ask questions one at a time — pose a single question, wait for the user's answer, then ask the next - Work through Q1 → Q6 in order, skipping any already answered in the input - After each answer, briefly acknowledge it (one sentence) before asking the next question - Once all gaps are filled, summarize what you understood and confirm before writing - If the user says "just write it" or "use your best judgment", proceed with clearly labeled assumptions
Step 3 — Read existing codebase context¶
Use Glob and Grep to find relevant existing components, entities, services, or APIs related to the feature. This informs the Requirements, Dependencies, and Next Steps sections.
Also read the official PRD template:
Step 4 — Write the PRD¶
Once all gaps are resolved, create docs/prd/PRD-{kebab-slug}.md following the official template from templates/artifacts/prd.template.md.
Fill every section — do not leave placeholder text. Where information is assumed rather than stated by the user, mark it with > **Assumption:** ... so it is easy to review.
Project-specific conventions to follow:
- Use VideoSource (not YouTubeVideo) as the active video entity
- Use ResultObjectInfo<T> / ResultListInfo<T> for API response wrappers
- Reference docs/adr/ (not doc/adr/) for ADR links
- Place new DB migrations in api/src/main/resources/db/changelog/sql/
Step 5 — Offer next steps¶
After writing the PRD, offer:
1. Create ADR (docs/adr/00NN-{slug}.md) using templates/artifacts/adr.template.md
- Key sections to fill: Metadata, Context, Decision Drivers, Considered Options (pros/cons per option), Decision Outcome, Consequences, Validation, Links, Changelog
- Do NOT include Technical Details or Implementation Steps in the ADR — those go in the Plan
2. Create Implementation Plan (docs/plans/plan-{slug}.md) using templates/artifacts/plan.template.md
3. Add entries to mkdocs.yml nav
Do not auto-create these — wait for the user to confirm.
Rules¶
- Never skip the clarification step if any of Q1–Q4 are unanswered
- One question at a time — ask Q1, wait for answer, then Q2, and so on
- Acknowledge each answer before moving to the next question
- Assumptions must be labelled — mark with
> **Assumption:**inline - Use the official template from
templates/artifacts/prd.template.md— do not invent a different structure - Fill every section — use
N/AorTBDonly when genuinely unknown, not as a shortcut
$ARGUMENTS