Learner-retro skill

skillsactive owner: philip · updated 2026-11-14

relates: build-process · harness-chain-contract · kb-retrieval-token-budget · onboarding

Learner-retro skill

Extracts learnings from finished work — rules, acceptance criteria, DoD gaps, principles, patterns — and writes them back into the KB as progressive, non-bloating entries. Manual mode after a PR/incident; automatic mode on a daily schedule across repos.

Trigger

• "what did we learn", "run the retro", after a PR merges / project closes / incident resolves — and daily via Devin Automation (automatic mode).

Contract

• Location: skills/learner-retro/SKILL.md in this repo.
• Version: 0.2.0.
• Install: same as knowledge-base — copy skills/learner-retro/ into .agents/skills/ or unzip kb-skills.zip.
• Inputs: merged PR diffs, session transcripts (devin_session_search/interact/insights), CI/DoD-gate results, review-round counts, delivery-chain stage outcomes.
• Outputs: at most one KB PR per run (manual or daily), PR body listing entries/levels/sources/metrics; "no learnings found" is a valid outcome.

How it works

1. Scope: last 24h (auto) or the named PR/project/incident (manual).
2. Extract across dimensions: Rule, Acceptance criteria, DoD gap, Principle, Pattern, Pipeline metric, Stage gate, Specific fix.
3. Categorize to KB types; assign level L1 (principle/rule) → L2 (pattern/framework) → L3 (specific, only when referenced).
4. Apply progressive discipline (below), dedupe vs machine/index.dsl + recent retro PRs, amend-first.
5. Write via the knowledge-base authoring workflow; compile in the same commit; open the PR.

Rules (progressive discipline)

1. Evidence thresholds — L1 rule only when a pattern repeats (≥2 independent occurrences, or one material incident); single occurrence = PR-body citation only.
2. Amend-first, dedupe always — search index + recent retro PRs; bump updated instead of sibling entries.
3. Hard caps — one PR per run, ≤3 entry changes; overflow deferred as "needs more evidence".
4. Highest-level-only by default — L1/L2; L3 specifics only when referenced by L1/L2; no orphan detail entries.
5. Decay, not accumulation — entries with no source in 90 days flagged in the PR body for human review; never silent deletion.
6. No wholesale rewrites — touch only what evidence supports.
7. Stage-gate inputs — design/build/unit/mock/Playwright/DoD/CI outcomes are first-class retro inputs; stage failures map to framework gates or infrastructure rules.

Anti-patterns

• One-off incidents becoming permanent rules (threshold violation).
• Duplicate entries per run (dedupe skipped).
• Detail entries nothing references (L3 orphans).
• Silent deletion of stale entries (decay means flag, not remove).
• Retro PRs that rewrite whole sections (bloat/drift).

Sources

• skills/learner-retro/SKILL.md v0.2.0 (this repo)
• factory/build-process.md, factory/ai-harness/issues/definition-of-done.md
• decisions/kb-retrieval-token-budget.md