review-drift
Skill4 starsChanged 3 months agoMITView on GitHub
Design-drift review — given what recently landed on main, what does the REST of the codebase now owe us? Finds new duplication, a good local idea that should spread, a rule stated but unapplied, a third workaround for one root cause, and proposes fixes with a blast radius. Runs after merges (nightly, from the bundled runner) or by hand on a window. Report, never fix. Use when asked "what did the last merges imply", "design drift", "what should spread", "review beyond the diff".
1 other project uses a version of this.
Adopted by
Most recently taken up by
- njt2810/claude-code-frameworktheir own version, first seen Sep 10, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- njt2810/claude-code-framework★ 1same name
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 repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- adapter-contract-testingSkill
- azure-devops-prSkill
- bugszero-root-causeSkill
- legacy-3pSkill
- port-refactoringSkill
- quality-gateSkill
- review-ai-writingSkill
- review-allSkill
- review-architectureSkill
- review-complexitySkill
- review-impactSkill
- review-prSkill
- review-securitySkill
- review-slopSkill
- review-testingSkill
- scope-challengeSkill
- teams-local-messagesSkill
- write-testsSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 5 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
Not a diff review. A diff reviewer answers "is this change good?".
- Very specific: line 32
Candidate seeds: Run scripts/design-candidates.sh from the repo root (the nightly runner does it for you).
- Very specific: line 39
CodeScene, optional — but never silently: If the CodeScene MCP server is available (ToolSearch query …
- Very specific: line 47
Don't re-derive what is already known: Read the previous report's not-findings ledger when the runner names one, and the open issues (gh …
- Distinctive: line 94
When a seed names a join or a setting, read the config file — the seed list is code-shaped, and a missing line of YAML is as real a sibling …
- Distinctive: line 99
Only the seed is windowed.
- Very specific: line 137
When two or three seeds are local instances of one general rule, state it in a sentence and say whether it belongs in docs/ or the …
- Very specific: line 143
Write the markdown to the report path, and beside it the same name with .md replaced by .findings.json (drift-2026-09-23.md → …
- Distinctive: line 178
Already #N: when an open issue covers it — then only what you add
- Distinctive: line 191
Concrete or nothing: Every claim has a file:line.
- Very specific: line 212
Add .design/ to the project's .gitignore.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
Design-Drift Review
Not a diff review. A diff reviewer answers "is this change good?"; this one answers:
Given what changed recently, what does the rest of the codebase now owe us?
Recent changes are evidence. Each either (a) introduced something the codebase already had, (b) worked around something for the second or third time, (c) introduced a good idea locally that the rest should adopt, (d) wrote down a rule the rest does not yet follow, or (e) made an already-bad place worse. Find those consequences outside the diff; propose fixes with an honest blast radius.
The review-* skills cannot do this by construction: they are bounded by a diff, and every
finding here lives in a file the diff did not touch. review-protocol.md
§ 4 asks a diff reviewer to check the siblings of what changed; this skill makes that the
whole job, over the codebase, unbounded in time.
0. Preconditions
- Candidate seeds. Run
scripts/design-candidates.shfrom the repo root (the nightly runner does it for you). It writes to.design/— clone pairs (jscpd, andpylintfor Python), complexity and argument-count hits (rufffor Python), files that change together (cochange.json), andtools.txt, which says which of those tools were missing. These are candidate seeds and candidate siblings, tagged by source — not findings. A missing tool is not a failure; it goes into the report's "what you did not check". - CodeScene, optional — but never silently. If the CodeScene MCP server is available
(
ToolSearchqueryselect:mcp__codescene__analyze_change_set,mcp__codescene__code_health_review,mcp__codescene__code_health_score), callanalyze_change_set(base_ref=<base>, git_repository_path=<this checkout>)and keep the result for step 4. If the tools are there and the call errors, the review fails: say so at the top and stop — a configured tool that broke must not produce a report that looks like one run with it. If CodeScene is simply not set up, carry on, and say so in the header. - Don't re-derive what is already known. Read the previous report's not-findings
ledger when the runner names one, and the open issues (
gh issue list --limit 100 --state open;glab issue list, oraz boards queryon other hosts). A seed ruled out with a stated reason is not re-investigated unless this window touched that reason; a finding that is already an issue is reported as "already #N" with only what you add. - Read the rules the project has written down: its conventions doc (
CLAUDE.md,AGENTS.md), and whichever of these it has adopted —code-design-rules.md,hexagonal-architecture-rules.md,design-patterns.md,accidental-complexity-guide.md,testing-rules.md. They define "good" and "cruft" here; do not import your own taste where they speak. Note which of them the window edited — a newly written rule is a seed.
1. The window
Establish it from merges, never from dates: `git log --merges --first-parent --oneline
<base>..origin/main`. `--since` matches commit timestamps, which after rebases and
cherry-picks do not track when work landed. In a history with no merge commits
(squash-only), use the first-parent commits instead. State the exact range and file count
at the top of the report.Reading order — this matters more than anything else in the method:
git log --format='%n===== %h %s%n%b' --stat <base>..origin/main— commit messages first. Where they state their reasons, those reasons are the seeds.git showof each merge.- The full diff only for files a seed points at.
2. Seeds — the claims the diff makes
The best seed is a justification: a sentence in a commit message or a doc that names its own rule ("one list, not a habit"; "only the tokens are secrets"; "a capability is named, never quoted"). Quote it. Then walk the mechanical list, one grep per seed — expect a third to die on the first grep:
- a new type / value object / wrapper; a new helper;
- a new pattern (validating, logging-and-continuing, reading config, resolving a name);
- a workaround — "because X does Y, we Z";
- a rule newly applied in one place;
- a rule newly stated in the docs or the conventions file — the doc is in the diff, the code it describes is not: the rule is the seed, every unfixed place a sibling;
- a fix of a bug class in one place; a deletion;
- a commit whose own diff contradicts the rule it states — stronger than a gap; name it;
- a
.design/candidate whose reason you can name.
When a seed names a join or a setting, read the config file — the seed list is code-shaped, and a missing line of YAML is as real a sibling as a missing function call.
3. Siblings — the whole codebase, unbounded in time
Only the seed is windowed. Grep outside the touched files:
- new type → where is the same primitive still naked?
- new helper → where is the same logic still inlined?
- new pattern → where does the old one survive? are there now two ways?
- workaround → is this the 2nd/3rd for one root cause? then the root cause is the finding
- rule stated/applied → where else does it visibly apply, unapplied?
- fix → does the bug class sit in a sibling adapter/route/script?
- deletion → is the same dead weight elsewhere?
- trace one real input through every join the seed touched. A miss the tests canonicalise away is found by execution, not by grep.
cochange.json lists files that move together without necessarily importing each other —
they are joined by something implicit, usually a string key, and are siblings grep will
not find by name.
Cite line numbers from grep -n on HEAD, never from diff hunks. A seed with no siblings
goes to the ledger with the search you ran. A diff fact whose consequence lives outside
the diff (a feature gated on an event that never fires) is a finding about the consequence.
4. Worsened places
For each file the window touched that got worse, or was already a hotspot, say what the change tells you the file wants to become — one of: a list, a type, a value object for the clump, a port, a split.
- With CodeScene:
analyze_change_set(step 0) names what degraded, with thresholds;code_health_reviewon a file gives smells with line ranges. - Without it: the
.design/complexity hits plus churn —git log --since="6 months ago" --format= --name-only | sort | uniq -c | sort -rn | head— give the hotspots; the tools table says which rule measures which smell.
Either way, remember a health score cannot see a semantic default that lies: a green adapter says nothing about its inbound contract.
5. The rule the codebase is discovering
When two or three seeds are local instances of one general rule, state it in a sentence and
say whether it belongs in docs/ or the conventions file. A doc line is a valid, cheap
finding.
Report — two files
Write the markdown to the report path, and beside it the same name with .md
replaced by .findings.json (drift-2026-09-23.md → drift-2026-09-23.findings.json,
never drift-2026-09-23.md.findings.json) — the machine-readable half that
scripts/drift_publish.py turns into issues, comments and a
digest. Its shape (the script's docstring is the authority):
{"window": {"base": "<sha>", "end": "<sha>", "ref": "origin/main"},
"models": ["opus"],
"findings": [{"title": "…", "blast_radius": "local|module|codebase|doc",
"confidence": "high|medium|low", "sensitive": false,
"already_issue": null, "models": ["opus"],
"body": "<the finding's full markdown: evidence, siblings, radius, proposal, risk, confidence>"}],
"not_findings": 14, "rule_discovered": "<one sentence>" }already_issue is the open issue number when one covers the finding — then body holds
only what you add. sensitive flags a security- or user-facing consequence.
The markdown, in this order:
- Header:
window: <base>..<end>, files, tools available (CodeScene yes/no, andtools.txt), what you did not check, the window you rejected and why. - Findings, ranked by leverage — the fix that removes the most future workarounds
first; a long sibling list is scope, not importance. Each:
- Title — the design consequence, not the symptom
- Evidence — commit + file:line + the quoted claim
- Siblings — every location, file:line; this list is the blast radius and later is the fix's checklist
- Blast radius —
local/module/codebase/doc; flag security- or user-facing consequences even when the radius is small - Proposal — ordered steps; for
codebase, the order (driven by what reads each sibling) and an explicit stop-point - Risk & effort — small/medium/large; the test that proves it, written first
- Confidence — high/medium/low and why you might be wrong
- Already #N when an open issue covers it — then only what you add
- Not-findings ledger — a table
seed | search | verdict. Rows a next run would plausibly re-derive; a seed nobody would think of twice needs no row. - The rule(s) the codebase is discovering.
- Only the tools saw this — what CodeScene or the
.design/candidates surfaced that grep and git did not. If nothing, say so: it is how the tools earn their place.
An empty findings list is a valid outcome for a quiet window. Say which seeds you walked.
Rules of engagement
- Outside the diff, always. A finding wholly inside the touched files is a diff-review finding; leave it out unless it anchors siblings elsewhere.
- Concrete or nothing. Every claim has a file:line. No "consider looking at".
- Deliberate exceptions exist — look before generalising: a comment, a test name, a conventions-file paragraph, a commit message that says "considered and not taken".
- Report, do not fix. Someone else decides whether to spend the radius. Findings become issues when the owner says so.
- Write the report files and stop. No
git add, no commit, no push, no PR, no issue — the runner, or the person who invoked you, publishes. A reviewer that pushes on its own is a reviewer nobody reads first. - Say what you did not check, at the top.
Running it
By hand, on the last few merges:
skills/review-drift/scripts/design-candidates.sh
claude -p "/review-drift report=.design/drift-report.md"
python3 skills/review-drift/scripts/drift_publish.py \
--findings .design/drift-report.findings.json --report .design/drift-report.md --dry-runAdd .design/ to the project's .gitignore. Reports are about one window and go stale as
soon as main moves, like the review reports in review-protocol.md § 6.
Nightly, scripts/review-drift-nightly.sh does the
whole loop: skip if no merge landed since the newest drift/* tag, review in a throwaway
worktree on one or more models, merge their reports, then publish — findings become issues
(or comments on the issue that already covers them), a digest goes to a tracking issue, and
the reviewed commit is tagged drift/<date> as the next run's base. Schedule it with cron,
launchd or a CI schedule; its header lists the knobs. Publishing is GitHub (gh); on
another host, replace drift_publish.py — the findings JSON is the contract.
Running two models and merging finds more than either alone: they seed differently. The cost is two reviews; start with one.
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.

