Claude Skill

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

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download allemaar-open-skills-skills_insight-retro-acf5f79.zip · 7 KB

Install

skills CLI npx skills add https://github.com/allemaar/open-skills/tree/main/skills/insight-retro
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
Git 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 @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.

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.

No comments yet.

Reviews (0)

No reviews yet.