insight-retro
Post-implementation retrospective — map blast radius, audit documentation, extract skills, update KIs, document lessons learned. Trigger when the user runs /retro or asks for a "retrospective", "post-mortem", "lessons learned", or "what changed" after completing significant imple
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/insight-retro
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/retro
Structured reflection after completing large implementations — map what changed, verify documentation accuracy, capture reusable patterns, update knowledge, and flag follow-up work.
Structured execution spec:
protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
Reflection Protocol — run after shipping significant work. Prevents knowledge loss, documentation drift, and tech debt accumulation. Observation only — fixes are separate tasks.
Phase 1 — Blast Radius Mapping
Identify everything that changed during execution. Sources: implementation_plan.md, walkthrough.md, task.md, conversation history, git diff.
Produce a structured manifest:
- Packages touched
- Apps touched
- Files created / modified / deleted
- New exports or APIs introduced
Group changes by package/app. This map drives every subsequent phase.
Gate: cannot proceed without knowing what changed.
Phase 2 — Pattern Extraction
Identify reusable patterns that emerged. Check for: new architectural patterns used in 2+ places; workarounds or gotchas future work will hit; integration patterns between packages not yet documented; novel solutions worth codifying.
For each pattern: name, description, reuse potential (HIGH / MEDIUM / LOW), recommended action (new skill, update existing skill, document in KI, or skip).
Phase 3 — Documentation Audit
For each package/app in the blast radius, audit all documentation surfaces.
Discovery: find README.md, llms.txt, index.yon, *.yon, *.feature.yon, CHANGELOG.md, barrel exports (index.ts).
- For docs/skills repositories: also check
SKILL.mdfiles (description quality, runtime parity), cross-reference maps between skills, per-skill front-matter consistency. Consider a full library-audit pass.
Discover the repository’s actual documentation contract first. Apply the following sidecar thresholds only where that convention is adopted or requested; elsewhere inspect the actual local obligations, without treating absent YON sidecars as defects.
Sidecar audit under that adopted convention: for each significant changed file (>100 LOC, public API, component/hook/route handler/schema) — does a colocated .yon exist? Still accurate? Should one be created?
- New directories with >3 significant files → flag missing
index.yon - Cross-file features touching >2 related files → flag missing
*.feature.yon
README accuracy: verify prose against current code — described APIs still accurate? New features documented? Removed features still mentioned?
Report by severity:
- MISLEADING — docs say X, code does Y (cite both the doc claim and contradicting code)
- STALE — docs describe removed features
- MISSING — new features/files undocumented
- ACCURATE — no action
Phase 4 — Knowledge & Skill Assessment
Knowledge Items: cross-reference changes against existing KI summaries. Report KIs to update (with what changed), KIs to create (with proposed scope), KIs still accurate (no action).
Skills: Resolve a supplied or current host/repository skill catalog and record its scope. If unavailable, keep proposals provisional with duplicate coverage incomplete; a missing index is not an empty library. Cross-reference patterns, libraries, and techniques against existing skills:
- (A) Skill exists and covers it — no action
- (B) Skill exists but is incomplete — specify what's missing or outdated
- (C) No skill exists — evaluate reuse potential (2+ uses, non-obvious decisions, multi-file scope). If warranted, propose: skill name, domain family, key sections, complexity estimate
Verify no existing skill covers the domain via skill-search first — never propose a duplicate.
Phase 5 — Difficulty Analysis
Reflect on execution difficulty. For each: what was harder than expected, what assumptions proved wrong, what took multiple attempts, what external blockers were hit. For each: root cause, resolution, prevention.
Phase 6 — Tech Debt Inventory
Inventory tech debt introduced or discovered: shortcuts taken, TODO/FIXME/HACK comments added, deferred limitations, test coverage gaps, sidecar coverage gaps. For each: severity (LOW/MEDIUM/HIGH), estimated effort, recommended timeline.
Phase 7 — Retrospective Report
Compile the full report:
- Blast Radius Summary
- Patterns Extracted — with recommended actions
- Documentation Audit — gaps, stale sidecars, README accuracy (MUST-DO vs SHOULD-DO)
- Knowledge & Skill Updates — KIs and skills to update/create
- Difficulty Log
- Tech Debt Inventory
- Gate Status — for committed work: the project gate-suite outcome (
pass/fail/skipped — why) and any acceptance criterion left unverified. Name skipped gates and unverified criteria explicitly; a clean-looking retro that omits a coverage hole misrepresents what actually shipped.
Present with actionable next steps.
Rules
- MUST check skill-index first when finding reusable patterns — avoid proposing duplicates
- MUST include skill name, domain family, and estimated content scope when proposing new skills
- MUST propose concrete follow-up when identifying tech debt — not vague observations
- MUST apply significance criteria (>100 LOC, public API, component/hook/route handler/schema) when assessing sidecars
- MUST cite both the doc claim and the contradicting code when finding MISLEADING docs
- MUST NOT fix issues in-line — retro is observation only; fixes are separate tasks
- SHOULD propose creating high-reuse skills immediately after retro
- SHOULD streamline the report to essentials only when blast radius is small (<5 files)
Next Steps
/insight-skill-gap— create/update skills flagged in retro
Human output. This skill's handler-facing output obeys the human-output contract (
human-output/SKILL.md).
Next skills. On completion, run the Next Skills protocol (
next-skills/SKILL.md): surface thenext-skillsrecommendations from front-matter for the caller to pick. Offer only — never auto-invoke.
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
protocol.yon 10.4 KB · in bundle
-
SKILL.md 7.3 KB
--- name: insight-retro description: > Post-implementation retrospective — map blast radius, audit documentation, extract skills, update KIs, document lessons learned. Trigger when the user runs /retro or asks for a "retrospective", "post-mortem", "lessons learned", or "what changed" after completing significant implementation work. Use insight-skill-gap when the goal is specifically to identify new or updated skills. visibility: public self-improvable: true next-skills: - skill: insight-skill-gap phrase: "/insight-skill-gap" why: "Codify recurring patterns into new or updated skills" - skill: human-draw phrase: "/human-draw" why: "Blast radius is proportional and positional — how far the change reached shows in a figure, not in a list of touched files" triggers: - "/retro" - "retrospective" - "post-mortem" - "lessons learned" - "what changed" --- # /retro Structured reflection after completing large implementations — map what changed, verify documentation accuracy, capture reusable patterns, update knowledge, and flag follow-up work. > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. > **Reflection Protocol — run after shipping significant work.** Prevents knowledge loss, documentation drift, and tech debt accumulation. Observation only — fixes are separate tasks. ## Phase 1 — Blast Radius Mapping Identify everything that changed during execution. Sources: `implementation_plan.md`, `walkthrough.md`, `task.md`, conversation history, git diff. Produce a structured manifest: - Packages touched - Apps touched - Files created / modified / deleted - New exports or APIs introduced Group changes by package/app. This map drives every subsequent phase. **Gate:** cannot proceed without knowing what changed. ## Phase 2 — Pattern Extraction Identify reusable patterns that emerged. Check for: new architectural patterns used in 2+ places; workarounds or gotchas future work will hit; integration patterns between packages not yet documented; novel solutions worth codifying. For each pattern: **name**, **description**, **reuse potential** (HIGH / MEDIUM / LOW), **recommended action** (new skill, update existing skill, document in KI, or skip). ## Phase 3 — Documentation Audit For each package/app in the blast radius, audit all documentation surfaces. **Discovery:** find `README.md`, `llms.txt`, `index.yon`, `*.yon`, `*.feature.yon`, `CHANGELOG.md`, barrel exports (`index.ts`). - **For docs/skills repositories:** also check `SKILL.md` files (description quality, runtime parity), cross-reference maps between skills, per-skill front-matter consistency. Consider a full library-audit pass. Discover the repository’s actual documentation contract first. Apply the following sidecar thresholds only where that convention is adopted or requested; elsewhere inspect the actual local obligations, without treating absent YON sidecars as defects. **Sidecar audit under that adopted convention:** for each significant changed file (>100 LOC, public API, component/hook/route handler/schema) — does a colocated `.yon` exist? Still accurate? Should one be created? - New directories with >3 significant files → flag missing `index.yon` - Cross-file features touching >2 related files → flag missing `*.feature.yon` **README accuracy:** verify prose against current code — described APIs still accurate? New features documented? Removed features still mentioned? Report by severity: - **MISLEADING** — docs say X, code does Y (cite both the doc claim and contradicting code) - **STALE** — docs describe removed features - **MISSING** — new features/files undocumented - **ACCURATE** — no action ## Phase 4 — Knowledge & Skill Assessment **Knowledge Items:** cross-reference changes against existing KI summaries. Report KIs to update (with what changed), KIs to create (with proposed scope), KIs still accurate (no action). **Skills:** Resolve a supplied or current host/repository skill catalog and record its scope. If unavailable, keep proposals provisional with duplicate coverage incomplete; a missing index is not an empty library. Cross-reference patterns, libraries, and techniques against existing skills: - (A) Skill exists and covers it — no action - (B) Skill exists but is incomplete — specify what's missing or outdated - (C) No skill exists — evaluate reuse potential (2+ uses, non-obvious decisions, multi-file scope). If warranted, propose: skill name, domain family, key sections, complexity estimate Verify no existing skill covers the domain via skill-search first — never propose a duplicate. ## Phase 5 — Difficulty Analysis Reflect on execution difficulty. For each: what was harder than expected, what assumptions proved wrong, what took multiple attempts, what external blockers were hit. For each: root cause, resolution, prevention. ## Phase 6 — Tech Debt Inventory Inventory tech debt introduced or discovered: shortcuts taken, TODO/FIXME/HACK comments added, deferred limitations, test coverage gaps, sidecar coverage gaps. For each: **severity** (LOW/MEDIUM/HIGH), **estimated effort**, **recommended timeline**. ## Phase 7 — Retrospective Report Compile the full report: 1. **Blast Radius Summary** 2. **Patterns Extracted** — with recommended actions 3. **Documentation Audit** — gaps, stale sidecars, README accuracy (MUST-DO vs SHOULD-DO) 4. **Knowledge & Skill Updates** — KIs and skills to update/create 5. **Difficulty Log** 6. **Tech Debt Inventory** 7. **Gate Status** — for committed work: the project gate-suite outcome (`pass` / `fail` / `skipped — why`) and any acceptance criterion left unverified. Name skipped gates and unverified criteria explicitly; a clean-looking retro that omits a coverage hole misrepresents what actually shipped. Present with actionable next steps. ## Rules - MUST check skill-index first when finding reusable patterns — avoid proposing duplicates - MUST include skill name, domain family, and estimated content scope when proposing new skills - MUST propose concrete follow-up when identifying tech debt — not vague observations - MUST apply significance criteria (>100 LOC, public API, component/hook/route handler/schema) when assessing sidecars - MUST cite both the doc claim and the contradicting code when finding MISLEADING docs - MUST NOT fix issues in-line — retro is observation only; fixes are separate tasks - SHOULD propose creating high-reuse skills immediately after retro - SHOULD streamline the report to essentials only when blast radius is small (<5 files) ## Next Steps - `/insight-skill-gap` — create/update skills flagged in retro > **Human output.** This skill's handler-facing output obeys the human-output > contract (`human-output/SKILL.md`). > **Next skills.** On completion, run the Next Skills protocol (`next-skills/SKILL.md`): surface the `next-skills` recommendations from front-matter for the caller to pick. Offer only — never auto-invoke. > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.