Retro

Close a completed Epic with a structured retrospective.

This skill compares what was planned (original Epic spec) against what shipped (closed Tasks + PRs). It reports deviations. It routes learnings into steering docs. It closes the Epic so the team starts the next initiative with a clean slate.

Process

0. GitHub CLI setup

Run steps 1–2 of ../references/gh-setup.md. Stop if gh is not installed or not authenticated.

1. Identify the Epic

If an Epic number was passed in, use it directly. Otherwise call AskUserQuestion (per ../references/questioning-style.md):

• question: "Which Epic are you closing out?"
• header: "Epic"
• options: from open Epics — list them per the List issues of a kind query (kind Epic) in ../references/issue-classification.md (--label epic in labels mode, --search 'type:"Epic"' in types mode)

Fetch the Epic and its full hierarchy:

gh issue view <epic_number>
gh sub-issue list <epic_number>              # feature numbers
# For each feature (in parallel):
gh issue view <feature_number>
gh sub-issue list <feature_number>           # task numbers
# For each task (in parallel):
gh issue view <task_number>

Also fetch:

• All PRs that closed issues under this Epic (search by Closes #<n> in merged PRs):

``bash gh pr list --state merged --json number,title,body,mergedAt --limit 100 ``

• The original Epic creation date and the date of the last merged PR (actual duration)

2. Check completion status

Verify all work is actually done before you run a retro:

• All child Features are closed
• All child Tasks are closed (or explicitly marked won't implement)
• No open PRs targeting feature branches under this Epic

If anything is still open, call AskUserQuestion (per ../references/questioning-style.md):

• question: "Not all work is closed yet — [list open items]. Run the retro anyway?"
• header: "Incomplete work"
• options:

- Run retro anyway → some items are open. Note them as incomplete. - Wait until complete → exit. Finish the remaining work first.

3. Compare planned vs. shipped

Build a side-by-side comparison:

Planned (from original Epic spec):

• Goal statement
• Success Metrics
• Feature Breakdown (original list from Epic body)
• Bounded Context

Shipped (from closed issues and PRs):

• Features actually created and merged
• Tasks actually created and merged
• Actual calendar duration (Epic opened → last PR merged)

Identify deviations:

• Features planned but not built (descoped or deferred)
• Features added that were not in the original breakdown (scope growth)
• Tasks that took significantly more iterations than expected (PR re-open, multiple verify cycles)
• Success Metrics: were they actually achieved? State what you can verify from the spec. Flag ones that require manual measurement.

4. Gather learnings

Only ask what is not already evident from the issue history. For each question below, call AskUserQuestion (per ../references/questioning-style.md).

Q1 — What was harder than expected?

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "What was harder or took longer than planned in this Epic?"
• header: "Friction points"
• options: 2–3 inferences from the deviation analysis (e.g. "Feature #X needed 3 verify cycles", "Task #Y was unscoped after implementation started")

Q2 — What should we do differently next time?

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "If you ran this Epic again, what would you change about how it was planned or executed?"
• header: "Process improvements"
• options:

- Better scoping upfront → scope drift was the main issue - Earlier design → design gaps caused implementation rework - Clearer contracts → interface ambiguity caused re-work - Nothing significant → execution was smooth

Q3 — Any domain model insights?

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Did this Epic reveal anything new about the domain model — new concepts, corrected names, missing bounded contexts?"
• header: "Domain insights"
• options:

- Yes — describe them → new terms or corrections to capture - No domain changes → model held up well

5. Route learnings to steering docs

For each learning gathered, determine where it belongs using the same routing table as wtf.reflect:

For each target doc, append under ## Hard-Won Lessons using the format:

- **[Short label]** — [Concrete rule or observation]. *Learned <YYYY-MM-DD> during Epic #<n>.*

Commit the steering doc updates:

git add docs/steering/
git commit -m "docs(steering): lessons from Epic #<epic_number>"

If any domain model insights were gathered (Q3), also update the glossary. Use the same pattern as wtf.write-epic step 10. Include the greppable STE allowlist table in docs/glossary.md per ../references/ste-writing.md.

6. Write the retro summary

Apply strict STE per ../references/ste-writing.md before writing any durable body (retro comment and any Hard-Won Lessons prose).

Post a structured retro comment on the Epic issue:

# Write the retro summary to a temp file with the Write tool; $COMMENT is that path.
python3 .wtf/gh-body.py comment <epic_number> --body-file "$COMMENT"

The retro summary must include:

## Retrospective — <YYYY-MM-DD>

**Duration:** <Epic opened> → <last PR merged> ([n] days)

### Planned vs. shipped

| Item | Planned | Shipped | Delta |
|------|---------|---------|-------|
| Features | [n] | [n] | [+n added / -n descoped] |
| Tasks | [n] | [n] | ... |

**Descoped:** [list features/tasks that were planned but not built — with reason]  
**Added:** [list features/tasks added beyond original scope — with reason]

### Success Metrics

| Metric | Target | Achieved |
|--------|--------|----------|
| <from Epic spec> | <value> | ✅ / ❌ / ⚠️ needs manual check |

### Lessons learned

[Bullet list of the learnings gathered in step 4 — in plain language, not the steering doc format]

### Steering docs updated

[List which docs were updated with new lessons]

7. Offer to generate a changelog

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Would you like to generate a changelog entry or GitHub Release for this Epic?"
• header: "Changelog"
• options:

- Yes — run changelog → run wtf.changelog for this Epic (recommended) - Not now → skip. The user will handle the release notes separately.

If yes → follow the wtf.changelog process with the Epic number pre-loaded as context.

8. Close the Epic

The Epic closes automatically when all child Feature PRs contain Closes #<featurenumber>, which in turn contains Closes #<epicnumber> — via GitHub's auto-close chain. Confirm this has happened:

gh issue view <epic_number> --json state -q .state

If the Epic is already CLOSED → print: "Epic #<n> is already closed via merged PRs. Retro complete."

If still open (e.g. auto-close chain did not fire): ask the user whether to close it via a merged PR reference or directly:

Call AskUserQuestion (per ../references/questioning-style.md):

• question: "Epic #<n> is still open. How would you like to close it?"
• header: "Close Epic"
• options:

- Close as completed → mark as closed. All work is done. - Leave open → the user will close it separately.

If "Close as completed":

gh issue close <epic_number> --comment "Closed after retro — all Features and Tasks merged."

9. Print the final summary

Retro complete — Epic #<n>: <title>
──────────────────────────────────────
Duration:      [n] days
Features:      [n] shipped / [n] descoped
Tasks:         [n] merged
Learnings:     [n] captured → TECH.md, QA.md, ...
Epic status:   closed ✅