prevent-drift
/prevent-drift
Pilnuje, by ten sam fakt nie istniał w dwóch miejscach naraz: przy regułach w CLAUDE.md, skillach, README, hookach i konfiguracjach.
- Autor
- NormandErwan ↗
- Repozytorium
- claude-casebook ↗
- Licencja
- BSD-3-Clause
- Ostatnia zmiana repozytorium
- 08.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 08.11.2026, bez odwołań do wycofanych modeli i API.
BSD-3-Clause, otwarta.
Co robi i kiedy
Pilnuje, by ten sam fakt nie istniał w dwóch miejscach naraz: przy regułach w CLAUDE.md, skillach, README, hookach i konfiguracjach.
Oryginalny opis (EN)
Use when a fact is about to exist in two places - writing a rule into a CLAUDE.md, a skill, a README, a hook or a config file; adding a note that restates a setting; reviewing a diff that repeats something stated elsewhere; editing a rule that other files also state. Also when auditing a knowledge base, a docs tree or a config set for drift, or when two files already disagree about the same fact.
Jak działa
- Who owns what
- When to check
- How to treat a duplicate
- Finding drift
- Rationalisations that produce drift
Podgląd SKILL.md
---
name: prevent-drift
version: 1.2.1
description: Use when a fact is about to exist in two places - writing a rule into a CLAUDE.md, a skill, a README, a hook or a config file; adding a note that restates a setting; reviewing a diff that repeats something stated elsewhere; editing a rule that other files also state. Also when auditing a knowledge base, a docs tree or a config set for drift, or when two files already disagree about the same fact.
---
# Single source of truth
Every fact has exactly one owner. Everywhere else names the owner instead of restating it.
Duplication is not a style problem. Two copies of a fact are two facts as soon as one is edited,
and nothing reports the split - the reader trusts whichever copy they happened to open.
## Who owns what
| Owner | Holds | Why it wins |
|---|---|---|
| What executes - config files, scripts, hooks, manifests, CI | The values | True by construction: it is what actually runs |
| The skill or procedure doc | How to do the thing | It is what an agent follows at the moment of acting |
| The prose doc, page or ADR | Why the decision was made | Reasons have no other home |
| Always-loaded instructions (CLAUDE.md) | Only what must be known before acting | Everything else costs context on every turn |
A doc that restates a config value is a copy. A doc that names the config file is a reference.
```markdown
Bad: Hidden files: CLAUDE.md, README.md, skills, .claude
Good: Hidden files are listed under `:hidden` in `logseq/config.edn`
```
## When to check
| Moment | Check |
|---|---|
| Before writing any fact into a file | Does it already live somewhere? `git grep` a distinctive phrase of it |
| When editing a rule | Hunt its copies before you finish. An edited rule with an unedited copy IS the drift |
| When **changing** what a rule does or outputs | Hunt the lines elsewhere that describe its behavior or output, not only its verbatim copies: they still read as current, and they are now false |
| When **moving** a fact to a new file | Hunt what read it at the old address. A move breaks references silently: the readers still run, they just read nothing, or the wrong thing |
| Before opening or updating a PR | Run the scan below, scoped to the diff's files |
| When a doc and a config disagree | Treat it as a bug report, not a formatting nit |
## How to treat a duplicate
1. Name the owner using the table above.
2. **Delete the copy. Do not synchronise it.** Replace it with a reference to the owner.
3. If a mechanism genuinely needs the text inline - a hook that must inject it without reading a
skill - then make one file the source and have the mechanism read that file at runtime. One
file, read twice, is not a copy.
4. Where the copies already disagree, the executable owner is right and the prose is wrong, unless
the prose states a decision the executable never implemented - then the executable is the bug.
## Finding drift
Identical copies are easy: `git grep -F "distinctive phrase"`.
Copies that have already drifted are the dangerous ones - they no longer match, so grep misses them.
Scan for near-duplicate lines across tracked text files. Compare only the diff's *added* lines
against the rest of the repo - comparing every line of a changed file (let alone the whole repo)
against every other line is O(n²) and times out past a few hundred tracked files, even scoped to
one file:
```bash
python3 - <<'PY'
import difflib, pathlib, subprocess
diff = subprocess.run(["git","diff","-U0","HEAD"],capture_output=True,text=True).stdout \
or subprocess.run(["git","diff","-U0","--cached"],capture_output=True,text=True).stdout
added, cur = [], None
for line in diff.splitlines():
if line.startswith("+++ b/"):
cur = line[6:]
elif line.startswith("+") and not line.startswith("+++") and len(line[1:].strip()) > 40:
added.append((cur, line[1:].strip()))
out = subprocess.run(["git","ls-files","-z"],capture_output=True,text=True).stdout
files = [f for f in out.split("\0")
if f.endswith((".md",".edn",".json",".yml",".yaml",".sh",".toml")) and f]
lines = [(f,n,s.strip()) for f in files
for n,s in enumerate(pathlib.Path(f).read_text(encoding="utf-8",errors="ignore").splitlines(),1)
if len(s.strip()) > 40]
for cf, a in added:
la = len(a)
for fb, nb, b in lines:
if fb == cf and b == a:
continue
lb = len(b)
if min(la, lb) < 0.6 * max(la, lb):
continue # can't reach ratio > 0.75 at this length gap - skip before the expensive part
if difflib.SequenceMatcher(None, a, b).ratio() > 0.75:
print(f"{cf} (new)\n{fb}:{nb}\n {a[:90]}\n {b[:90]}\n")
PY
```
Nothing staged or modified -> `added` is empty, the scan reports nothing. That is correct for a
pre-commit check (nothing new to compare yet), not a sign the scan is broken.
For a deliberate full-repo audit (not a pre-commit check) - a knowledge base you suspect has
drifted for reasons the diff-scoped scan above can't see - drop the `git diff` step and replace
`added` with every line in `lines`. That is a real O(n²) pass: expect minutes, not seconds, and
run it once, not on every commit.
Split on NUL, not whitespace: tracked paths contain spaces more often than you expect, and
`git ls-files` without `-z` silently shreds them into paths that do not exist.
Exact matches across two files are copies waiting to drift; matches above 75% that are not identical
have drifted already. Both need an owner.
The scan compares lines, so it is a net with holes: it will not pair a value inside a config
structure with the prose that restates it elsewhere, and it will not catch the same fact written in
two different shapes. It finds copies cheaply; it does not prove there are none. The owner table is
what prevents drift - the scan only reports what already slipped through.
## Rationalisations that produce drift
| Thought | Reality |
|---|---|
| "It is only two lines" | Two lines is the usual size of a rule, and rules are what get edited |
| "The wording differs, so it is not duplication" | Differing wording of the same fact is drift that already started |
| "I will keep them in sync" | Nothing enforces that. The next editor is not you, and has not read this |
| "The reader needs it here too" | The reader needs a pointer here. Pointers do not drift |
| "One is for humans, one is for agents" | Two audiences, one fact, still one owner - the other side gets a reference |
Wersje
W bazie nie ma innych skilli o nazwie prevent-drift.
Migawka bazy z 13.11.2026 · wersja paczki f4892108115a (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 91duplicate-declaration
Pilnuje, by ten sam fakt zapisany w dwóch miejscach pozostawał zgodny. - 100review-docs
Sprawdza README i pliki instrukcji dla agentów, na przykład CLAUDE.md, pod kątem aktualności względem kodu i kosztu kontekstu. - 100docs
Tworzy, audytuje i utrzymuje dokumentację projektu (CLAUDE.md, .claude/rules, AGENTS.md, README.md i drzewa docs/ według Diátaxis) w trybach init, update, readme i audit. - 91mirror-copy
Pilnuje, by jeden plik zapisany w dwóch miejscach nie rozjechał się między nimi. - 95shipping-across-surfaces
Wprowadza zmianę we wszystkich miejscach, gdzie ten sam fakt jest zapisany: strony, dokumentację, changelog i sitemapę. - 90doc-standards
Pilnuje standardów pisania dokumentacji w repozytorium: gdzie zapisać fakt, jak dopisywać specyfikacje i co przyciąć.