I want to add an enhancement to this project. Help me evaluate it, document it properly, and create tasks for implementation.
Here's the enhancement:
$ARGUMENTS
Phase 1: Discovery & Impact Analysis
Review Existing Context
Before asking questions, thoroughly review:
docs/plan.md — Current PRD: vision, personas, features, data model
docs/user-stories.md — Existing stories and epics (note the last story ID used)
docs/tech-stack.md — Technical constraints and patterns
docs/coding-standards.md — Code conventions, styling rules, commit format
docs/project-structure.md — Where new files should go
docs/tdd-standards.md — Test categories and patterns for task descriptions
docs/design-system.md — Design tokens, component patterns, styling approach (if frontend changes)
CLAUDE.md — Project conventions, Key Commands, workflow
- Relevant source code if needed to understand current implementation
Understand the Enhancement
Use AskUserQuestionTool to batch these questions:
- What problem does this solve? Who benefits? (Which persona?)
- What's the user flow? Walk me through it step by step.
- What triggers this feature? (User action, system event, time-based?)
- What does success look like? How will we measure it?
Challenge and Refine
Push back where appropriate:
- Is this the simplest solution? Propose alternatives if you see a better way.
- Should the scope be smaller for a v1 of this enhancement?
- Are there edge cases or error states not mentioned?
- Does this conflict with or duplicate existing functionality?
- What are the riskiest assumptions?
Innovation Pass
Before finalizing the enhancement scope, research and consider:
Competitive Analysis (use subagents for research):
- How do similar apps handle this feature?
- What do they do well? Where do they fall short?
- Is there a standard UX pattern users will expect?
Enhancement Opportunities:
- What would make this feature "delightful" vs just "functional"?
- Are there adjacent features that would multiply the value? (e.g., if adding notifications, should we add notification preferences too?)
- What would a user complain about if we ship the minimal version?
AI-Native Possibilities:
- Could AI make this smarter? (smart defaults, predictions, natural language)
- Is there manual work we could automate?
Present innovation ideas with:
- What: The enhancement to the enhancement
- Why: User benefit
- Cost: Trivial / Moderate / Significant effort
- Recommendation: Include in this enhancement, or backlog for later
Use AskUserQuestionTool to present innovation ideas for approval BEFORE proceeding.
Impact Analysis
Report what this enhancement affects:
-
Fit Check
- Does this align with the product vision in the PRD?
- Which persona(s) does this serve?
- Does it conflict with any existing features or design decisions?
-
Scope Assessment
- Is this a v1 feature or should it be deferred?
- Complexity estimate: Small (1-2 tasks), Medium (3-5 tasks), Large (6+ tasks)
- Dependencies on existing features or new infrastructure?
-
Technical Impact
- Data Model: New entities? Changes to existing ones? Migrations needed?
- UI Changes: New screens? Modifications to existing ones?
- API Changes: New endpoints? Changes to existing ones?
- External Integrations: New third-party services?
-
Recommendation
- Proceed as described
- Proceed with modifications (explain)
- Defer to a future version (explain why)
- Reconsider (if it conflicts with product vision)
Wait for user approval before proceeding to Phase 2.
Phase 2: Documentation Updates
After approval, update the relevant documentation.
Update docs/plan.md
Add the enhancement to the PRD (do NOT remove or significantly alter existing content):
-
Feature Requirements section — Add the new feature with:
- Clear description of what it does
- Why it exists (tied to user need/persona)
- Priority: Must-have / Should-have / Future
- Business rules or logic that aren't obvious
- Concrete examples where behavior might be misinterpreted
- Mark with:
[Enhancement added YYYY-MM-DD] for traceability
-
Data Model Overview (if applicable):
- New entities with their key attributes
- Changes to existing entities
- New relationships between entities
-
Core User Flows (if applicable):
- New flow, or modifications to existing flows
- Include happy path AND error/edge cases
- Be specific: "when X happens, the user sees Y" not "handle errors gracefully"
-
External Integrations (if applicable):
- New third-party services or APIs
- What data flows in/out
-
Non-Functional Requirements (if applicable):
- Performance implications
- Security considerations
- Accessibility needs
Update docs/user-stories.md
Add new user stories following the existing document structure and the User Stories prompt format:
-
Determine Epic Placement
- Does this fit under an existing epic?
- Or does it need a new epic? (Only if it's a significant new area — match existing naming patterns)
-
Create User Stories — Each story MUST include ALL of these fields:
- ID: Continue the existing numbering sequence (check the last ID in the file)
- Title: Short, scannable summary
- Story: "As a [persona], I want [action], so that [outcome]"
- Acceptance Criteria: Written as testable Given/When/Then scenarios
- These become TDD test cases — be explicit
- Cover happy path AND edge cases
- Include error states
- Scope Boundary: What this story does NOT include (prevents scope creep)
- Data/State Requirements: What data models, state, or dependencies are implied
- UI/UX Notes: What the user sees, key interactions, error states, loading states
- Priority: MoSCoW (Must/Should/Could/Won't)
- Enhancement Reference:
[Enhancement added YYYY-MM-DD]
-
Story Quality Checks — Before finalizing, verify:
- Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
- No story is so large it couldn't be implemented in 1-3 focused Claude Code sessions
- Acceptance criteria are specific enough that pass/fail is unambiguous
- Edge cases and error states are covered explicitly
Cross-Reference Check
After updating both documents:
- Verify every new PRD feature maps to at least one user story
- Verify terminology is consistent with existing documentation
- Verify no contradictions were introduced with existing features
- Check that personas referenced exist in the PRD
Phase 3: Task Creation
Create Beads tasks for implementation.
Task Creation Guidelines
For each user story (or logical grouping of small stories):
bd create "US-XXX: <imperative title>" -p <priority>
# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have
Task Titles and Descriptions
- Title format:
US-XXX: <imperative action> (e.g., "US-048: Add streak notification settings")
- Description should include:
- Reference to user story:
Implements US-XXX
- Key acceptance criteria summary
- Technical notes or gotchas from analysis
- Migration notes if data model changes
Task Sizing
- One task per story for small/medium stories
- Multiple tasks per story for large stories — break down by:
- Data model/migrations first
- Backend API second
- Frontend/UI third
- Edge cases and polish last
Dependency Management
# Set up dependencies (child is blocked by parent)
bd dep add <child-task-id> <parent-task-id>
# Common dependency patterns:
# - Migrations before features that use new models
# - Backend before frontend
# - Core functionality before edge cases
# - Shared components before features that use them
# Verify the dependency graph
bd dep tree <task-id>
Migration Considerations
If the enhancement requires data model changes:
- Create a dedicated migration task as the first dependency
- Note if existing data needs transformation
- Consider: can this be deployed incrementally or does it require coordination?
- Document rollback strategy if the migration is risky
Phase 4: Summary & Approval
After completing all updates, provide a clear summary:
1. Enhancement Summary
One paragraph: what this adds and why it matters.
2. Documentation Changes
- docs/plan.md: What sections were added/modified
- docs/user-stories.md: List new story IDs with titles
3. Tasks Created
| Task ID | Title | Priority | Depends On |
|---------|-------|----------|------------|
| xxx-abc | US-048: Add notification settings | 1 | - |
| xxx-def | US-049: Send streak reminders | 1 | xxx-abc |
4. Implementation Order
Recommended sequence based on dependencies:
- First: [task(s)]
- Then: [task(s)] (can be parallelized)
- Finally: [task(s)]
5. Ready to Implement
bd ready # Show what's available to work on now
6. Open Questions (if any)
- Decisions deferred to implementation time
- Areas that may need refinement during development
- Risks to monitor
7. Consider Follow-Up Reviews
Depending on the enhancement scope, you may want to re-run these prompts:
- Implementation Plan Review: If you created 5+ tasks, run it to verify sizing, dependencies, and coverage
- Platform Parity Review: If the enhancement has platform-specific behavior (web vs. mobile differences), re-run to check platform coverage
- Workflow Audit: Only if the enhancement changed project infrastructure or conventions (rare)
Process Rules
- Don't skip discovery: Even if the enhancement seems simple, do the impact analysis
- Use subagents for research: Competitive analysis and UX best practices can run in parallel with other work
- Batch questions: Use AskUserQuestionTool to group related questions — don't ask one at a time
- Present innovations before documenting: Get approval on scope expansions before writing them up
- Challenge assumptions: If something seems overengineered or could be simpler, say so
- Maintain consistency: Match terminology, format, and style of existing docs exactly
- Add traceability: Mark enhancements with dates so we know when features were added
- Right-size the scope: Push back if the enhancement is too large — suggest phasing
- Check for conflicts: Review
bd list for in-progress work that might be affected
When to Use This Prompt
- Adding a new feature to an existing product
- Expanding an existing feature with new capabilities
- Adding a new user flow or journey
- Any change that requires updating the PRD or user stories
When NOT to Use This Prompt
- Bug fixes: Use
/scaffold:quick-task instead — it creates focused, well-defined Beads tasks
- Refactoring: Use
/scaffold:quick-task instead — no doc updates needed, just a task with clear acceptance criteria
- Performance improvements: Use
/scaffold:quick-task instead — targeted fixes don't need full discovery
- Initial product creation: Use the PRD prompt instead
- Major pivots: If this changes the core product direction, revisit the full PRD first
- Exploratory ideas: If you're not sure you want this, discuss before documenting
Optional: Skip Innovation Pass
If you just want to document a well-defined enhancement without competitive research and innovation brainstorming, add this to your request:
Skip the innovation pass — just document and create tasks for what I described.
This is appropriate when:
- The enhancement is already well-researched
- You're porting a feature from a competitor you've already analyzed
- Time pressure requires moving fast
- The enhancement is truly trivial (but consider: does it even need this prompt?)
Quality Standards
From the PRD prompt — apply these to enhancement documentation:
- Every feature must be described thoroughly enough that an AI agent can build it without asking follow-up questions
- Avoid ambiguity: specify what errors can occur and what the user sees for each
- Include concrete examples where behavior might be misinterpreted
- Use consistent terminology throughout
- Non-functional requirements are specific and measurable (not "fast" — how fast?)
From the User Stories prompt — apply these to new stories:
- Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
- Acceptance criteria are specific enough that pass/fail is unambiguous
- No story is so large it couldn't be implemented in 1-3 focused sessions
- Every story has scope boundaries to prevent creep during implementation
From the Gap Analysis prompts — verify before finishing:
- Every new PRD feature maps to at least one user story
- Happy paths AND error/edge cases are covered in acceptance criteria
- No vague language that could be misinterpreted ("intuitive," "user-friendly," "seamless," "handles gracefully")
- Dependencies between stories are identified (they become Beads dependencies)
- Priority assignments make sense relative to existing features
After This Step
When this step is complete, tell the user:
Enhancement documented — PRD updated, user stories created, Beads tasks ready.
Next (if applicable):
- If you created 5+ tasks: Run
/scaffold:implementation-plan-review — Review task quality, coverage, and dependencies.
- If the enhancement has platform-specific behavior: Run
/scaffold:platform-parity-review — Check platform coverage.
- Otherwise: Run
/scaffold:single-agent-start or /scaffold:single-agent-resume to begin implementation (or /scaffold:multi-agent-start <agent-name> / /scaffold:multi-agent-resume <agent-name> for worktree agents).
Pipeline reference: /scaffold:prompt-pipeline