Skip to content

xiduzo/wtf / skills/wtf.write-epic

wtf.write-epic

Verified

This skill should be used when a user wants to create, draft, or plan a GitHub Epic issue — for example "write an epic", "I want to define a new initiative", "scope out this strategic project", "turn this idea into an epic", "plan work that spans multiple features", or "start from a bounded context". Also use when the user asks to define domain outcomes, capture a large initiative before breaking it into features, or describe work in terms of business goals rather than implementation details.

FileKindSize
SKILL.mdskill md10.2 KB
---
name: wtf.write-epic
description: This skill should be used when a user wants to create, draft, or plan a GitHub Epic issue — for example "write an epic", "I want to define a new initiative", "scope out this strategic project", "turn this idea into an epic", "plan work that spans multiple features", or "start from a bounded context". Also use when the user asks to define domain outcomes, capture a large initiative before breaking it into features, or describe work in terms of business goals rather than implementation details.
---

# Write Epic

Create a GitHub Epic issue for a strategic initiative. Capture stakeholders, goals, success metrics, and a feature breakdown scaffold.

## Process

### 0. GitHub CLI setup

Run the setup check from `../references/gh-setup.md`. Stop if `gh` is not installed or not authenticated. Note whether the extensions are available. That result controls whether native dependency links are created in step 8.

If gh-setup was already confirmed this session, skip this step. Example: this skill is re-invoked via `wtf.write-feature` step 11 "Write another Epic".

### 1. Capture the seed idea

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "What initiative are you working on?"
- header: "Initiative"
- options: infer 1–2 candidates from recent open Epics or README context if available

Do not ask follow-up questions yet. Acknowledge the idea briefly. Move to research.

### 2. Deep research

Run in parallel with the Agent tool and GitHub issue search.

**Codebase exploration:**

Use the Agent tool to find, with independent searches in parallel:

- Existing product descriptions, ADRs, and architectural notes (READMEs, `docs/`, ADR files)
- The module structure — which systems exist
- Existing implementations, prior attempts, or integration points for the initiative's key domain nouns
- Any existing domain glossary, ubiquitous-language doc, or prior DDD artifact

**Wiki / glossary fetch:**
Fetch relevant GitHub wiki pages or in-repo glossary docs. Search for pages that match the initiative domain area. Use these to:

- Identify existing Ubiquitous Language terms the team already uses
- Avoid new synonyms for named concepts
- Surface any existing Bounded Context definitions

**Related issues (optional — if GitHub is unavailable, skip this sub-step without comment):**

- Open and closed issues or epics that overlap or inform this initiative
- Prior discussions, decisions, or rejected approaches

Synthesize findings internally. Do not dump raw research at the user.

### 3. Grill the user

Use research findings. Ask targeted follow-up questions to close remaining gaps. For each unanswered item below, call `AskUserQuestion` (per `../references/questioning-style.md`).

Completeness checklist (ask only about unanswered items):

- Scope boundaries (what is explicitly out of scope?)
- Success criteria (how will we know we are done?)
- Stakeholders (Product Owner, Lead Designer, Tech Lead — skip any that do not apply)
- Constraints or deadlines that must shape the approach
- Any known risks or dependencies the research surfaced that need confirmation
- **Bounded Context:** Which domain context(s) does this initiative live in? (Ask last — use an option list if multiple contexts were found in research.)
- **Ubiquitous Language:** What domain actors (named roles, not "users") and domain verbs (business actions) define this space? Are there existing terms the team already uses that must be preserved?

### 4. DDD Language Check

Before drafting, review the seed idea and all gathered context against the rules in `../references/ddd-writing-rules.md`:

- Does the Epic title describe a **business outcome**, not a technology action?
- Does the Goal use domain vocabulary — not engineering jargon?
- Reframe any tech terms as business outcomes. Implementation detail belongs in Traces.
- Flag any ambiguous or undefined term. Propose the domain-correct alternative.

### 5. Vertical slice assessment

Run Stage 1 of `../references/scope-gates.md` on the gathered context. Epic bar: a coherent strategic initiative that delivers user or business value alone. It must not exist only as a dependency for another epic.

Evaluate:

- **Passes** → proceed to draft.
- **Too broad** → propose focused epics and confirm with the user before continuing.
- **Has dependencies** → identify Epics this epic depends on and Epics that depend on this one. Record each dependency issue number for step 8. Do not write them into the body yet.

### 6. Draft the Epic

Produce a complete draft. Success Metrics must be specific and measurable. Feature Breakdown stays as empty placeholders.

Apply strict STE per `../references/ste-writing.md` before writing any durable body.

Load the EPIC template per `../references/issue-template-loading.md` (verify existence, halt-or-setup if missing, read body below the second `---` delimiter). Fill all sections with the gathered context.

**DDD writing rules for this draft:**

