retrospective-codify

Retrospective Codify

In the final stage of a task, extract the knowledge that "if I had known this first, I would not have taken a detour," and fix it into one of the following: a static rule, a skill, or an always-on rule. Prioritize distilling it into a reproducible form rather than relying on prompts.

When to use

Immediately before completing a task, or when instructed by the user to "leave the learnings" or "turn it into a rule"
When you arrived at a solution after trial and error (got stuck on the first move, formed an incorrect hypothesis, wasted time due to insufficient documentation, etc.)
When there is a possibility of doing the same kind of task again in the future

When not to use:

A simple task that succeeded on the first try (there is no learning to extract)
A one-off, project-specific response (a commit message is sufficient)

Workflow

Failure⇄success mapping: Write out the following 3 points from this task.
- The first attempt (what you did / how it failed)
- The final solution (what worked)
- The insight that bridged them (why the first attempt did not get there)
Verbalizing "what should have been known first": Summarize the insight in 1 to 3 sentences. Write it not as a retrospective, but in imperative form addressed to your future self ("do not ~" / "check ~ first").
Classification: Decide the output destination according to the decision table below.
Duplicate check (required): Before proposing, check against existing knowledge. If there is a duplicate or a closely related rule, choose "append to / update the existing one" rather than "add new." Neglecting this causes skills / rules to bloat.

Extract 2 to 3 words from the insight as candidate search keys (tool names, API names, symptom words, antonyms). Example: if the insight is "use pnpm v10," then pnpm, packageManager, lockfile。

Comparison targets and minimum search:
```
# skill 重複（global）
ls ~/.claude/skills/
Grep "<キー>" ~/.claude/skills/*/SKILL.md

# CLAUDE.md 重複
Grep "<キー>" ~/.claude/CLAUDE.md
Grep "<キー>" <project-root>/CLAUDE.md   # 該当プロジェクトがある場合

# lint ルール重複
ls <project-root>/rules/
Grep "<キー>" <project-root>/rules/
```
Classify the results into 4 levels:
- New: No hits → normal proposal
- Append to existing: A related skill/rule exists, and the additional information is complementary → propose "append to existing"
  - "Partial duplicate" (only part of the learning is covered by existing knowledge, and the rest is new) is also included in this classification. Write the duplicated part in the "Duplicate detection" section, and the new part in the "Adoption candidates" section ([skill 追記] or [rule]).
- Duplicate of existing (no proposal needed): Existing knowledge already fully covers it → zero proposals, but leave a "duplicate detection" line in the presentation format (for auditability). For the duplicate detection line, attach the existing skill name + the relevant section name (or line number) as evidence.
- Judgment deferred: The agent cannot determine whether it is a duplicate → show the user the comparison result and ask them to decide
Write-out: Generate the artifact according to the template for the chosen format (described later).
Confirmation: Show the diff to the user and get approval on whether to adopt it. If rejected, keep it as a note within the session rather than as a skill.

Classification decision

digraph classify {
    "機械的に検出可能？" [shape=diamond];
    "毎回適用すべき短い指示？" [shape=diamond];
    "複数ステップの手順や判断を伴う？" [shape=diamond];
    "ast-grep ルール / lint" [shape=box];
    "CLAUDE.md ルール" [shape=box];
    "skill" [shape=box];
    "メモに留める" [shape=box];

    "機械的に検出可能？" -> "ast-grep ルール / lint" [label="yes"];
    "機械的に検出可能？" -> "毎回適用すべき短い指示？" [label="no"];
    "毎回適用すべき短い指示？" -> "CLAUDE.md ルール" [label="yes"];
    "毎回適用すべき短い指示？" -> "複数ステップの手順や判断を伴う？" [label="no"];
    "複数ステップの手順や判断を伴う？" -> "skill" [label="yes"];
    "複数ステップの手順や判断を伴う？" -> "メモに留める" [label="no"];
}

Judgment axis	Output destination	Example
Detectable at the code/config syntax level	`ast-grep` Rule or existing linter configuration	"`Array.from(set).length` Don't use,`set.size` Use"
Short, always applicable, involves no judgment	`CLAUDE.md`（user global / project）	"Use pnpm v10 or higher"
Requires procedures, contextual judgment, or a template	New skill or addition to an existing skill	"Procedure for writing MoonBit C bindings"
Project-specific and one-off	Do not adopt (keep it in the commit message / PR description)	—

The principle of prioritizing ast-grep: Anything statically detectable must not be written in prompts or documents, but always in ast-grep make it a rule (the user's global rule).

CLAUDE.md write-out destination:

Cross-language, cross-tool general rules → ~/.claude/CLAUDE.md
Specific repository only → that repository's CLAUDE.md

Output template

ast-grep rules

ast-grep-practice See the skill.rules/ Add YAML to the directory, andrule-tests/ always write valid / invalid pairs in

Addition to CLAUDE.md

# <既存セクションに追記>
- <命令形の 1 文>（理由: <短い根拠>）

Always attach the reason in parentheses (so your future self can judge edge cases).

New skill

writing-skillsFollow the minimal template (superpowers):

---
name: <kebab-case>
description: Use when <具体的な状況> / <症状>
---

# <Title>

## 目的
## いつ使うか
## ワークフロー
## 落とし穴

Concrete examples

Example 1: Converting to an ast-grep rule (machine-detectable)

First attempt: In TypeScript, getting the size of a collection with Array.from(set).length , but a review pointed out it was inefficient.
Final solution: set.size Use.
Insight: Set / Map To get the size of .size use the property.Array.from(...).length Is detectable at the syntax level.

→ rules/no-array-from-size.yml Added:

id: no-array-from-size
language: TypeScript
severity: warning
rule:
  pattern: Array.from($COLL).length
message: Set/Map のサイズは .size プロパティを使う。

Example 2: Making it a CLAUDE.md rule (a short always-on rule)

First attempt: pnpm install When run, CI failed due to a lockfile format diff.
Final solution: Aligned the pnpm version to the v10 series.
Insight: pnpm's lockfile changes with version differences. Always use v10 or higher.

→ ~/.claude/CLAUDE.md Added to the "Tools" section of

- pnpm は v10 以上を使う（理由: lockfile 形式が v9 以前と非互換で CI 差分が出る）

Example 3: Making it a new skill (involves procedures + judgment)

First attempt: When calling a C library from MoonBit, I tried several methods and got stuck on FFI declarations and stub placement.
Final solution: extern "c" declaration + moonbit.h stub using + moon.pkg.json の native-stub / link.native combination of settings.
Insight: It doesn't fit in a single procedure; you need to understand all three layers at once: declarations, stubs, and build settings.

→ New skill moonbit-c-binding Extract the procedure and template as (since it already exists, this example is a case of choosing "append to existing via duplicate check").

Red flags (beware of rationalization)

If the following thoughts come up, pause once.

Rationalizations that come up	Reality
"It's project-specific, but let's make it a skill anyway"	The skill becomes bloated and less searchable. A commit message / PR is enough.
"Let's skip approval and write it out first; we can show it later"	If you change CLAUDE.md / skills on your own, future behavior becomes unpredictable. Always propose → approve → write out.
"I feel like it could be written with ast-grep, but writing the rule in natural language is faster"	If you write something statically detectable in prose, the agent won't follow it. Prefer ast-grep.
"The insight is thin, but it won't look right unless I write something"	Zero proposals is also correct. An empty retrospective is harmless.
"Duplicate checking is a hassle, so let's skip it; if there's overlap, we can delete it later"	If duplicate rules remain, behavior diverges. Dedup is a required step.
"Let's omit the failure side and write only the final solution"	Without a description of the failure, your future self will fall into the same pitfall again.

Format for presenting to the user

At task completion, present the inventory in the following form.There can be multiple learnings. Explicitly list duplicates and rejected items too, leaving a trail of decisions.

## Retrospective

### 学び 1: <短いラベル>
- 最初の失敗: <1 行>
- 最終解: <1 行>
- 気付き: <1 行>

### 学び 2: <短いラベル>      # 学びが 1 つだけならこのブロックは省く
- 最初の失敗: <1 行>
- 最終解: <1 行>
- 気付き: <1 行>

## 提案

採用候補:
- [lint] <ルール名>: <1 行>（artifact: <path>, 学び N 由来）
- [skill 追記] <既存 skill 名>: <1 行>（学び N 由来）
- [skill 新規] <skill 名>: <1 行>（学び N 由来）
- [rule] CLAUDE.md（global/project）: <1 行>（学び N 由来）

重複検出（提案不要）:
- <学び N>: 既存 <skill/rule 名> の <該当節名 or 行番号> が完全カバー → 追加なし

不採用:
- <学び N>: <不採用理由 1 行>（例: プロジェクト固有 / cross-file で lint 表現困難 / 他の学びに吸収）

採用するものを番号または項目名で指示してください。提案ゼロも妥当な結論です。

Format rules:

If there is 1 learning, ### 学び N omit the heading and write only 1 Retrospective block
If any of "adoption candidates", "duplicate detection", or "rejected" is empty, omit that whole section (do not write a "none" line)
At the end of each proposal line, always write "from learning N" (if it spans multiple learnings, you may list them like "from learnings 1, 3")
When "adoption candidates" is empty and only "duplicate detection" remains, change the closing sentence to 採用するものを指示してください instead of 採用候補なし。記録目的でレビューしてください。 replace with
Write out only the items the user instructed to adopt. Do not write them out silently.

Presentation example: all learnings already covered (duplicate detection only)

## Retrospective

### 学び 1: <ラベル>
- 最初の失敗: ...
- 最終解: ...
- 気付き: ...

## 提案

重複検出（提案不要）:
- 学び 1: 既存 skill `<skill 名>` の `<節名>` が完全カバー → 追加なし

採用候補なし。記録目的でレビューしてください。

Presentation example: partial duplication (append to existing + duplicate detection)

## 提案

採用候補:
- [skill 追記] <既存 skill 名>: <新規部分の 1 行>（学び 1 由来, 既存節 `<節名>` への補完）

重複検出（提案不要）:
- 学び 1（version 値部分）: 既存 `~/.claude/CLAUDE.md` ツール節が既にカバー → 追記不要

Common failures

Granularity is too fine: Turning even one-off circumstances (a specific function name, a specific version) into rules → abstract it and raise it to the level of "what to check"
Tendency to write in prompts: Writing statically detectable rules in natural language in CLAUDE.md → ast-grep move them to rules
Not writing the reason: The basis for the rule is not preserved, and your future self cannot judge why it should be followed → always Why: attach
Writing out without permission: Updating CLAUDE.md or skills without user approval → always follow the order of proposal → approval → writing out
Skipping verbalizing failures: Writing only "the final solution is X" and not preserving why you got stuck on the first move → without a description of the failure side, your future self will fall into the same pitfall again

Related skills

superpowers:writing-skills — Template and TDD flow for writing a new skill
ast-grep-practice — How to write and test when turning into a lint rule
update-config — When changes to settings.json / permissions are needed