retro-to-framework

Retro-to-Framework

Convert project-level retrospective findings into framework-level improvements.

When to Use

Two entry points, one procedure:

• Downstream of a retro — self-retrospective produces the findings, this skill promotes the generic ones.
• Downstream of an incident — one session where an agent observably did the wrong thing. No retro needed; the evidence is the session itself. Bring what the agent did, what the component told it to do, and the proof it read that component (otherwise the finding is "the agent never saw it", a different fix).

Two boundaries — the finding must be cross-project generic (a project-local fix stays in that project's CLAUDE.md), and trimming or dedup of components that already exist is skill-optimization, not this.

Procedure

1. Classify findings: For each retrospective finding, ask: "Would this same problem occur in a different project using the same role?"

   • YES → framework candidate (rule, skill, or skill update)
   • NO → project-specific (stays in project CLAUDE.md)

2. Map to component type — mechanism first:

   Finding type	Framework component
   Invariant a machine can decide ("never write X to Y")	Hook / gate / CLI check — not prose
   Behavioral constraint ("always do X")	Rule
   Multi-step process ("when X, do Y then Z")	Skill
   Missing check in existing process	Skill update
   Knowledge gap	Reference doc or injection update

   The first row is first on purpose: prose costs tokens every turn and asks the agent to comply, a hook costs nothing and does not ask. Rank the options with the mechanism ladder in trait skill-engineer before picking a row.

   If prose for this finding was already tried and did not hold, the first row is the only honest answer. A component the agent demonstrably read and did not apply will not be fixed by rewording it in the same place — that is the evidence that the mechanism, not the wording, is wrong. Record what was tried and how it was measured, so the next reader does not re-run the experiment.

3. Draft the improvement: Follow skill-template for new skills, rule naming convention for rules.

4. Wire into composition: Determine which trait should include the new component. Update trait config.yaml. Run composer validation for all affected roles.

5. Propagate to projects: Roles are composed fresh at every session launch, so a library edit needs no per-project command — it is live for the next session. A project pinned to a published ai-hats-library needs ai-hats self update to pull the new version; self init does not fetch one. Remove corresponding band-aids from the project's own CLAUDE.md. Verify with ai-hats config status (composition tree) or ai-hats --dry-run (the exact artifacts a launch would deliver).

6. Close the loop: Update the original retrospective with a link to the framework change. File a backlog card if the change is non-trivial.

Completion

• Findings classified as framework vs project-specific
• Framework improvements implemented and validated (composer 0 errors, tests green)
• All projects using affected roles bumped
• Per-project band-aids removed
• Original retrospective updated with provenance

Anti-Patterns

• Leaving band-aids in project CLAUDE.md after framework fixes exist — remove them
• Making everything a framework change — some things are truly project-specific
• Skipping composer validation — always verify after wiring changes