retro-notes
Capture AI-readable postmortems after a dev attempt resolves into a project-scoped lessons file that future /big-plan runs can read. Use when: (1) User says 'retro-notes', 'retro', 'capture lessons', 'fail-notes', 'postmortem', (2) A dev session wrapped up that took longer than expected, changed approach mid-way, or had non-obvious gotchas. Reader is a future planning agent.
Best use case
retro-notes is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Capture AI-readable postmortems after a dev attempt resolves into a project-scoped lessons file that future /big-plan runs can read. Use when: (1) User says 'retro-notes', 'retro', 'capture lessons', 'fail-notes', 'postmortem', (2) A dev session wrapped up that took longer than expected, changed approach mid-way, or had non-obvious gotchas. Reader is a future planning agent.
Teams using retro-notes should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/retro-notes/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How retro-notes Compares
| Feature / Agent | retro-notes | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Capture AI-readable postmortems after a dev attempt resolves into a project-scoped lessons file that future /big-plan runs can read. Use when: (1) User says 'retro-notes', 'retro', 'capture lessons', 'fail-notes', 'postmortem', (2) A dev session wrapped up that took longer than expected, changed approach mid-way, or had non-obvious gotchas. Reader is a future planning agent.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Retro Notes
## Purpose
Convert lessons from a just-resolved dev attempt into a structured, project-scoped lessons file (`/l-lessons-{area}` skill) that future planning runs (e.g. `/big-plan`) can consume. Goal: turn one-time pain into permanent leverage so the next attempt in the same area is faster.
## Pre-flight check (mandatory)
Before writing, confirm two things:
1. **Is the work actually wrapped up?** If the user is still mid-struggle, ask them to confirm. Mid-struggle notes record symptoms, not root causes — they crystallize the wrong lesson. If unresolved, suggest they invoke this skill again after the fix lands.
2. **What's the project area?** Look at the current working directory, recently touched files, and conversation topic. Propose a project-area name (kebab-case, e.g. `canvas-tools`, `tauri-window-mgmt`, `react-form-state`). Confirm with the user before writing.
## Locate or create the lessons file
The output is a project-scope skill at `.claude/skills/l-lessons-{area}/SKILL.md`.
**One growing file per problem-area, NOT one file per attempt.**
1. Check `.claude/skills/` for any existing `l-lessons-*` skill that matches the area. If a relevant one exists, **append** a new dated section to its `SKILL.md`.
2. If none exists, scaffold a new skill at `.claude/skills/l-lessons-{area}/SKILL.md` with the frontmatter shown below.
### Frontmatter for new lessons files
```yaml
---
name: l-lessons-{area}
description: Project lessons learned for {area}. Read PROACTIVELY before planning or implementing work touching {area} — contains traps, root causes, and "watch for next time" notes from previous attempts.
---
```
Keep `description` short but concrete enough that planning agents pick it up automatically.
## Note template
Append (or create) a section using exactly this structure:
```markdown
## {YYYY-MM-DD} — {short topic}
### What we set out to do
{1–2 sentences. The original goal, not the implementation.}
### Approach we tried first
{The wrong path. Be specific about the abstraction or structural choice — not the symptom.}
### Why it went wrong (root cause)
{The structural cause, not the symptom. See "Symptom vs root cause" below.}
### What worked instead
{The right abstraction or approach.}
### Watch for next time
- {Concrete trap, ideally in "if you see X, you're probably Y" form.}
- {Another trap. Aim for 2–5 bullets, not narrative.}
### Would-skip-if-redoing
{Things that wasted time and are now provably unnecessary. One short paragraph or bullet list.}
```
The **Watch for next time** section is the highest-leverage part. Future planning agents will scan it first. Keep bullets concrete and trap-shaped.
## Symptom vs root cause
When the user offers a symptom-shaped description, probe for the structural cause before writing.
| Symptom (what the user says first) | Root cause (what to actually record) |
|---|---|
| "zoom was buggy" | "transform threaded through every function instead of inverted at input boundary" |
| "form kept losing state" | "state owned by child instead of lifted to parent that survives re-mount" |
| "the build was flaky" | "test relied on filesystem ordering not guaranteed by the runtime" |
| "performance was bad" | "N+1 query in the render loop, hidden behind an inner abstraction" |
If the user gives a symptom, ask: "What was the actual structural reason that made the symptom show up — what was wrong about the shape of the code, not the bug itself?" Record the structural answer. The symptom can stay as one phrase in **What we set out to do** or **Approach we tried first** for context.
## Writing style
- **Terse.** The reader is a future LLM scanning for relevant patterns, not a human reading prose. Cut adjectives, cut narrative.
- **Specific over general.** "Coordinate transforms must invert at input boundary" beats "be careful with coordinates."
- **Past tense, no apology.** "We threaded the transform through every function" — not "I made a mistake by..."
- **No grep-able blame.** Don't name people or PRs; the lesson is structural.
## After writing
Briefly tell the user:
1. The lessons file is at `.claude/skills/l-lessons-{area}/SKILL.md` and will be picked up by future `/big-plan` runs (assuming `/big-plan` is wired to read `l-lessons-*` skills — that's a separate tweak via `/skill-creator`).
2. Suggest a periodic `lessons-refactor` pass (manual for now) every few months: merge overlapping notes, delete advice for code that no longer exists, promote repeated lessons into broader wisdom.
3. If the retro produced "nothing surprising, plan matched reality," that's signal too — the area is now well-mapped, future planning in this area can be lighter.
## When NOT to invoke this skill
- The work is still in progress or stuck.
- The dev was trivial and went exactly as planned (no lesson to extract).
- The lesson is universal CSS/JS knowledge that belongs in a global wisdom skill (e.g. `/css-wisdom`), not a project-scoped one.Related Skills
retro-notes-refactor
Refactor an accumulated `l-lessons-*` skill (created by /retro-notes) when later entries partially supersede or extend earlier ones, so future planning agents see the cross-cutting wisdom first instead of having to read every dated entry. Use when (1) the user says "lessons refactor", "retro refactor", "retro-notes refactor", "refactor lessons", or "synthesize lessons", (2) a `/retro-notes` session just added a new dated entry that broadens / narrows / contradicts a claim in an earlier entry on the same area, (3) an `l-lessons-*/SKILL.md` has 5+ dated entries on the same problem area OR exceeds ~500 lines, (4) the next `/big-plan` run in that area would have to scan many entries to find the relevant pattern. Produces a top-of-file "Recurring patterns (synthesized)" section in Trigger/Action/See format, adds Caveat notes to entries whose claims were later widened, updates the frontmatter description with pattern keywords, and formats with mdx-formatter. Does NOT delete historical entries — they remain as terse drill-down postmortems. Pair with /retro-notes (which writes new entries) and /big-plan (which reads the synthesized section first).
zudoesa-articlify
Convert conversation context into an esa article via the zudoesa-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write esa article', 'esa記事', 'esaに書いて', 'articlify for esa', or /zudoesa-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zudoesa-apply-voice
Apply Takazudo's esa writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's esa style, (2) User says 'apply voice', 'esa voice', 'esa文体で', 'esa風に書いて', '文体を適用', (3) User provides text to transform to esa style. Reads writing-style.md and vocabulary-rule.md from takazudo-esa-writing repo and applies the rules.
zudocg-articlify
Convert conversation context into a CodeGrid article via the zudocg-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write codegrid article', 'CodeGrid記事', 'codegridに書いて', 'articlify for codegrid', or /zudocg-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zudocg-apply-voice
Apply Takazudo's CodeGrid writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's CodeGrid style, (2) User says 'apply voice', 'codegrid voice', 'codegrid文体で', 'codegrid風に書いて', '文体を適用', (3) User provides text to transform to CodeGrid style. Reads writing-style.md and vocabulary-rule.md from takazudo-codegrid-writing repo and applies the rules.
zpaper-articlify
Convert conversation context into a zpaper blog article via the zpaper-writer subagent. ONLY invoke when the user explicitly asks — NEVER proactively propose. Triggers: 'write zpaper article', 'zpaper記事', 'zpaperに書いて', 'articlify for zpaper', or /zpaper-articlify. Gathers context, creates a writing brief, delegates to the writer subagent.
zpaper-apply-voice
Apply Takazudo's zpaper blog writing voice and vocabulary rules to text. Use when: (1) User wants to write/rewrite text in Takazudo's zpaper style, (2) User says 'apply voice', 'zpaper voice', 'zpaper文体で', 'zpaper風に書いて', 'ブログ文体を適用', (3) User provides text to transform to zpaper style. Reads writing-style.md and vocabulary-rule.md from the zpaper repo and applies the rules.
xlsx
Spreadsheet creation, editing, and analysis. Use when working with .xlsx, .xlsm, .csv, .tsv files for: (1) Creating spreadsheets with formulas and formatting, (2) Reading or analyzing data, (3) Modifying existing spreadsheets while preserving formulas, (4) Data analysis and visualization, (5) Recalculating formulas.
x
Facade for development workflows. Routes on two axes: plan-first vs implement-now (escalates to /big-plan -a when the request needs research / decomposition / has unclear scope — the appended -a makes the plan chain into implementation in-session), then single vs multi on the ready-to-build fast paths (/x-as-pr single-topic, /x-wt-teams multi-topic parallel). Use when: (1) User says '/x' followed by dev instructions, (2) User wants to start development without choosing the workflow skill, (3) User says 'dev', 'implement', or 'build' with a task. Default option: -v (verify-ui). Review-loop (-l) is opt-in — without -l the downstream skill runs a single /deep-review pass. Forwards -a (autonomy/auto-chain) and -m (merge at the end + cleanup + CI watch) through every route; auto-fix of raised findings (-f) and issue-raising (-ri) are downstream defaults, with -nf/--no-fix and -nori/--no-raise-issues as the forwarded opt-outs. -a and -m are orthogonal — full hands-off end-to-end is -a -m.
x-wt-teams
Parallel multi-topic development using git worktrees, base branches, and Claude Code agent teams. Use when: (1) User wants to work on multiple related features in parallel, (2) User mentions 'worktree', 'base branch', 'parallel development', 'split into topics', or 'multi-topic'. FULLY AUTONOMOUS — creates worktrees, spawns teams, coordinates everything. Also supports Super-Epic child mode for [Epic] issues from /big-plan with '**Super-epic:** #N' markers (targets the super-epic base branch instead of main).
x-as-pr
Start a development workflow as a draft PR. Creates a NEW branch from the current branch, empty start commit, draft PR targeting the current branch, then implements. ALWAYS creates a new branch by default — produces a nested PR-on-PR when the current branch already has one. Use when: (1) User says 'dev as pr', (2) User wants a PR-first workflow before coding, (3) User passes -s/--stay to reuse the current branch instead of nesting, (4) User passes a GitHub issue URL to implement, (5) User passes --make-issue/--issue to create an issue first. Logs progress via issue comments when an issue is linked.
watch-ci
Watch GitHub PR CI checks in the background and notify on completion. Use when: (1) User wants to monitor CI/CD status, (2) User says 'watch CI', 'check CI', 'monitor checks', or 'wait for CI', (3) User wants to know when checks pass or fail. Runs a background gh polling shell loop (NOT a subagent — near-zero token cost), sends macOS notification on completion. Also handles merged PRs by watching the target branch CI.