agentleFS
emp3thyemp3thy/claude-skills/skills/document-drift/SKILL.md

document-drift

Skill0 starsChanged 35 days agoMITView on GitHub

Keep a repository's markdown docs matching what its code does, in both directions. Rewrites or removes statements the code contradicts or names the code no longer has, adds user-facing commands, flags, environment variables, MCP tools, routes and scripts no doc mentions, and marks blocks that describe the code but name nothing in it. Agents that read the repository and write only their own output file review the docs against the code, verifier agents check every edit, and the result is commits on a new branch for review. Use when asked to check docs for drift, fix stale READMEs, or update docs after a refactor or a release.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 4 are distinctive, and 5 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.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Not for: pushing, opening pull requests or writing a PR body.

    line 22
  2. Distinctive:

    Run the stages in order, dispatch exactly the plan entries, and relay the final summary.

    line 32
  3. Distinctive:

    Never edit a doc, never write an agent's output file yourself, never rerun a stage except as the exit 3 rule below says, never push and …

    line 33
  4. Very specific:

    Run every command from this skill's directory (skills/document-drift/), with <repo> as an absolute path.

    line 47
  5. Very specific:

    Read plan-docs.json, the file at the path printed on the stdout line.

    line 63
  6. Very specific:

    Only when start printed readme: yes: compose the README.

    line 78
  7. Distinctive:

    Verify the agents' outputs and check their edits:

    line 97
  8. Very specific:

    Read plan-verify.json, the file at the path printed on the stdout line, and dispatch the verifier entries the same way as in step 2, all in …

    line 115
  9. Very specific:

    When the repository root has no README.md, the run also writes one from the code, in the additions commit, with the bullet - README.md:1 …

    line 193

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

document-drift

Keeps a repository's markdown docs matching what its code does, in both directions. Docs to code: a statement a doc makes about this repository's code that the code contradicts, or that names something the code no longer has, is rewritten or removed. Code to docs: a command, flag, environment variable, MCP tool, route or script the code offers its users that no doc mentions, or that is missing from a doc's list of such things, is added to the docs. The docs are the record of what to check: the first run reviews every doc against the code it points at; later runs review only the statements whose code changed since the last run, and document only user-facing names added since then. Scripts decide what to review, check every proposed edit, apply and commit; agents you dispatch from plan files do the reading. The result is commits on a new branch; the user's own process pushes it, reads the change and opens the pull request.

Not for: pushing, opening pull requests or writing a PR body; creating doc files (but for the README of a repository that has none); editing excluded files (changelogs, licences, ADRs and decision records, RFCs, plans and specs, research and archive folders, vendored and generated docs, templates); changing code (a guarantee the code does not keep is listed for the user, not edited); running the project's code, builds, installs, examples or --help; external URL checking, .rst and .adoc, translated READMEs, prose style or markdown lint.

No improvisation

Run the stages in order, dispatch exactly the plan entries, and relay the final summary. Never edit a doc, never write an agent's output file yourself, never rerun a stage except as the exit 3 rule below says, never push and never open a pull request, and never run the project's code. Do not retry with other flags unless the user asks. On exit 5, stop and report the message verbatim; when the message names apply, commit or summary, tell the user to check git status and git branch, since docs may already be edited and the branch may exist. A crash outside a step at finish names no step, but its message already carries that git status and git branch pointer; relay it verbatim.

Invocation

/document-drift <repo> [--base <ref>] [--full] [--branch <name>] [--check]