- **Bounded Context:** Fill the Bounded Context field. If the epic spans multiple contexts, name each and describe where the seam is.
- **Context and Goal sections:** Every sentence must use Ubiquitous Language. No tech jargon.
- **Success Metrics:** Phrase as business-observable outcomes ("Merchants can view settlement status within 2 minutes of payment"), not system metrics ("API latency < 200ms").
- **Risks:** Frame risks in domain terms ("Dispute resolution rules differ by jurisdiction") before listing technical risks.

### 7. Scope gate

Run Stage 2 of `../references/scope-gates.md` on the written draft. Run this even if step 5 passed. Drafting can reveal bundled objectives that were invisible in the abstract.

**Epic-level split signals** (heuristics — use judgement, not rigid thresholds):

- The Goal statement contains multiple distinct business objectives joined by "and". Each could stand alone as a separate initiative.
- The Feature Breakdown has more than 8 proposed features. Treat this as a signal worth scrutiny, not an automatic trigger. Eight tightly related features in one domain can be fine.
- The Epic spans more than one Bounded Context without a clear seam or handoff point.
- Success Metrics describe outcomes that belong to completely different user journeys.
- The epic's beneficiary cannot be stated in a single sentence without using "and" to cover unrelated groups.

If no signals fire, proceed to creation. If one or more fire, follow the Stage 2 procedure. State the signals. Explain the risk. Propose a concrete split (two or three focused epic titles with a one-line goal each). Use the keep/split/stop ask from `../references/scope-gates.md`.

On **Split it** → return to step 3 with the chosen focused Epic as the seed. Carry forward all research and codebase findings already gathered. Only re-ask stakeholder questions that the narrowed scope makes ambiguous. Note the remaining proposed sub-epics to the user as follow-on work.

### 8. Review with user

Show the draft. Then call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Does this look right?"
- header: "Review"
- options:
  - **Looks good — create the issue** → proceed with issue creation
  - **I have changes** → adjust first

Apply edits. Then proceed immediately.

### 9. Create the issue

> Note: Write the issue body to a temp file (`$BODY`) with the Write tool. Then create it through the gh body helper so multi-line UTF-8 content survives on Windows. See `../references/gh-body-helper.md`.

> **Title generation:** Spawn a subagent with `model: "haiku"` to generate a concise, domain-language title from the Epic's Goal. Pass in the Goal text and ask for a title (no prefix emoji/label needed — that is added below).

```bash
# $BODY is the temp file you wrote the filled body to with the Write tool.
# Create the issue WITHOUT a kind label — the classify step below sets the kind.
python3 .wtf/gh-body.py create --title "🎯 Epic: <title>" --body-file "$BODY"
```

Print the issue URL and number.

**Classify the issue as `Epic`.** Set `TYPE="Epic"` and `ISSUE_NUMBER=<number from the URL>`. Then run the **Classify a new issue** block from `../references/issue-classification.md` (resolve `$WTF_CLASS` once first). In `types` mode it sets the native GitHub issue type and leaves labels free for your own segmentation. In `labels` mode it applies the `epic` label. Either way the Epic is classified. Nothing downstream depends on which mechanism was used.

**Native dependency links:** Epics are top-level. No `gh sub-issue` call is needed here. If `gh-issue-dependency-available` (from step 0), create a blocking link for each dependency identified in step 5:

```bash
# For each issue this epic depends on (must ship first):
gh issue-dependency add <this_epic_number> --blocked-by <blocker_number>
```

If the extension is unavailable, warn the user. Do not write dependency references into the issue body.

### 10. Update the wiki / glossary

If this Epic introduced or refined **Bounded Context** definitions or **Ubiquitous Language** terms, update the project glossary:

- Check whether a wiki page or in-repo glossary doc exists for this Bounded Context (e.g. `docs/glossary.md`, GitHub wiki page matching the context name).
- If a page exists: add or update the relevant term definitions, linking back to the Epic issue number.
- If no page exists: create one (prefer the GitHub wiki if available, otherwise `docs/glossary.md`), seeding it with the terms defined in this Epic.
- Always keep (or add) the greppable **STE allowlist** table in `docs/glossary.md` per the **Glossary shape** in `../references/ste-writing.md` — one row per term with Kind `actor` | `verb` | `object` | `context` | `event` and a Source pointing at this Epic.

If no terms were introduced, skip without comment. If an update was made, report only the page name and terms added.

### 11. Offer to continue

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "What's next?"
- header: "Next step"
- options:
  - **Plan all Features** → invoke `wtf.epic-to-features`, passing the Epic number in as context (default)
  - **Write one Feature** → proceed with `wtf.write-feature`, passing the Epic number in as context so the user is not asked for it again
  - **Write another Epic** → restart this skill from step 1
  - **Stop here** → exit, no further action
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall