drift-update
Skill1 starsChanged 34 days agoMITView on GitHub
Execute the handoff briefs a /drift-handoff run wrote to docs/audits/<audit-date>/<source-id>/ — apply each brief's edits, run its own verification steps, and stamp it done. Reads briefs from disk and never from the conversation, so it runs cold in a fresh session (preferred) or warm straight after /drift-audit and /drift-handoff. Walks briefs in numbered order with a checkpoint each — confirm the brief's quoted evidence still exists, apply, verify, stamp, continue — and stops on the first failure rather than pressing on. Briefs whose Kind is a decision or an investigation rather than an edit are put back to the user, never executed. Skips briefs already carrying an execution log, so an interrupted run resumes where it stopped. Hands off to /commit at the end.
In this repository38 other files it gives its agents.
- claude/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- author-skillSkill
- drift-auditSkill
- drift-handoffSkill
- test-skillSkill
- triageSkill
- fabric-iqSkill
- fabric-catalog-governanceSkill
- fabric-deploySkill
- fabric-rest-apiSkill
- fabric-securitySkill
- fabric-variable-librarySkill
- fabric-databaseSkill
- fabric-dataflowSkill
- fabric-data-pipelineSkill
- fabric-sparkSkill
- fabric-warehouse-monitoringSkill
- fabric-warehouseSkill
- fabric-activatorSkill
- fabric-eventhouseSkill
- fabric-event-schema-setSkill
- fabric-eventstreamSkill
- fabric-realtime-dashboardSkill
- learnSkill
- fabric-semantic-model-auditSkill
- fabric-tmdlSkill
- pbip-project-structureSkill
- pbir-report-workflowSkill
- linkedin-highlightsSkill
- msix-packagingSkill
- code-reviewSkill
- commitSkill
- find-sessionSkill
- landSkill
- prune-branchesSkill
- recreate-repoSkill
- run-briefsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 13 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Read every brief from disk, every time: Never reconstruct one from the conversation, from memory of an audit, or from a summary, even when …
- Very specific: line 36
Check whether /drift-audit or /drift-handoff ran in this session.
- Distinctive: line 66
Use it directly. This is the shape of the hand-written invocation this skill replaces, so it must keep working.
- Distinctive: line 114
If every brief is already stamped, say so and stop.
- Distinctive: line 117
If the directory does not exist, stop:
- Distinctive: line 126
Read each brief's Kind line before doing anything with it.
- Very specific: line 178
Before editing, confirm each target in What to change still looks like the brief says it does: Grep for the quoted offending line at the …
- Distinctive: line 214
A brief can foresee its own staleness: When its Sequencing note names the sibling brief that rewrites the quoted text, and says what to do …
- Distinctive: line 247
Text this run wrote is not adjacent: When a later brief, or a later verification step, makes text an earlier brief wrote this run false, …
- Distinctive: line 261
Run the brief's own Verification section, in order, as commands.
- Distinctive: line 289
One check this skill cannot perform: no brief that edits a skill can have its behaviour validated in the session that applied it.
- Very specific: line 402
Brief-format defects: If a brief could not be executed without opening 00-audit-report.md, say which one and what was missing from it.
- Distinctive: line 429
Do not start the work an escalated decision implies, and do not begin the next source's briefs.
- Distinctive: line 434
Briefs come from disk: Never from the transcript, a summary, or memory.
- Distinctive: line 437
The brief set is the scope: No unbriefed edits, no adjacent fixes, no re-opened reasoning.
- Distinctive: line 454
First failure stops the run: Leave the tree as it is and report.
≈ “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.
Files
Drift update
Execute the briefs on disk. /drift-audit finds the drift, /drift-handoff
writes it down, and this skill is the third turn: it applies what the briefs
specify, verifies with the steps the briefs supply, and records that it ran.
The briefs are the instruction set. This skill contributes the loop around them — resolution, a staleness gate, triage, checkpointing, and a stamp — not the content of any edit.
Read every brief from disk, every time. Never reconstruct one from the conversation, from memory of an audit, or from a summary, even when this session produced it. The file is the contract; the transcript is not.
Paths below are relative to the repo root. This skill is project scope — it
lives in .claude/skills/, deployed nowhere since 2026-09-09 — so it only
fires in sessions inside this repo.
1. Preconditions and session posture
Fresh session is the intended way to run this. A brief is written to be read cold; running cold is what proves it was written well.
Check whether /drift-audit or /drift-handoff ran in this session. If
either did, this is a warm run. A report that is merely present does not
count: an @-mention or a path argument loads 00-audit-report.md with its
## Audit window and ## Recommended actions intact, but none of the audit
turn's context the limits below exist for. Runs on 2026-09-08 and 2026-09-11
both met this and stamped themselves fresh. Warm is allowed, with two limits:
- Refuse a brief whose targets include
.claude/skills/drift-audit/,.claude/skills/drift-handoff/, or.claude/skills/drift-update/. Editing the skill that produced the briefs, in the session that produced them, is the one case where warm is actually unsound. Name the brief, say why it was skipped, and tell the user to run it from a fresh session. - Cap the run at three briefs. The audit turn is the expensive one; its
fetched sources and artifact sweep are still resident. Apply the first three
eligible briefs, stop, and report the remainder as pending a fresh session.
The cap counts briefs this run applies; one that 4.2 stamps as
already-appliedcosts a grep and an append, so it does not consume the budget. Compaction part-way through an edit is worse than a restart, because a compacted session is a lossy warm one — strictly worse than a cold one.
Say which posture the run used in the closing report. A warm run that does not announce itself looks like a cold one that skipped work.
2. Resolve the brief set
The target is a directory: docs/audits/<audit-date>/<source-id>/.
Argument forms, all optional:
- A path —
docs/audits/2026-08-29/fabric, in either slash style. Use it directly. This is the shape of the hand-written invocation this skill replaces, so it must keep working. - ISO date (
YYYY-MM-DD) — that run's directory. If it holds more than one source directory, apply the multi-source rule below. - Source id (
fabric,powerbi,vscode-agent,claude-code, …) — that source under the most recent audit date that has one. - Trailing brief numbers — one integer, or a comma-separated list
(
1,2,3,5), restricts the run to those briefs, still walked in numbered order. Without them a cold run has no cap and walks every unstamped brief in one pass; name numbers to keep a session to a batch one/commitcan review. - No argument — the most recent date directory under
docs/audits/.
Multiple source directories under one date are separate runs of work, not one
run. List them and ask which to execute. Do not silently pick the first or
concatenate them: sources produce unrelated edits with unrelated verification,
which is the same reason /drift-handoff gives them sibling directories.
Take the pass's worktree before reading its briefs, named after the
directory: EnterWorktree with the name <audit-date>-<source-id>, such
as 2026-09-12-skills-for-fabric, as root CLAUDE.md has a brief take
one. A pass holds every brief's edits uncommitted until step 5, which in
the main checkout leaves them in reach of a peer's commit. The worktree
branches from local HEAD, where /drift-handoff committed the
directory: if git status --short <directory> prints anything, stop and
have it committed first, or the worktree starts without it.
- One by that name already in
git worktree listis a stopped run's. Enter it withpath: its stamps, the resume mechanism below, are there, and the main checkout, which has none, would re-run every brief. - A refusal naming
git resolves its working tree to <path>came after the worktree was made (2026-09-30). Enter it withpath, spelled as that message prints it, rather than recreating it as the message suggests.
Then, in the resolved directory:
Globthe numbered briefs, at the top and undercompleted/.00-audit-report.mdis not a brief; it is evidence, and step 4 governs when to open it.README.mdis not one either: it is the generated index of the directory, worth a glance for where things stand, but the## Execution login each brief is the resume mechanism, not the index's status column or the brief's folder.- Skip any brief already carrying an
## Execution logsection. That is the resume mechanism. Every brief undercompleted/carries one, since 4.5 files a brief there only once its log leaves nothing open; the top holds the rest, unstamped or stamped open. Report skipped-as-done briefs by name so a short run is never mistaken for an empty one. - If every brief is already stamped, say so and stop. Nothing to do is a result, not a failure.
If the directory does not exist, stop:
No briefs at
<path>. This skill executes briefs that/drift-handoffalready wrote; it does not derive work from an audit report. Run/drift-auditthen/drift-handofffirst, or name an existing directory underdocs/audits/.
3. Triage — which briefs this skill may execute
Read each brief's Kind line before doing anything with it. It is the metadata block's most load-bearing field and it classifies the brief:
- Edit — "factual correction to committed prose", "rewrite the lineage section", "propagate a GA status". Execute it.
- Decision — the Kind says the output is a decision, a scoping call, or
that no file is corrected by this brief. The worked case is a brief reading
Kind: scoping decision, not an edit, whose body then says it exists to make the decision makeable, not to make it. Never execute one. Present the brief's problem and evidence to the user, ask the question it poses, and record the answer per step 4.6. A skill that cheerfully writes a new skill because a brief mentioned one has misread its only instruction. - Investigation — the Kind says measurement, probe, research or an empirical step, and no edit is authorized until it reports. Split it by what it needs. A doc lookup settles like an edit's own fetch: run it, and apply the edit only if the page establishes it. Anything more — a person at a GUI, a tenant, a cold probe session, a repo the user chooses — is not run here: escalate it per step 4.6 with the brief's method named, so it runs later as its own task. This kind went unnamed until 2026-09-11, and runs improvised it: one probed for a running Desktop before escalating, another relabelled a measurement as a decision.
- Self-referential — the target is the drift skills' own machinery, most
often
.claude/skills/drift-audit/references/. Apply it, but understand what verification is available: such a brief typically specifies "verified by re-running an audit, not by grepping prose", and this skill cannot re-run an audit against its own just-edited registry. Run the gates that do apply, then record the behavioural check as deferred to the next/drift-auditrun in the execution log and in the closing report.
A sub-sectioned brief (## D-1, ## D-2, …) is triaged per defect. A defect
carrying an Open question blocks that defect only — ask the user about it,
apply the rest of the brief, and note the deferral in the execution log.
4. The per-brief loop
One brief at a time, in numbered order — that order encodes dependency where one exists. Each brief runs the full loop before the next one starts. Stop the whole run on the first failure; do not skip ahead to an easier brief.
4.1 Read the brief
In full, from disk. Honour every section, not just What to change:
- Constraint on the fix bounds the edit. It usually names what the evidence does not establish, precisely so the fix does not overreach. Obey it even when a broader change looks obviously right.
- Not fixable / Out of scope describes what survives the fix on purpose. Do not attempt those parts, and do not report them as incomplete.
4.2 Staleness gate
Briefs are executed days or weeks after they are written, and the tree moves.
Before editing, confirm each target in What to change still looks like the
brief says it does: Grep for the quoted offending line at the named path.
- Quote found — proceed to 4.3.
- Quote absent — do not guess and do not search for something similar.
Grep once more at the same path, this time for the brief's intended
post-fix text. A missing quote means one of two opposite things, and that
second grep is the only cheap way to tell them apart:
- Corrected text present — the fix is already in the tree, applied by
hand or by an earlier unstamped run. That run may have failed 4.4,
which leaves its edits in place unstamped, so the text proves the edit
was made and not that it passed. Skip 4.3, run the brief's own
Verification as 4.4 does — a failure stops the run there too — and
on a pass go to 4.5 and stamp it
already-applied. Nothing is edited, but the brief is now done and a later run passes over it. Without this stamp the run never converges: a set applied by hand before this skill first ran would be re-derived in full, every time. - Corrected text also absent — the target was rewritten, renamed, or deleted for reasons the brief knows nothing about. The correction is not in the tree and this brief can no longer put it there. Stop the run and report it, as for a partially valid brief below. Do not stamp: a stamp here would silently retire an unaddressed correction.
- Corrected text present — the fix is already in the tree, applied by
hand or by an earlier unstamped run. That run may have failed 4.4,
which leaves its edits in place unstamped, so the text proves the edit
was made and not that it passed. Skip 4.3, run the brief's own
Verification as 4.4 does — a failure stops the run there too — and
on a pass go to 4.5 and stamp it
- Some targets found, some not — treat it as a stop. A partially valid brief means the tree diverged in a way nobody predicted, and that deserves a human look before anything is written.
A target that is itself an audit brief may since have moved into its
directory's completed/, where 4.5 files a brief whose log leaves
nothing open. If the named path is missing and
completed/<same filename> exists, it is the same file, not a
lookalike: grep it for the post-fix text. Found, it is
already-applied as above, with the Verification run against that
path and the path recorded under Deviations. Anything else stops
the run: the brief it targets finished by a route this one did not
foresee.
A brief can foresee its own staleness. When its Sequencing note
names the sibling brief that rewrites the quoted text, and says what to
do once that brief has run, the divergence is predicted, not unknown:
confirm the sibling's log stamps it applied, grep for whatever of the
quote the note says survives, follow the note, and record the changed
quote and the note under Deviations. Anything the note does not
cover still stops the run. Three of ten briefs in the 2026-10-06
fabric-iq-ontology pass met this, each quoting text fabric/04 or
fabric/07 had since rewritten as its note predicted (2026-10-07).
Otherwise, an explicit instruction is the one way past a missing quote. When the user names where the quoted text now sits ("it moved two paragraphs down"), they have taken the human look this stop exists to force. Run the post-fix grep first, as above; then apply the fix at the line they named, and record the brief's quote, the line edited and that the user directed it under Deviations. A line this run found for itself never counts.
4.3 Apply
Make the edits the brief enumerates, at the paths it names, and nothing else.
Do not fix adjacent problems. Something else wrong in a file you are editing is a finding for the closing report, not licence to widen the diff. The audit / handoff / update split exists so that analysis, transcription, and execution stay separable; an unbriefed edit made here has no evidence behind it and no verification step written for it.
That holds when the user asks for them in the invocation, too — "fix any typos while you're in there": the request supplies neither the evidence nor the verification step. List them as adjacent findings in the closing report, where they can be briefed or fixed outside the run.
Text this run wrote is not adjacent. When a later brief, or a later
verification step, makes text an earlier brief wrote this run false,
correct it before the run ends, and record it under Deviations in
the log of the brief that caught it; the earlier log stays as written,
true when stamped. In the 2026-10-06 fabric-iq-ontology pass, brief
09 explained in §1 what brief 08 had just written that nothing
explained (2026-10-07).
Equally, do not re-open the brief's reasoning. If the brief looks wrong,
stop the run and say so in chat rather than improving it in passing — the same
rule /drift-handoff follows when transcribing.
4.4 Verify
Run the brief's own Verification section, in order, as commands. It is numbered and runnable for exactly this reason, and the shared-verification test is what decided the brief's boundaries in the first place.
Two adjustments to the repo's standard gates:
uv run --with pyyaml scripts/lint-frontmatter.py <file>— run per brief, on any skill or rule file it touched.pre-commit run --all-files— run once at the end of the whole run, not per brief. It is repo-wide and slow, and per-brief runs tell you nothing extra. Skip it only when the run wrote nothing, which means a brief set that came back wholly already-stamped. Analready-appliedstamp is a write: its log and the regenerated index are a diff underdocs/audits/, whichlint-audit-indexandlint-briefsboth check.
A failed verification stops the run. Report the command, its output, and the state of the tree; leave the edits in place rather than reverting, so the user can see what happened.
A step that needs the deployed payload is deferred, not failed, since
the worktree cannot reach it: a claude/ file checked once deployed
(link-claude.ps1 refuses a worktree), or a probe of a skill in a
deployed group, workflow, social or meta, which reads the main
checkout's copy. Stamp it under Deferred with a **Needs**: line and
run it on main after the landing (step 5);
docs/handoffs/execute/README.md § "Every brief takes a worktree" has
the measurements.
One check this skill cannot perform: no brief that edits a skill can have
its behaviour validated in the session that applied it. Skills hot-reload
(.claude/rules/editing-skills.md), but that session's context can mask a
co-load failure, and it already knows the answers it would check for. Lint
and prose checks pass; behavioural confirmation is a fresh-session task. Say
so rather than implying the skill was exercised, and name the task:
/test-skill <skill> @<brief>, which takes the brief's What to change as
the claim to separate from the baseline and appends its confirmation to this
execution log rather than deleting the brief.
4.5 Stamp
Append to the brief file:
## Execution log
- **Executed**: <ISO date> — <applied | applied with deferrals |
already-applied | escalated>
- **Session**: <fresh | warm>
- **Files changed**: `<path>`, `<path>`
- **Verification**: <which steps ran and passed>
- **Deferred**: <what could not be checked here, and what would check it>
- **Deviations**: <anything done differently from the brief, and why — or none>
- **Needs**: <only when work is left open: user, tenant, desktop or a short
phrase, comma-separated, or none — then what it is for>An already-applied stamp uses the same shape with different content:
Files changed is none, and Verification names the confirming grep
from 4.2 — the post-fix text, found at the named path — and then the brief's
own steps, which 4.2 ran before stamping.
Append; never rewrite the brief above it. The brief as written is the record of what was decided, and the log is the record of what happened — keeping them distinct is what makes the pair auditable.
Then regenerate the directory's index:
uv run scripts/audit-status.py --dir <the resolved directory>That rewrites its README.md from the briefs, so this brief's row moves from
pending to the outcome and date just stamped. It also files the brief
under the directory's completed/ when the stamp leaves nothing open,
applied or already-applied, so the top lists only briefs still unrun
or open; an escalated, deferred or applied-with-deferrals brief stays
there until its **Closed**: line. The index and the folder are derived,
never edited, and the lint-audit-index pre-commit hook fails a commit
whose index disagrees with its briefs or whose brief sits on the wrong
side — so a stamp, its move and its regenerated README are one commit.
- **Closed**: <ISO date> — <how> is the key added after the stamp,
by whichever later session discharges what the log left open — an
/author-skill run that authored the accepted candidates, a /drift-audit
run that performed the deferred behavioural check, a decision the user made.
Append it to the existing log; the Executed and Deferred lines were
accurate when written and stay as they are. The index reads it and shows the
row as closed. Without it an escalated brief reads as open forever, which is
how the four skills authored from 2026-09-10 brief 07 left no trace in the
ledger until a later audit wrote a brief to record them. The one other key a
later session appends is a fresh **Needs**: line, when what the open work
waits on changes; the last one counts. A **Closed**: line moves the brief
into completed/ at the next regeneration, so re-point any live path to it
in that commit, though never a stamped brief's own text.
docs/audits/ is tracked, so these stamps are history and not just working
state: they make a re-run resumable, and they are also the record of what a
brief actually did. That does not make them the changelog — the commit message
still documents the change. Stamps are committed alongside the edits they
describe, so a brief and its outcome land together.
4.6 Checkpoint
Emit one line — brief number, outcome, files touched — then continue. Do not batch the reporting to the end; a run that fails at brief five should already have shown what briefs one through four did.
For an escalated brief, the checkpoint is the question itself. For a decision,
put the brief's problem and evidence in front of the user and ask; for an
investigation, say what it needs and ask where it should run. Stamp the answer
into the execution log as escalated. Whatever work the answer implies is a
separate task, started deliberately — not something to fold into this run.
That holds when the answer arrives with the invocation — "I've decided
yes, write those skills too": record it, stamp escalated, and name the
task on the Needs line (/author-skill, for a new skill).
That task needs a home before the run ends: the stamp's **Needs**:
line. The stamp makes every later run skip the brief, so work recorded only
in its log is seen only by what reads the log for it.
uv run scripts/handoff-status.py lists every escalated, deferred and
applied-with-deferrals brief with no **Closed**: line, grouped by that line,
and lint-briefs fails the commit on one without it. A deferred re-check
gets one too, naming what performs it, such as the next audit of that source,
and so does an adjacent finding, stamped applied with deferrals. Found
2026-09-11, when two runs' follow-ups turned out to be in no queue.
5. Report and hand off
Close with:
- Per-brief outcomes, one line each: applied, escalated, already-applied, already-stamped, or not-reached. Keep the last three distinct: applied is a change this run wrote, already-applied is one 4.2 found already in the tree and stamped now, already-stamped is one a previous run had already logged before this one started.
- Session posture, and anything the posture cost — briefs held back by the warm cap or the self-referential refusal.
- Deferred verification — every check that needs a fresh session or a
later
/drift-auditrun, named with what would perform it. - Adjacent findings — problems seen but deliberately not fixed.
- Brief-format defects. If a brief could not be executed without opening
00-audit-report.md, say which one and what was missing from it. A brief is supposed to be sufficient cold; every fallback to the report is evidence that/drift-handoffunder-specified one, and this is the only place that failure is observable. pre-commit run --all-filesresult — or that it was skipped because the run wrote nothing.
Then hand off to /commit. Unlike /drift-handoff, this skill changes tracked
files, so there is a real diff — and /commit splits it logically, which is
why this skill does not commit per brief. A brief 4.5 filed under
completed/ shows as a deletion plus an untracked file until both are
staged, when git reads the pair as a rename. If the run stopped early, say
plainly which edits are applied and uncommitted before handing over. A run
that wrote nothing has nothing to hand over: report the clean tree and stop,
rather than invoking /commit against an empty diff.
The pass lands as a brief's worktree does: from the main checkout, by
fast-forward with no push, by the commands docs/handoffs/CLAUDE.md
gives, once the user asks this session to leave the worktree. Then run
the deferred steps that need the deployed payload, deploying first, and
append **Closed**: to each brief whose steps pass, as 4.5 says.
A commit per brief is the user's to ask for: it trades /commit's logical
split for isolation, which counts in a tree another session shares. Hand
each brief to /commit once it is stamped, and say so under Deviations.
Do not start the work an escalated decision implies, and do not begin the next source's briefs. Both are separate, deliberate invocations.
6. Constraints
- Briefs come from disk. Never from the transcript, a summary, or memory.
- A pass runs in its own worktree (step 2) and lands from the main checkout (step 5).
- The brief set is the scope. No unbriefed edits, no adjacent fixes, no re-opened reasoning. Text this run wrote is in scope (4.3).
- Kind decides. Decision and investigation briefs are escalated, never
executed — and anything a run leaves for later gets a
**Needs**:line. - Stale splits two ways, and neither is improvising. A missing quoted
line means the fix already landed (stamp
already-applied) or the target moved (stop the run). Never substitute a line that looks close enough. A rewrite the brief's own sequencing note foresaw is neither: follow the note (4.2). - Two mechanics yield to an explicit instruction, and nothing else does: applying a moved line where the user names it (4.2), and a commit per brief (5), each recorded under Deviations. Adjacent fixes and a decision's work stay refused however the request is worded. Measured 2026-09-29: with only the listing entry in context, a request pre-authorizing all four was agreed to in 2 of 2 runs; with the body loaded, 3 of 4 still yielded, because it did not say which may.
- Constraints and Out-of-scope sections are binding, not advisory.
- First failure stops the run. Leave the tree as it is and report.
- Stamp what ran, including deferrals and deviations.
- Warm runs announce themselves, cap at three briefs, and refuse briefs targeting the drift skills themselves.
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.