Run every command from this skill's directory (skills/document-drift/), with <repo> as an absolute path. Give start the flags the user gave; give compose, verify and finish none of them except --workdir (they read the others from the run's record, and a different value is refused).

  1. Start the run:

    python scripts/dd_run.py <repo> --stage start [--base <ref>] [--full] [--branch <name>] [--check]

    It first prints readme: yes or readme: no, then plan-docs.json <path> with <n> entries (or, for a repository with no doc in scope and readme: no, the message that no-docs mode arrives in phase B). readme: yes means the repository has no README.md at its root and this run writes one.

  2. Read plan-docs.json, the file at the path printed on the stdout line. For each entry dispatch one general-purpose Agent with the entry's model; it must have Read, Grep, Glob and Write, so it can write its one output file, and it is read-only toward the repository. Its prompt is exactly:

    Read the file <prompt> in full and follow it. Write only <output>.

    with the entry's prompt and output paths filled in. Dispatch all entries in one message so they run in parallel. Never paste the prompt file's content, and never write an output file yourself: each agent writes its own and replies with a receipt. A review agent reads the code ranges its prompt lists and reports the files it opened beyond them. When start printed readme: yes, the entries include the sheet agents, one per area of the code. When the file holds [] there is nothing to dispatch: go to step 3 after readme: yes, otherwise to step 6.

  3. Only when start printed readme: yes: compose the README. Skip this step after readme: no.

    python scripts/dd_run.py <repo> --stage compose

    On exit 3, the same rule as step 4: read retry.json, dispatch those entries once, then rerun with --retried:

    python scripts/dd_run.py <repo> --stage compose --retried

    Otherwise it prints plan-readme.json <path> with 1 entries: read plan-readme.json at that path, dispatch that one entry exactly as in step 2 (one writer agent), then go on to step 4. Or it prints readme: no sheet; nothing to compose: no sheet was usable, there is nothing to dispatch, go on to step 4.

  4. Verify the agents' outputs and check their edits:

    python scripts/dd_run.py <repo> --stage verify

    On exit 3 it prints retry.json <path> with <n> entries: read retry.json at that path, dispatch those entries once, exactly as in step 2, then rerun the same command with --retried. After readme: yes, the entries also include the writer if its output was missing or invalid. The entries are the agents whose output was missing or invalid, plus new review entries (fresh unit ids) for the ranges a review agent reported it did not get to:

    python scripts/dd_run.py <repo> --stage verify --retried

    Otherwise it prints plan-verify.json <path> with <n> entries.

  5. Read plan-verify.json, the file at the path printed on the stdout line, and dispatch the verifier entries the same way as in step 2, all in one message. When it holds [], go to step 6.
  6. Finish the run:

    python scripts/dd_run.py <repo> --stage finish

    On exit 3, the same rule as step 4: read retry.json, dispatch those entries once, then rerun with --retried:

    python scripts/dd_run.py <repo> --stage finish --retried

    Otherwise it prints the summary.

FlagEffect
--base <ref>Compare against <ref> instead of the last drift run. An unknown ref is refused.
--fullA first run (every doc reviewed in full) regardless of any previous run.
--branch <name>The branch to create. Default docs/drift-<YYYY-MM-DD>, or the branch pattern in .document-drift.yaml.
--checkRun through verification and stop: no doc edit, no branch, no commit, no last-run record. The summary lists every edit that would apply as a commit bullet, the README that would be written among them; finish exits 1 when an edit would apply (an accepted edit, a kept notice edit, which needs no verdict, or a README that would be written because a statement of it was accepted). Runs from a detached HEAD or a dirty tree too; results are judged against the working tree, and a dirty indexed file can shift line ranges.
--workdir <dir>Where the run's files go. Default <repo>/.document-drift, added to .git/info/exclude, never committed. Pass it only when the user asks, and then to every stage.
--date <YYYY-MM-DD>Fixes the branch date and run id (for tests). Pass it only when the user asks.
--retriedOnly on the rerun of a stage that exited 3, after dispatching retry.json. An output still missing or invalid then leaves its unit or batch unchecked, and the run goes on.

--base, --full, --branch, --check and --date are given to start, which records them; compose, verify and finish take them from that record and refuse a different value (exit 2).

Preconditions the run checks

