Epic Clarify

epic-clarify

Goal: Detect and reduce ambiguity in the epic specification before moving to technical planning.

1. Load epic context:

   • Find epic.md in current directory or parent epic directory
   • Load parent project's PRD.md and epics.md
   • Load epic-codebase-scan.md if exists (brownfield code analysis)
   • Understand epic's role in larger project
   • If no epic.md: ERROR "No epic specification found. Run /epic-specify first"

   Brownfield Adaptation: If epic-codebase-scan.md exists, focus questions on non-discoverable aspects (strategy, future direction) rather than existing features.

2. Analyze epic specification for ambiguities:

   Epic Scope & Boundaries

   • Clear separation from other epics?
   • All user stories well-defined?
   • Edge cases identified?

   Integration Points

   • Dependencies fully specified?
   • API contracts defined?
   • Data flow clear?

   Technical Approach

   • Major technical decisions identified?
   • Performance requirements specific?
   • Security needs clear?

   User Experience

   • User journeys complete?
   • Error scenarios covered?
   • Accessibility requirements?

3. Generate clarification questions (max 5):

   • Focus on epic-specific concerns
   • Prioritize blockers for story breakdown
   • Include context for each question
   • Suggest options where helpful

4. Present questions professionally:

   I've analyzed the epic specification and found areas to clarify:
   
   1. **[Area] - [Specific Question]**
      Context: [Why this matters for epic success]
      Options:
      a) [Option 1]
      b) [Option 2]
      (This will clarify the [Section] section)
   

5. Update epic.md with clarifications:

   • Add "## Clarifications" section
   • Document each Q&A
   • Update affected sections
   • Remove [NEEDS CLARIFICATION] markers

6. Report completion and re-evaluate optional steps:

   Output:

    Epic Clarifications Complete!
   
   Clarified: [X] questions
   Sections Updated: [List]
   

   Then immediately run an Optional Step Evaluation based on the updated epic.md (clarifications may have revealed new signals):

   Evaluate using these criteria (same as epic-specify, now with more context):

   Step	🔴 Required when	Recommended when	⬜ Skip when
   /epic-constitution	Regulated domain; defines API boundary; multi-team coordination	Domain-specific rules not in project constitution	Simple feature, no compliance concerns
   /epic-architecture	Touches 2+ services; new infra; explicit perf targets; complex new integrations	Modifies existing API contracts; new architectural patterns	Simple CRUD; single-service; clear path
   /epic-journey + /epic-wireframes	Any mention of UI, screens, forms, user flows, front-end	Mixes backend and light UI	Backend-only / API-only / CLI / infra
   /speck-skeptical-review	Unfamiliar tech; TBD sections; competing technical approaches	Minor unknowns	Clear path, established patterns

   Output:

   ## Optional Step Evaluation (post-clarification)
   
   | Step | Recommendation | Evidence |
   |------|---------------|----------|
   | /epic-constitution         | ⬜ /  / 🔴 | "[observation]" |
   | /epic-architecture         | ⬜ /  / 🔴 | "[observation]" |
   | /epic-journey + /wireframes| ⬜ / 🔴       | "[observation]" |
   | /speck-skeptical-review              | ⬜ /        | "[observation]" |
   
   Next applicable slot from the marked canonical Epic flow in root AGENTS.md:
   → [first incomplete Required/Recommended slot]
   
   Shall I proceed with [first recommended step]?
   

Error conditions:

• No epic.md → Instruct to run /epic-specify
• Already has tech spec → Note that clarifications may affect design