# Epic Clarify

> Fills gaps in epic.md. Use after epic-specify when scope, boundaries, or technical intent are unclear.

- Skill: `telum-ai/epic-clarify` (Agent Skill)
- Install (CLI): `npx skillmds@latest add telum-ai/epic-clarify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/telum-ai/epic-clarify/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: telum-ai (https://skillmd.com/u/telum-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/telum-ai/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