andurilcode Kintsugi (金継ぎ) — Codebase Repair Visibility
Every bugfix, workaround, hotfix, defensive pattern has a story. When invisible, the codebase loses institutional memory and developers repeat past mistakes. Gold = context (comments, ADRs, test annotations, docs) making past repairs legible.
Input Modes
/kintsugi
Scan full codebase + recent git history. Produce gilding backlog.
/kintsugi "focus description"
Scope examples: "auth module", "last 3 months of hotfixes", "defensive null checks", "dependency pins".
When focused: lead with focus findings, mark others [ALSO NOTED], still scan all scar types.
The Scar Taxonomy
Scars are past repairs. Each has gold (context) or is bare (story lost).
| Scar type | Detection signal |
|---|---|
| Workaround | Code avoiding a known issue without explaining which |
| Defensive guard | Null check / try-catch / retry not in original design, no comment on what fails |
| Magic value | Hardcoded timeout, retry count, batch size, threshold without rationale |
| Regression test | Test exists because something broke, but name doesn't reference what |
| Dependency pin | Version pin without comment explaining what breaks if upgraded |
| Reverted pattern | Code redone differently with no trace of why previous approach failed |
| Silent migration | Compatibility shim handling "old format" without migration explanation |
| Config override | Non-default value without explaining why default doesn't work |
Five Dimensions — Execute in Order
D1 — Scar Discovery (傷の発見)
Vector A — Git archaeology: scan commits for repair keywords:
fix, bugfix, hotfix, patch, workaround, revert, rollback, handle edge case, prevent, guard against, fallback, retry, defensive, incident, postmortem, outage, regression
Per repair commit: SCAR [sha] [date] | Message: [...] | Files: [...] | Gold: [yes/no]
Vector B — Code patterns: grep for each scar type from the taxonomy.
Output: SCAR INVENTORY — Total: [N] (git: [N], code: [N], lookback: [period])
D2 — Gold Audit (金の監査)
Grade each scar:
| Level | Meaning |
|---|---|
| 🥇 Full gold | Why documented, linked to ticket/incident, immediately understandable |
| 🥈 Partial gold | Some context but incomplete — "fix for prod issue" with no specifics |
| ⬜ Bare scar | Story completely invisible |
Per scar:
[SCAR] [type]
📍 [file:line or commit]
Visibility: [🥇 | 🥈 | ⬜]
Story: [reconstructed from git context — state confidence and evidence]
Missing gold: [what context is absent]
D3 — Gilding Backlog (金継ぎバックログ)
Primary deliverable. Prioritize bare and partial-gold scars.
Scoring (each 1–3):
- Blast radius: shared utility=3, isolated file=1
- Decay risk: author left=3, still on team=1
- Confusion potential: looks like dead code=3, obviously defensive=1
Gold types:
| Gold type | Example |
|---|---|
| Inline comment | // Retry 3x: Service Y cold-start up to 30s (#1234) |
| Block comment | /* WORKAROUND: API returns stale cache ~5min after deploy... */ |
| Test annotation | Rename test + description linking to original bug |
| ADR | docs/adr/003-sync-vs-async-payments.md |
| Pin comment | // Pinned: v3.0 breaks SSO callback, see #5678 |
| CHANGELOG entry | Date + explanation of significant past fix |
金継ぎ GILDING BACKLOG
# Score Type Scar Gold to apply
1 3.0 Inline comment Bare retry payments.ts:89 Add incident context
2 2.7 Pin comment Lodash pinned 4.17.21 Explain breaking change
...
Cap at 10 items. Each implementable in one small PR.
D4 — Kintsugi Health Score (金継ぎ健康スコア)
KINTSUGI HEALTH
Total scars: [N] | 🥇 [N] ([%]) | 🥈 [N] ([%]) | ⬜ [N] ([%])
Health score: [% with full or partial gold] Target: 80%+
D5 — Prevention Compass (予防の羅針盤)
Each rated 🟢 In place | 🟡 Partial | 🔴 Missing:
COMMIT HYGIENE: [Message standards enforced? Template/hook?]
FIX TEMPLATES: [PR template prompts "what broke and why"?]
INCIDENT LINKS: [Postmortem learnings linked back to code?]
TEST NAMING: [Test names carry story of what they prevent?]
PIN DISCIPLINE: [Convention for commenting dependency pins?]
Report Assembly
- Header: Codebase, focus or "Full scan", date, git lookback
- Health Score (D4) — headline
- Gilding Backlog (D3) — hero section
- Scar Inventory (D1) — counts by type
- Detailed findings (D2) — bare scars with reconstruction, grouped by type
- Prevention Compass (D5)
"金継ぎの心: 傷は隠すものではなく、金で照らすもの。"
Calibration Rules
- Gold, not noise:
// fixis not gold. Gold carries the why. Low-context comments are bare scars disguised as gold. - Reconstruct honestly: state confidence, cite evidence, don't make unsupported claims.
- Don't gild the obvious: try/catch around file I/O needs no explanation. Gild only where the reason for this specific pattern is non-obvious.
- Prioritize by decay risk: author left recently → urgent. Stable team → can wait.
- One PR, one scar: don't bundle unrelated context additions.
- Git lookback: default 6 months unless user specifies.
- Never change behavior: gold is always documentation. Never modify logic, refactor, or change tests.