handoff
Skill21 starsChanged 11 days agoMITView on GitHub
Hand this repo's work over - which files a handoff touches (CLAUDE.md, `.claude/rules/`, FOLLOWUPS.md, DONE.md, docs/smoke-test.md), how closing an item is a move rather than an edit, and why every number and mechanism must be re-derived rather than recalled. Use when updating the handoff docs, closing a FOLLOWUPS item, or writing prose that states a rule about how this code behaves.
191 other projects use a version of this.
Adopted by
Most recently taken up by
- bamlab/flashlighttheir own version, first seen Nov 16, 2026
- element-hq/element-calltheir own version, first seen Nov 16, 2026
- lhotwll217/owner-operatortheir own version, first seen Nov 16, 2026
- tanishq286/tq-forgetheir own version, first seen Nov 15, 2026
- niki914/zafirotheir own version, first seen Nov 15, 2026
- davidondrej/skillstheir own version, first seen Nov 15, 2026
Used with
Projects with it also use decision-mapping, setup-ts-deep-modules and 10 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
FabienDehopreSkilldecision-mapping
Turn a loose idea into a sequenced map of investigation tickets, then drive them to resolution one at a time.
Also in 8 projects that use this
liufeng1976Skillsetup-ts-deep-modules
Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
Also in 47 projects that use this
RoentekSkillloop-me
Grill me about specs for the workflows I want to build, within this workspace.
Also in 59 projects that use this
AWSSkillto-questionnaire
Turn a decision you can't fully answer into a questionnaire for someone else to fill in.
Also in 105 projects that use this
GoogleSkillask-matt
Ask which skill or flow fits your situation. A router over the skills in this repo.
Also in 101 projects that use this
LesaniSkillwriting-beats
Shape an article as a journey of beats, choose-your-own-adventure style. The user picks a starting beat from the raw material, you write only that beat, then offer options for where to pivot next, beat by beat, until the article reaches a natural end. Use when the user has raw material and wants to assemble it as a narrative rather than an argument.
Also in 62 projects that use this
Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
- mattpocock/skills★ 325ksame name
- The-Vibe-Company/quivr★ 40ksame name
- QuivrHQ/quivr★ 40ksame name
- GreyDGL/PentestGPT★ 16ksame name
- ykdojo/claude-code-tips★ 10ksame name
- ArcReel/ArcReel★ 6.6ksame name
- vinvcn/mattpocock-skills-zh-CN★ 5.8ksame name
- withcoral/coral★ 5ksame name
- epicenter-md/epicenter★ 4.8ksame name
- EpicenterHQ/epicenter★ 4.8ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- eval-benchSkill
- live-hypervisorSkill
- live-kernelSkill
- merge-dependabot-prsSkill
- release-rust-crates-ioSkill
- review-roundSkill
- tiersSkill
- msrc-patch-diffSkill
- windbg-debuggingSkill
The file
Files
Handing the work over
The files a handoff touches
"Update the handoff docs" means a specific set, discoverable only from what the handoff PRs touched
(#155, #159, #170). They are titled "Hand the <X> work over: …" — the stem is the convention,
and the clause after the colon says what kind of handoff it is: "the traps, not just the result"
on #159 and #170, "what is covered, what is not" on #155.
CLAUDE.md— the two roles, the release-exe lock, and the routing table naming every rule and skill below. It is loaded into every session, so what goes here is what every session needs; anything longer belongs in one of the next two..claude/rules/*.md— what bites while editing a subsystem, scoped by apaths:glob so it loads only when Claude reads a file it covers. A new subsystem note goes in the rule whose subject it belongs to; the scope is not part of that choice, for the reason below.paths:is one shared scope for the nine code rules, and that is a decision rather than laziness. Each was first scoped to the files named in its own title, which is the natural thing to do and was wrong fifteen times: nine filed as review findings across rounds one to nine of #285, six more found by enumerating rather than waiting for the next round — and the ninth landed after the shared scope, againstcargo-and-dependencies, whose first paragraph bound a Rust-only change from a manifest-scoped file.worker-architecturebindsworker.rsandproto.rs,listener-clientsbindsserver.rsandengine.rs,tool-surfacebindsworker.rs,execution-waitsbindsserver.rs,batch.rsandstructured.rs,transcriptsbindsmain.rs,server.rsandengine.rs, and so on. Two heuristics were tried and both failed: "start from the four hub files" cannot reachbatch.rs, which is bound by what it routes; and a lint over symbols a rule names returns mostly collisions, because tool names and English words are the same strings as this crate's items (cargo-and-dependencies"names"engine.rsthrough registry,transcriptsnamesserver.rsthrough theregisterstool, andArchandExpiredare each defined in two modules meaning different things).What settled it was measuring instead of arguing. At the restructure, against the 72,396 bytes of all eight rules as they then were,
engine.rsalready loaded 89%,worker.rsandserver.rs69%, andproto.rs62% — because every tool call crosses those four. Eleven hand-maintained lists bought 11–38% on the files anyone edits and cost a review round per mistake, so they were replaced bysrc/**/*.rsplustests/**/*.rsandbuild.rs—build.rs's ownINPUTSless the manifests — identical in all of them. A new code rule copies that scope; it does not invent one. The laziness that still pays is on the other axis and is untouched: a session touching no Rust never loads the code rules at all — it loadsCLAUDE.mdplus whichever narrow rules its files match. Measured after round twelve: 77,169 B against 6,496 B.State that as a bound, never as a composition. Two goes at the exact wording were both review findings: "and nothing else" (the narrow rule loads too), then "the one narrow rule its subject matches" — which was written one commit after the paragraph below documenting that
examples/README.mdmatches two rules andbuild.rsnine. The globs intersect by design, so any sentence counting how many fire has to be re-derived against them, and the saving does not need the count: what it rests on is the code rules not firing.A byte figure in prose is a measurement, not an invariant — so date it, and paste it rather than derive it. The bound was written as 11,315 B and was already 30 bytes stale, because the commit that added a pointer sentence to
cargo-and-dependencies.mdmoved it in the same series; a reviewer recomputed and was right. Then, updating it after round twelve's split, the figures went in as 77,134 and 6,422 — arrived at by subtracting the moved section by hand, one line after a command had printed 77,169 and 6,496. Both halves of this rule matter and the second is the one that keeps being broken: run the measurement, then copy what it said. Worse, this file carried 72,396 and 72,211 for the same quantity in two paragraphs, both phrased as current fact, because they were snapshots taken four commits apart. Every such figure here now says when it was taken, which is the only form that stays true — the percentages above are from the restructure and must not be "corrected" against today's sizes, or they stop matching the total they were computed from.The three rules that are not about this server's code keep narrow scopes, and should: their subjects are disjoint from the code's, so scoping them is one obvious judgement each rather than a per-file list, and no round has filed a scope finding against any of the three.
Their globs do overlap, and that is fine — the sentence here used to say they "overlap nothing", which is simply false and was a review finding in its own right.
cargo-and-dependenciesnamesbuild.rs, which is also in the code scope;powershell-scriptsnamesexamples/**, which catchesexamples/README.mdalongsidemarkdown-and-docs's**/*.md. Both are wanted:build.rsis a build input and the file the PE version resource lives in, and a README beside the scripts it documents is both markdown and script context. Overlap costs a few kilobytes on a file that genuinely has two subjects. The failure to care about is a rule that does not load where it is needed, which is the opposite direction and the one all fifteen mistakes were in. Do not narrow a scope to make a Venn diagram tidy.One thing to know while reading them:
powershell-scriptsnamestools/**, so it also loads on the eval scripts, which are Python. That is deliberate — its stderr-draining rule is about driving this server from any script — but the rule's name undersells it..claude/skills/*/SKILL.md— the procedures:tiers,review-round,live-kernel,eval-bench, and this file. A skill's body costs nothing until it is invoked, so length is cheap here and expensive inCLAUDE.md. Itsdescriptionis the whole of how it gets found — that line is in context every session, and the body is not.FOLLOWUPS.md— numbered items still open, each saying what would close it, why it was deferred, and where it picks up. Its header enumerates clusters and needs a line whenever an item is added.DONE.md— the same entries once they land, kept in full and under the number they were filed with. Closing an item is therefore a move: out ofFOLLOWUPS.md, out of its cluster list, and intoDONE.mdwith an index line, which is the only list of what has closed. An item that is half landed or declined stays put — the first because the entry narrows to what is left, the second because what it proposed did not land and the reopening condition is the content.A citation is not retargeted, and that is a decision rather than an oversight. Some twenty files say "
FOLLOWUPS.mditem N" — doc comments in eleven modules and intests/,CHANGELOG.md,DECISIONS.md, everydocs/*.md, the rules and skills under.claude/,build.rs,ci.ymland the eval tooling — so a citation whose file half followed the entry would make every close a sweep of source comments, unchecked, in a form that would have to be swept again next time. The number is the name;FOLLOWUPS.md's header answers which file, above every entry, for whoever followed one there. What keeps that from rotting is a test rather than the rule:engine::every_followups_citation_names_an_item_that_existsreads every text file in the repository and fails if a cited number is in neither file, if one number is in both, or ifDONE.md's index has fallen out of step with its own entries. It was raised as a review finding on the split (#270) with the sweep as its proposed fix; the fact was right and the remedy was the expensive half of it.docs/smoke-test.md— what each tier claims, per test, with budgets.
Plus CHANGELOG.md and whichever docs/*.md the behaviour moved in.
Six places to check, not six files to edit. A handoff touches the ones its change actually
moved: #170 updated two of them and README.md, and was right to — the test its
docs/smoke-test.md entry would have described did not exist yet, landing in #176 later the same
day. Going looking for another edit with no subject is how a section gets written about nothing.
The failure this list prevents is the opposite one, and it is the common one: not knowing the
next file is there.
The closing sentence of an explanation is where the false claim goes. Rounds six, seven and
eight of #285 were three consecutive findings of exactly this, none of them about the thing being
explained and all of them about the tidy line at the end of it: "a docs session loads CLAUDE.md
and nothing else" (it loads the matching narrow rule too), the three narrow rules "overlap nothing"
(build.rs is in nine scopes, examples/README.md in two), and a commit message claiming a change
"closes the class" (the next round reopened it). Each was written after the accurate paragraph
above it, as a summary — and summarising is where the qualifier gets dropped, because a crisp line
reads better than a true one. The tell is a sentence with nothing, every, always,
one, closes or never in it that you wrote to finish a paragraph rather than to state a
fact. Re-read those against the thing itself, not against the paragraph they conclude.
And round ten was the same mistake inside the commit that named it. The fix for "and nothing
else" replaced it with "the one narrow rule its subject matches", which is false for the same
examples/README.md the paragraph above had documented one commit earlier — so the correction, the
rule it contradicted, and the paragraph warning about exactly this shipped together. Naming a habit
does not interrupt it. What worked was changing the shape of the claim: state a bound, which
survives a glob change, rather than a composition, which has to be re-derived against every scope
and was wrong both times it was written.
This prose is reviewed as hard as code, and deserves to be. A docs-only PR (#170) drew six findings from the Codex bot, every one a real inaccuracy about the lease — and two of them were errors introduced while fixing earlier ones. The worst class is a rule stated without its qualifier: "a request renews the lease" where the truth is "a request the lease admits", written on an item that proposed a deletion. Taken at face value it licenses renewal-on-arrival, which lets a stream of wrong session ids hold an abandoned live kernel target open for ever — the failure the sweep exists to prevent.
The drift is continuous, not per-PR. The 2026-08-23 pass found problems in all three files
accumulated across four merges, none introduced by the change that prompted it: a test count that
said 69 and is 75, an item missing from the FOLLOWUPS.md header, and a section describing six
listener tests where there are ten. Assume anything countable has moved, and that the sentence
around it has not.
So re-derive every number — and distrust the derivation, not just the number. Four ways this has gone wrong here, each of which produced a confident wrong edit or came one step from it:
- A grep is not an enumeration. Counting
Listener::startcall sites gives nine protocol-tier listener tests; there are ten, becausethe_listener_will_not_start_without_a_tokenspawns the exe itself — a listener that will not start cannot be started by the helper. The wrong nine reached a PR description before the source was walked properly. cat A 2>/dev/null || cat Bprints contents without saying whose. That is how the markdownlint config came to be written down as.markdownlint-cli2.jsonc, which does not exist here; it is.markdownlint.jsonc.- The
FOLLOWUPS.mdheader drifts silently, because nothing reads it. It has claimed "twelve" while enumerating fourteen, and has twice stopped short of items already written. Match itsitems N–Mspans against the## N.headings mechanically rather than counting by eye. - A number that looks stale may be right. "The four assertions that read a target" survives
five tests gating on those conditions, because the four are the ones opening
NATIVE_SAMPLEand the fifth is deliberately separate — countingskipcall sites would have "fixed" it wrongly.
And re-read every mechanism, for the same reason. A number gets re-derived; a claim about how
something works gets the file opened. What goes wrong is stating it from the shape of the code
around it, from a field's name, from one backend in front of you, or from what a neighbouring rule
does — and it is cheap to avoid, because every instance below was one grep or one sed away.
Six findings across five review rounds on
#221 were all this, and so was a wrong
verification on #220:
- From the neighbours. A proposed test's module counts and
pc"need a symbol gate", because the tier around them gates.docs/smoke-test.mdalready draws that line — target memory against the dump's structure — and carries the measurement that settles where a stack falls; two rounds to land, and what the entry carries now is a pointer to that file rather than a second copy of it. - From a name. A drift test was to pin
answer_key. Nothing readsanswer_key—grep -rnfinds no consumer intools/,tests/orsrc/— becausematches()grades from each task'sexpect. The test would have stayed green while the facts models are scored against rotted. - From an identifier. A compare mode was to pair two runs on
(backend, model, ctx, surface, task)and note any suite difference above the table, whileusable()in that same file refuses a record whose prompt differs. The proposal was laxer than the code beside it. - From one backend. "Record the model digest on every record", generalised from the ollama
driver, which is the only one with an
/api/psto ask;claude_code_drive.pyrecords a mutable alias and has no equivalent to offer. - From what a field is for.
expectwas taken as ground truth for a verifier, but it holds only the expected answers — a task's dump path lives in its prosepromptanduseful_toolscarries no arguments, so nothing structured says what to call. - From the half that agreed. "Grades unchanged" after rewording a task, checked by running
--gradeand reading the numerators, which did match. The denominators had gone 20 to 15 and every row saidUNCOUNTED x5.
The tell is that the sentence is about behaviour and the file is not open. It is the same error as the eval task that started that work — answering the question the way it reads rather than the way it is keyed — which is worth knowing because at the time it does not feel like guessing.
And it survives being noticed, which is the last thing this paragraph is for. Its first draft
opened "Five review rounds on #221 were all this". Five was neither: it was the finding count at
that moment, written as a round count, and there were four rounds — by the time either was
counted from the API rather than from my own commit subjects (which had numbered my own edits as
rounds) there were five rounds and six findings, the sixth having landed while the paragraph
was being written. The same draft also credited docs/smoke-test.md with the three-way symbol
split; that file draws a two-way line — target memory against the dump's structure — and the third
way was mine.
And none of this is linted. CI's markdownlint globs are README.md, CHANGELOG.md,
docs/**/*.md and skills/**/*.md (.github/workflows/ci.yml), so CLAUDE.md, FOLLOWUPS.md,
DONE.md and everything under .claude/ are absent from all four — and note skills/** is
the shipped plugin skill, not .claude/skills/, which is this repo's own working guidance and is
unlinted like the rest. Point the linter at them anyway and it reports pre-existing errors —
fourteen in CLAUDE.md alone, measured 2026-09-27, where this line said ten —
fence and list spacing, nothing that renders wrongly — so neither a clean run nor a dirty one tells
you anything about an edit you just made here.
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.

