Insight retro

/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 @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.

Sidecar audit: 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: load skill-index. 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): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply.