agentleFS
tammaitammai/bigin-skills/skills/sprint-distill/SKILL.md

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'.

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
  1. Very specific:

    Not this skill: a single PR, a single change, or a one-off code review — use /code-review or /review.

    line 13
  2. Very specific:

    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 …

    line 21
  3. Very specific:

    Check whether knowledge/ exists in this repo.

    line 25
  4. Distinctive:

    Treat pasted material as additional candidate learnings, classified identically to git-derived ones in Phase 2 — no separate pipeline.

    line 52
  5. Very specific:

    If KB_MODE = full, read knowledge/meta/knowledge-bundle-spec.md before classifying — this is the authoritative spec.

    line 58
  6. Distinctive:

    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.

    line 67
  7. Very specific:

    Never touch source code, openapi.yaml, or migrations.

    line 91
  8. Very specific:

    Follow knowledge/meta/knowledge-bundle-spec.md for frontmatter and structure.

    line 92
  9. Distinctive:

    If the user asks for edits, revise and re-propose before applying — don't reinterpret silently.

    line 136
  10. Distinctive:

    Only after explicit approval, and only the items approved:

    line 142
  11. Very specific:

    Write approved knowledge/ changes.

    line 144
  12. Very specific:

    Write approved repo convention changes (.claude/rules/, CLAUDE.md).

    line 145
  13. Very specific:

    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 …

    line 147

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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:

  1. Check whether knowledge/ exists in this repo.
    • Missing entirely → this repo hasn't opted into the Knowledge Bundle. Ask with one AskUserQuestion call ("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-only or stop for option 2. If skills-only, ask for SPRINT_START directly (a date or git ref) since there's no log.md cursor.

    • Exists → set KB_MODE = full. Read knowledge/log.md.
      • Last dated ## {DATE} entry found → SPRINT_START = that date.
      • log.md exists but has no dated entries yet (fresh bundle) → ask the user for a start date.
  2. Surface version drift. Best-effort print the installed bigin-skills plugin version (.claude-plugin/plugin.json under ${CLAUDE_PLUGIN_ROOT}) and, if present, this repo's .claude/harness-version stamp, 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:

  1. git log merged commits/PRs on the main branch since SPRINT_START — titles + bodies.
  2. git diff --stat SPRINT_START..HEAD -- knowledge/ (if KB_MODE = full) — concept files touched this sprint.
  3. Current .claude/rules/*.md — read so you don't re-propose a convention that's already documented.
  4. Stale-rules scan: for each file in .claude/rules/ and CLAUDE.md, identify the most recent git log entry that touched it. Flag any file with no merged PR touching it in the 2 sprints since SPRINT_START as a deletion candidate. Output as a list: {file} — last touched {date}, {N} sprints ago.
  5. If graphify-out/graph.json exists: 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. If KB_MODE = full, also check each concept file's referenced identifiers (functions/tables/routes it names) against graph.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 — skip knowledge/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.

  1. 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/* or CLAUDE.md, written here in Phase 4.
    • plugin-side — a bigin-skills SKILL.md or 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.
  • 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 by task-workflow and epic-workflow at cleanup, one Record per 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 what tools/knowledge_validate.mjs warns on; reachability seeds from every index, not only the bundle root's).
  • If a graphify-out/graph.json graph 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 in knowledge/). 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.mjs stays unchanged until the false-positive rate is known. Negative test: this skill never writes into or reads graphify-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 into knowledge/.
  • Never touch source code, openapi.yaml, or migrations. sprint-distill only writes to knowledge/ and this repo's .claude/rules/ / CLAUDE.md; plugin-side changes are proposals, never writes.
  • Follow knowledge/meta/knowledge-bundle-spec.md for 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:

  1. Write approved knowledge/ changes.
  2. 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.
  3. Validator, best-effort: if KB_MODE = full and tools/knowledge_validate.mjs exists at the repo root, run it (node tools/knowledge_validate.mjs). Repos scaffolded before v1.19.0 have the legacy tools/knowledge_validate.py instead — run that via uv 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.
  4. 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 runs newest-first. It may cite the records this sprint added ("three tasks and one epic recorded under implementation/", with links) but must never absorb them: log.md is 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 updated

References

  • knowledge/meta/knowledge-bundle-spec.md (consumer repo) — authoritative frontmatter/structure/staleness spec; read, never copied
  • knowledge/log.md (consumer repo) — sprint cursor and log target
  • tools/knowledge_validate.mjs (consumer repo, if Knowledge Bundle opted in; .py in pre-v1.19.0 repos) — best-effort validation in Phase 4

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.