create-epic

name	create-epic
description	Turn an idea into a structured epic draft using templates/epic-template.md
argument-hint	[epic idea - can be a short prompt or a path to a raw idea note]

Create Epic

You help turn a raw product idea into a well-structured epic draft. The output follows templates/epic-template.md and lands in epics/ with stage: Explore.

Input

The user provides via $ARGUMENTS:

• A short prompt (e.g., "unified onboarding dashboard for CSMs"), OR
• A path to a raw idea note (e.g., samples/sample-epic-idea.md)

Workflow

1. Gather context

Read the raw idea. If $ARGUMENTS is a path, read that file. Otherwise use the prompt directly.

Read supporting context in parallel:

• templates/epic-template.md - the target structure
• docs/epic-lifecycle.md - the stage framework
• research/personas/ - personas that might match the target user
• Dashboard/people-profiles.md - any stakeholders mentioned
• Loose Notes/Work/ and Meetings/ - related prior discussions (search by keywords from the idea)
• Initiatives/ - does this fit under an existing initiative?

2. Identify gaps in the idea

Before drafting, identify what's missing or unclear. Ask the user 3-5 focused questions in ONE AskUserQuestion round if any of these are unclear from the raw input:

• Target user: which persona does this serve? (Offer personas from research/personas/ as options.)
• Primary metric: what measurable outcome should improve?
• Scope boundary: what is explicitly NOT in this epic?
• Initiative fit: does this belong under an existing initiative (show list from Initiatives/) or does it stand alone?
• Competitor check: has competitive research been done? (Offer /competitive-research if not.)

Skip questions where the raw idea already has a clear answer. Maximum one round.

3. Draft the epic

Use templates/epic-template.md as the structure. Fill what you can from the raw idea + answers:

Required sections (always fill):

• Value Proposition Statement - one crisp statement of the outcome.
• User Problem - 1-2 paragraphs from the customer's perspective. Frame from the "why", not the product's failure.
• User Stories - 3-6 stories at the "what" level (Explore phase). Add the "how" later.

Phase-specific (fill lightly in Explore, flag for Scope):

• Breakdown - list sub-activities under Explore (customer interviews, research, opportunity-solution tree).
• Risk Assessment - initial class only, full in Scope.

Skip for now:

• Release Notes (drafted in Scope or later).
• Implementation Notes (Scope phase).
• Design Planning, Documentation Planning (Scope phase).
• Validation Criteria (Validate phase).

Fill placeholders honestly. If you don't know something, write [To determine during Scope] or [Needs user research]. Don't fabricate.

4. File location and naming

• Folder: epics/. Create if it doesn't exist.
• Filename: YYYY-MM-DD - [Epic Title slug].md. Example: 2026-04-20 - Unified onboarding dashboard.md.
• Frontmatter: set stage: Explore, status: exploring, created: YYYY-MM-DD.

5. Link the epic

• Daily journal: add a link in today's journal under ## Notes. Format: - [[YYYY-MM-DD - Epic Title]] - new epic in Explore stage.
• Initiative: if the epic fits under an existing initiative (from step 2), add a link in the initiative file under ## Epics under this initiative.
• Nothing external: do NOT push to any external tracker. The epic lives in the vault until you explicitly ship it elsewhere.

6. Propose follow-up tasks

Based on what's missing in the draft, propose 2-5 tasks that would move the epic out of Explore. Examples:

• Schedule 5 customer interviews with target persona
• Run /competitive-research on [topic]
• Run /opportunity-solution-tree for the primary metric
• Review the draft with [stakeholder]
• Draft a 3-bullet research brief for the user research team

Show the proposed task list and wait for user confirmation. After confirmation, append to Dashboard/tasks.md under "This week" with format:

- [ ] Task - source: [[YYYY-MM-DD - Epic Title]] - due: YYYY-MM-DD - priority: P3

7. Output summary

✅ Epic drafted: [[YYYY-MM-DD - Epic Title]]
✅ Linked in today's journal
[if initiative match] ✅ Linked under [[Initiative]]

Stage: Explore
Status: exploring

📋 Proposed follow-up tasks (to move to Scope):
1. [Task]
2. [Task]

Confirm: Add tasks to Dashboard/tasks.md? (Y/N)

💡 Next steps in the lifecycle: see docs/epic-lifecycle.md

Notes

• Honesty over completeness. It's better to mark a section as [Needs user research] than to invent answers.
• Epics start thin and grow. The Explore-stage draft should be under 1 page. Sections get filled as the epic progresses.
• One initiative per epic. If the idea fits under multiple initiatives, flag this as a scope problem rather than dual-linking.
• User stories from the customer's perspective, not the product's. "As a support engineer, I can..." not "The product shall...".