xiduzo/wtf / skills/wtf.write-epic
wtf.write-epic
VerifiedThis 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.2 KB |
SKILL.md
View on GitHub---
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |