Change Recap — Work retrospective → Knowledge sedimentation

When to use

After a piece of work wraps up (feature complete / error handling / milestone archive / a refactor), explicitly invoke this skill to review and extract knowledge worth sedimenting, then persist it to project docs for reuse by future development and review.

When NOT to use

• During in-flight work — this is an end-of-work retrospective, not a mid-task logger.
• For project progress / phase state changes — use phase-tracking.
• For bug prevention specifics that error-handling stage 4/5 already covered — see step 4 below.

Core principles (reasoned, not absolute)

1. Each sedimentation item must be confirmed one by one — list candidates (content + location + value); write only after the user explicitly agrees. Do not default to "approve all" — every item needs a yes. Reason: silent batch writes are how scope creep and unwanted edits slip in.
2. Explicit trigger only — this skill does not auto-run, and is not embedded into other flows to fire automatically. Reason: sedimentation requires reflective judgment, which auto-triggers short-circuit.
3. Skip items already covered by error-handling — if the candidate comes from a just-finished error-handling session (stage 4/5 already sedimented code review / tests), mark and skip. Reason: avoid duplicate proposals for the same knowledge.
4. Dedup by semantic comparison (not keyword grep) — judge whether the candidate is already covered by some existing sedimented item, even if worded differently.
5. Granularity rule — only extract items meeting at least one of: "a pitfall that will recur", "a pattern that will be reused", "a decision affecting future work". One-off details and items already in existing docs are not extracted.
6. Mapping is a reference, not a mechanical rule — the category-to-location mapping gives "default destinations", but each candidate's placement should consider the actual situation (pitfall substance + section semantics). When in doubt, discuss with the user — do not apply the mapping blindly.

Process

1. Define the retrospective scope

Confirm with the user which stretch to review: this change / this error-handling session / this conversation / a specified range.

2. Extract candidates (four categories)

• Build / environment config pitfalls (build-toolchain versions, dependency conflicts, build parameters, environment variables, CI config).
• Code traps / API misuse (framework / library specific gotchas, concurrency / timing traps, lifecycle misuse, error-handling mistakes).
• Architecture / process decisions (chose A over B + reason; module boundary setting; conventions established).
• Temporary by-products (debug entry points / placeholders / TODOs — annotate as temporary + deletion condition).

3. Dedup (semantic comparison)

For each candidate, compare against existing sediments (any project knowledge base — progress-tracking doc, decision doc, review checklist, CLAUDE.md, etc. If none exists, skip this step). Judge at the semantic level whether the candidate is already covered; if so, drop or merge.

4. Skip items already covered by error-handling

If a candidate was already sedimented by error-handling stage 4/5 in this session (code-review item / test), mark "already sedimented by error-handling" and do not propose again.

5. Categorize → location (mapping as reference, judge by situation)

Default location mapping (if the project has no corresponding doc, first discuss with the user whether to create one or merge into an existing doc):

Trap-category example (map by the project's actual layers — not a fixed checklist):

⚠️ Mapping is only a default reference: when categorizing, judge by the pitfall's substance and the section's semantics to pick the best fit. If the project has no review checklist yet, prompt the user to consider creating one (do not fabricate content). For cross-layer cases or any doubt, discuss with the user — do not apply the mapping blindly.

6. Propose list (must wait for user confirmation)

Output:

• The "existing-similar reference" column points out similar items already in the doc (e.g., "concurrency chapter item 5 already covers X timing; this one is related but different"), helping the user decide dedup / merge / placement.

Wait for confirmation item by item. The user can: select all / partial / adjust wording / adjust location / reject. Items without explicit agreement are not written.

7. Write

For confirmed items, use Edit on the corresponding doc (insert into the right section, preserve existing format, do not touch unrelated content).

8. Summary

Output: what was sedimented (with locations) + what was skipped (covered by error-handling / deduped) + what the user rejected.

Boundaries

• error-handling stage 4/5 — narrow bug-specific prevention. This skill skips items it already sedimented.
• phase-tracking — milestone progress (numerical). No overlap with this skill.
• code-review — consumes the review checklist to do reviews. This skill sediments new review items into the checklist (expands its content).