sprint-distill
Skill1 starsChanged 40 days agoMITView on GitHub
End-of-sprint distillation: merged PRs + touched knowledge/ concepts → proposal-first knowledge/ and bigin-skills updates. Compresses, never appends. Triggers: 'sprint distill', 'end of sprint', 'end-of-sprint review'.
In this repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- harness-auditSkill
- skill-benchSkill
- ask-biginSkill
- bigin-harness-setupSkill
- contract-syncSkill
- debug-workflowSkill
- discovery-workflowSkill
- epic-workflowSkill
- flutter-figma-handoffSkill
- go-scaffoldSkill
- knowledge-distillSkill
- model-routerSkill
- napkinSkill
- next-scaffoldSkill
- nodejs-scaffoldSkill
- nuxt-marketing-scaffoldSkill
- nuxt-scaffoldSkill
- nuxt-ui-figma-handoffSkill
- project-scaffoldSkill
- session-handoffSkill
- task-workflowSkill
- write-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 4 are distinctive, and 9 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
9
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Not this skill: a single PR, a single change, or a one-off code review — use /code-review or /review.
- Very specific: line 21
Anti-trigger check first: If the request is actually about one PR, one commit, or one change — not a sprint-scale range — stop and point to …
- Very specific: line 25
Check whether knowledge/ exists in this repo.
- Distinctive: line 52
Treat pasted material as additional candidate learnings, classified identically to git-derived ones in Phase 2 — no separate pipeline.
- Very specific: line 58
If KB_MODE = full, read knowledge/meta/knowledge-bundle-spec.md before classifying — this is the authoritative spec.
- Distinctive: line 67
Never both: If a candidate seems to span both, pick the side it primarily belongs to and link to the other rather than writing it twice.
- Very specific: line 91
Never touch source code, openapi.yaml, or migrations.
- Very specific: line 92
Follow knowledge/meta/knowledge-bundle-spec.md for frontmatter and structure.
- Distinctive: line 136
If the user asks for edits, revise and re-propose before applying — don't reinterpret silently.
- Distinctive: line 142
Only after explicit approval, and only the items approved:
- Very specific: line 144
Write approved knowledge/ changes.
- Very specific: line 145
Write approved repo convention changes (.claude/rules/, CLAUDE.md).
- Very specific: line 147
Write the knowledge/log.md entry last, only after the above succeed — as a new date heading directly under the file's title, since the log …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
sprint-distill
Turns a sprint's worth of merged work into knowledge/ updates and convention updates (this repo's rules, or upstream proposals for bigin-skills) — proposal-first, nothing writes until you approve it. Classifies every candidate learning as WHAT/WHY (→ knowledge/), HOW-we-work (→ conventions), or neither (dropped, but reported). Never both.
Not this skill: a single PR, a single change, or a one-off code review — use /code-review or /review. This one only operates on a sprint-scale date range.
Distillation compresses, never just appends. Net line delta for CLAUDE.md and .claude/rules/ should be ≤0 across a sprint unless there is explicit budget headroom. Every addition must name what it replaces or compresses.
Phase 0: Scope Confirmation
Anti-trigger check first. If the request is actually about one PR, one commit, or one change — not a sprint-scale range — stop and point to /code-review or /review instead. Do not proceed.
Determine SPRINT_START:
- Check whether
knowledge/exists in this repo.Missing entirely → this repo hasn't opted into the Knowledge Bundle. Ask with one
AskUserQuestioncall ("No knowledge/ bundle found in this repo — how should this run go?"), two options:- skills-only — distill this sprint's HOW-we-work learnings only; skip knowledge/ classification. A start date is asked next.
- bootstrap — set up the Knowledge Bundle first (via bigin-harness-setup), then re-run sprint-distill.
Store
KB_MODE = skills-onlyor stop for option 2. Ifskills-only, ask forSPRINT_STARTdirectly (a date or git ref) since there's nolog.mdcursor.- Exists → set
KB_MODE = full. Readknowledge/log.md.- Last dated
## {DATE}entry found →SPRINT_START= that date. log.mdexists but has no dated entries yet (fresh bundle) → ask the user for a start date.
- Last dated
- Surface version drift. Best-effort print the installed bigin-skills plugin version (
.claude-plugin/plugin.jsonunder${CLAUDE_PLUGIN_ROOT}) and, if present, this repo's.claude/harness-versionstamp, so any lag behind the upstream templates is visible up front. Don't fail the run if this can't be resolved.
Phase 1: Gather Inputs
Steps 1-4 run in a subagent — non-interactive and can produce large git log/diff output that shouldn't sit in the main conversation. Use the Agent tool (general-purpose, it needs Bash for git commands) with a prompt covering:
git logmerged commits/PRs on the main branch sinceSPRINT_START— titles + bodies.git diff --stat SPRINT_START..HEAD -- knowledge/(ifKB_MODE = full) — concept files touched this sprint.- Current
.claude/rules/*.md— read so you don't re-propose a convention that's already documented. - Stale-rules scan: for each file in
.claude/rules/andCLAUDE.md, identify the most recentgit logentry that touched it. Flag any file with no merged PR touching it in the 2 sprints sinceSPRINT_STARTas a deletion candidate. Output as a list:{file} — last touched {date}, {N} sprints ago. - If
graphify-out/graph.jsonexists: check whether any commit since the graph's last build touched an indexed path — if so, flag the graph as stale so Phase 2's checks run against a fresh rebuild. IfKB_MODE = full, also check each concept file's referenced identifiers (functions/tables/routes it names) againstgraph.json; any that no longer resolve join Phase 2's stale-concept output with reason "symbol no longer in graph" (code-state expiry, not calendar). Concept files only — skipknowledge/implementation/entirely, for the reason Phase 2 states.
Have the subagent return: the commit titles/bodies, the knowledge/ diff stat, the stale-rules list, and (if a graph exists) the staleness flag + symbol-miss list — not raw git log/git diff output. This is a plain subagent delegation (Agent tool), not the skill-level context: fork frontmatter — only steps 1-5 need isolating, and context: fork would run the entire skill (including step 6's interactive question) as a subagent, where AskUserQuestion isn't available.
- After the subagent returns, ask the user directly in the main conversation, as a plain question rather than
AskUserQuestion(the answer is pasted text, not a choice): "Any out-of-repo material for this sprint? (meeting notes, transcripts, client docs — paste directly, or say none)" Treat pasted material as additional candidate learnings, classified identically to git-derived ones in Phase 2 — no separate pipeline.
Phase 2: Classify
If KB_MODE = full, read knowledge/meta/knowledge-bundle-spec.md before classifying — this is the authoritative spec; don't restate it here, link to it.
For every candidate learning gathered in Phase 1, apply the sorting rule strictly:
- WHAT/WHY the system is (a domain concept, a contract, a system boundary, a constraint that will outlive this sprint) →
knowledge/concept file (new or update to an existing one). - HOW we work (a convention, a gate, a process change) → a convention update, on one of two sides:
- repo-side — this repo's
.claude/rules/*orCLAUDE.md, written here in Phase 4. - plugin-side — a bigin-skills
SKILL.mdor reference file. Never written from here: the installed plugin is a versioned cache (~/.claude/plugins/cache/…) that the next plugin update replaces, so an edit there is silently lost. Phase 4 hands it over as an upstream proposal for the bigin-skills repo instead.
- repo-side — this repo's
- Neither (noise, a one-off, something already covered) → drop, but report it in the proposal so nothing silently vanishes.
- Never both. If a candidate seems to span both, pick the side it primarily belongs to and link to the other rather than writing it twice.
- Never a record.
knowledge/implementation/is written only bytask-workflowandepic-workflowat cleanup, oneRecordper finished task or epic. No candidate learning is ever routed there, and this skill never opens one to mine it: a record's narrative is not a candidate for distillation, it is what distillation already ran against.
Bias toward DROP when uncertain — knowledge/ concept files are terse by design; don't grow the bundle to record something obvious or already covered.
Net-neutral rule: any proposed addition to .claude/rules/ or CLAUDE.md must either:
- (a) name the rule or text it replaces or compresses (e.g. "replaces the 3-line BFF section"), OR
- (b) cite specific budget headroom (e.g. "CLAUDE.md is at 38/60 lines; adding 4 lines is within budget")
Proposals that just append without a corresponding compression are reclassified as neither-WHAT-nor-HOW and dropped.
Stale-concept detection (if KB_MODE = full, first-class output, not an afterthought):
knowledge/implementation/ is exempt from every sweep below, and from the net-neutral rule above. The bundle spec's staleness policy exempts Record files outright, and each sweep fails on one for its own reason: a record cites the code as it stood when it shipped, so a moved citation or a vanished symbol is the history it exists to keep rather than a staleness signal; it hangs off its own nested index.md, so it is reachable without a root-index entry; and it is never edited after it is written, so "compress it" and "merge it into another file" aren't moves that exist here. Never propose deleting, shrinking, rewriting, or re-verifying one — a record edited to stay accurate is no longer a record of anything.
The sweeps, over concept files only:
- Any concept file whose
resource:/citation target appears in this sprint's diff, but the concept file itself wasn't updated — flag as possibly stale. - Any concept file unreachable from any
index.md— flag (mirrors whattools/knowledge_validate.mjswarns on; reachability seeds from every index, not only the bundle root's). - If a
graphify-out/graph.jsongraph exists: Phase 1's symbol-miss list joins here with reason "symbol no longer in graph"; and any concept file whose content overlaps graph-extractable structure (call flow, dependency, schema shape) — flag as a deletion/merge candidate under the net-neutral rule above (this is the B1 sweep: structural facts belong in the graph, not restated inknowledge/). If Phase 1 flagged the graph itself as stale, propose a rebuild before trusting these checks, so knowledge updates and graph regeneration land together. This check is distill-only in v1 —tools/knowledge_validate.mjsstays unchanged until the false-positive rate is known. Negative test: this skill never writes into or readsgraphify-out/as an update source, only compares symbol names already extracted by Phase 1's subagent.
Hard constraints while drafting (non-negotiable, apply regardless of what a candidate learning suggests):
- Concept files ≤ ~60 lines. Terse beats complete. The ceiling is a concept rule and does not reach records, which are verbatim by design and not written here anyway.
- Link, don't copy — point at
openapi.yaml,.claude/rules/, source code; never duplicate their content intoknowledge/. - Never touch source code,
openapi.yaml, or migrations.sprint-distillonly writes toknowledge/and this repo's.claude/rules//CLAUDE.md; plugin-side changes are proposals, never writes. - Follow
knowledge/meta/knowledge-bundle-spec.mdfor frontmatter and structure.
Phase 3: Propose — STOP HERE
Output a single structured proposal and wait for explicit approval before writing anything:
## Knowledge changes
- [new/update] knowledge/<path>.md — <one-line reason>
...
## Repo convention changes (.claude/rules/, CLAUDE.md)
- [new/update] <path> — <one-line reason> [replaces: <what it compresses>]
...
## Upstream bigin-skills proposals (handed over, never written here)
- <path in the bigin-skills repo> — <one-line reason>
...
## Draft log entry (knowledge/log.md, written last on approval, newest-first)
## {DATE}
<summary of what changed in the bundle this sprint>
## Dropped candidates (reported, not written)
- <candidate> — <why it was dropped>
...
## Stale-concept flags
- knowledge/<path>.md — <why it looks stale>
...
## Deletion candidates (rules untouched for 2+ sprints)
- <file> — last touched <date>; recommend: delete / compress to N lines / keep (reason)
...
## Net-neutral check
CLAUDE.md: <current lines> / 60. Rules delta this sprint: +<added> -<removed> = <net> lines.
Then ask with one AskUserQuestion call, three options: approve all, approve some (the user names which), request edits.
If the user asks for edits, revise and re-propose before applying — don't reinterpret silently.
Phase 4: Apply
Only after explicit approval, and only the items approved:
- Write approved
knowledge/changes. - Write approved repo convention changes (
.claude/rules/,CLAUDE.md). For each approved upstream proposal, print a ready-to-apply edit for the bigin-skills repo (path relative to that repo, plus the exact text to add, replace or remove) — never write it into the installed plugin. - Validator, best-effort: if
KB_MODE = fullandtools/knowledge_validate.mjsexists at the repo root, run it (node tools/knowledge_validate.mjs). Repos scaffolded before v1.19.0 have the legacytools/knowledge_validate.pyinstead — run that viauv run tools/knowledge_validate.py. If neither exists or the run errors, don't block — note in the Phase 5 summary that validation didn't run and should be checked manually. - Write the
knowledge/log.mdentry last, only after the above succeed — as a new date heading directly under the file's title, since the log runs newest-first. It may cite the records this sprint added ("three tasks and one epic recorded underimplementation/", with links) but must never absorb them:log.mdis a per-sprint index of what moved, one entry deep, and summarising a record into it recreates in the log the narrative the record was written to hold.
Phase 5: Summary
sprint-distill complete for <SPRINT_START>..HEAD
Written:
knowledge/: <list, or none>
repo conventions: <list, or none>
Proposed upstream (bigin-skills repo, not written): <list, or none>
Dropped: <count> (see proposal for reasons)
Stale-concept flags: <count, or none>
Deletion candidates actioned: <count, or none>
Net delta: CLAUDE.md <N> lines, .claude/rules/ <+X/-Y> lines
Validator: [passed | not run — verify manually | not applicable (skills-only mode)]
Log entry: knowledge/log.md updatedReferences
knowledge/meta/knowledge-bundle-spec.md(consumer repo) — authoritative frontmatter/structure/staleness spec; read, never copiedknowledge/log.md(consumer repo) — sprint cursor and log targettools/knowledge_validate.mjs(consumer repo, if Knowledge Bundle opted in;.pyin pre-v1.19.0 repos) — best-effort validation in Phase 4
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