start refuses (exit 2) when <repo> is not a git repository, is not the top level of a working tree (a subdirectory, a bare repository or a .git directory: pass the repository's top level), has no commits, or when --base names an unknown ref. Outside --check it also refuses a detached HEAD, uncommitted changes, an existing target branch, a missing git author identity (user.name and user.email) and an invalid branch name. compose refuses when this run writes no README. Any stage refuses when it is run out of order or with a flag that differs from the one start recorded, and finish refuses, before it applies anything, when HEAD moved during the run (naming both commits; a branch switch counts) or when files outside the workdir changed during the run (naming them).

Exit codes

CodeMeaningWhat to tell the user
0The stage succeeded. From finish: with edits, the branch exists with its commits and the user is on it; without edits, no branch was created.After start, compose and verify, nothing: go on to the next step. After finish, the final message below.
1finish under --check only: an edit would apply (an accepted edit, a kept notice edit, or a README that would be written). Nothing was changed.The printed summary; a run without --check would commit those edits.
2Refused before any change. compose also refuses when the run writes no README (readme: no), when start has not run, and when a flag differs from the one start recorded.The error line verbatim and what to fix (commit or stash, check out a branch, choose another --branch, set the git identity, run the stages in order with the same flags, leave the working tree and the checked-out branch alone during a run).
3The previous agent wave left missing or invalid output files; the stage wrote retry.json and changed nothing else.Nothing: dispatch the retry.json entries once and rerun the same stage with --retried.
5A script step crashed or a script's own expected output is missing. The message names the step; a crash outside a step names none, and at finish its message already carries the git status and git branch pointer.The error line verbatim. Stop: do not edit docs by hand. When the step is apply, commit or summary, docs may already be edited and the drift branch may exist: tell the user to check git status and git branch.
6The commit failed after the edits were applied to the working tree.The error line verbatim: it says where the edits are. Do not retry; the user decides.

What the user gets

  • One branch, docs/drift-<date> by default, created from the starting HEAD with at most three commits, docs(drift): correct stale docs (review edits and notice edits), then docs(drift): document missing surface (additions) and then docs(drift): correct citations and facts (script edits). A commit with no edits is not made. Each body has the lines Drift-Run: <run id>, Drift-Base: <starting HEAD sha>, Drift-Scope: first | since <sha> | base <ref> | full and Drift-Unchecked: <n> doc units, <n> gap docs, <n> verify batches, then one bullet per edit (- <doc>:<line> correct|remove|anchor|add|cite|fact ... and the notice bullets). The last commit made ends with a Needs a human decision: list when there is one: guarantees the code does not keep, unsure claims, blocks with a 2nd notice, edits too large or in a protected region, overlapping edits, names with no home, refused targets, edits a verifier rejected and edits reverted by the re-check. Only in-scope markdown files change. The Drift-Base line is how the next run finds where to start.
  • The third commit holds what scripts settle without an agent: a path:line citation whose definition moved, and a default, choices or required cell of a doc table that the code contradicts. Its bullets are - <doc>:<line> cite <subject> <old> -> <new> and - <doc>:<line> fact <name> <column> <old> -> <new> (<file>:<line>). Script edits are checked by script and skip the verifier. The summary has a Script edits section, and Edits proposed a script: line.
  • When the repository root has no README.md, the run also writes one from the code, in the additions commit, with the bullet - README.md:1 create readme (<n> statements from <n> sheets, <n> removed). Agents list what each area of the code offers its users, one agent writes the README from those lists citing them, and verifier agents judge every statement of it; a statement judged wrong or unsure is left out and listed under "Needs a human decision" as readme-rejected. With no accepted statement no README is written, and the summary says why.
  • No branch created when no edit was applied; the human-decision list is then in the summary only.
  • Markers the user can add to a doc: <!-- drift-ignore: reason --> (the next block), <!-- drift-ignore-next-line: reason -->, <!-- drift-ignore-file: reason -->. A marker needs the colon and a reason; one without is listed in the summary and has no effect.
  • The skill's own notices: a block that describes the code but names nothing the skill can tie to a definition gets a <!-- drift-unverified: 1st notice, ... --> comment on the line above it. The user answers it in one of three ways: name what the block describes (in an inline-code span), add a drift-ignore: <reason> marker, or rewrite the block. Any of them clears the notice on the next run (a rewritten block is reviewed afresh and may get a new 1st notice). Unanswered, the next run turns it into a 2nd notice and lists the block under "Needs a human decision"; unanswered again, the run after that removes the block and its notice. The user must not edit a notice by hand except to answer it; a malformed notice is listed as stale and left alone.
  • Optional .document-drift.yaml at the repository root:

    KeyDefaultEffect
    exclude[]Extra globs of docs to leave out.
    never_edit_headingnoneExtra regex for sections never edited.
    branchdocs/drift-{date}The branch name pattern.
    commit_trailers[]Lines appended at the end of each commit message.
    unit_lines6000Line budget per review unit.
    max_delete_lines15Larger removals go to a human.
    max_section_lines40Larger additions go to a human.
    min_anchor_ratio0.25Docs anchoring below this are listed as weakly anchored.
    undocumented_ok[]Globs of names that are never gaps.
    readmetrueWrite a README when the root has none; false turns that off.
    area_lines5000Line budget per area of code, one sheet agent each.
    readme_lines300The longest README the writer may produce.
    caps.review / caps.gaps / caps.verify40 / 15 / 25Agents per run per role; work beyond a cap is listed as unchecked.
    caps.sheet_agents / caps.readme_batch12 / 15Areas given a sheet agent per run; README statements per verifier batch.
    models.review / models.gap / models.verifysonnet / sonnet / opusThe model each role's agents run on.
    models.sheet / models.readmesonnet / opusThe model of the sheet agents and of the README writer.

Final message

Your final message to the user is the summary finish printed, verbatim, followed by the branch name (or No branch created). Add nothing else except one line saying that pushing the branch and opening the pull request are theirs to do.

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.