| name | auditing-derived-artifact-claude-md |
| description | Use when an existing CLAUDE.md in a derived or projected directory (symlink view, build cache, mirror, generated docs, materialized projection) needs to be re-checked against current upstream governance — e.g., upstream rules document was updated, sibling artifact added/removed, manifest schema evolved, or a pre-deploy sanity check is needed on the derived file's guidance. |
Auditing a derived-artifact CLAUDE.md for drift
Overview
A capable agent can usually enumerate drift between a derived CLAUDE.md and current upstream — they read both, list what's missing, suggest fixes. That's table stakes. This skill exists to add four things on top:
- Standardized dimensions so nothing is forgotten across audits.
- A consistent output shape so audits done six months apart are comparable.
- Re-audit trigger recommendations so the audit isn't a one-shot.
- Anchoring patterns so future drift is detected automatically.
Pair skill: writing-derived-artifact-claude-md (for the initial write).
When to Use
Use when one of these triggers fires:
- Upstream CLAUDE.md, README, INGEST-RULES, or any authoritative governance doc has a new commit / version / SHA
- A sibling derived artifact has been added or removed (changes the "family" section)
- The manifest schema or generator script signature has changed
- Time-based: scheduled audit (quarterly / pre-release / before onboarding a new agent class)
- A new contributor will edit the derived artifact and the existing CLAUDE.md hasn't been audited recently
Do not use when:
- The derived directory has no CLAUDE.md yet (use
writing-derived-artifact-claude-md instead)
- The upstream itself is what changed physically (file moves, deletions) — that's a "regenerate the artifact" task, not an audit task
- The CLAUDE.md is for a code repo (use general code-review tools)
The five audit dimensions
Scan the derived CLAUDE.md against the current upstream along these five axes. Each item found becomes a row in the drift report (Section "Output format" below).
D1 — Missing upstream rules
Rules / sections / constraints in current upstream that the derived file does not reference at all. Example: upstream added a "Hard Rejects" list; derived doesn't mention it.
Severity: high if rule directly affects the "edit upstream → regenerate" path the derived advertises; medium if rule affects a related path; low if rule is multi-step / multi-reviewer only and the derived's typical user wouldn't trigger it.
D2 — Stale version references
Derived references upstream docs by name but no version anchor (no SHA, no version number, no "last audited on YYYY-MM-DD" stamp). Or references a specific version older than current upstream.
Severity: medium (silent drift risk). Fix is to add an anchor.
D3 — Hardcoded facts that drift
Derived inlines specific facts about the artifact (current file count, current symlink targets, current consumer list) that change on every rebuild or manifest update.
Severity: low individually, but accumulates. Fix is to replace with "see X for current state."
D4 — Step / ordering omissions
Derived describes an upstream flow but skips steps or has them in wrong order. Example: upstream §3 is Hard-Reject scan → path check → 5-dim score → final approval; derived says 5-dim score → final approval (skips first two).
Severity: high (silent bypass of mandatory steps).
D5 — Broken or aged cross-references
Derived links to upstream by path; the path moved, was renamed, or the linked doc was deprecated. Includes "still-points-to-template" cases where the derived was instantiated from a template but never updated the template links.
Severity: high if the link is in a "must-read" section; medium otherwise.
Output format
Always emit the audit report in this structure. Future audits compare row-by-row to detect regression.
# Drift Report: <derived path> vs <upstream paths>
## Audit metadata
- Auditor: <agent or human + date>
- Upstream docs scanned: <list with current SHA or version>
- Derived doc SHA at audit time: <sha256>
- Last prior audit: <date or "first audit">
## D1 — Missing upstream rules
| # | Rule (upstream section) | Severity | Why it matters |
|---|---|---|---|
## D2 — Stale version references
| # | Reference | Current upstream version | Anchor in derived | Severity |
|---|---|---|---|---|
## D3 — Hardcoded facts that drift
| # | Fact (line ref) | Why it drifts | Suggested replacement |
|---|---|---|---|
## D4 — Step / ordering omissions
| # | Flow described | Upstream order | Derived order | Severity |
|---|---|---|---|---|
## D5 — Broken or aged cross-references
| # | Link / reference | Current state | Severity |
|---|---|---|---|
## Fix recipe (ordered by severity then dependency)
1. ...
2. ...
## Recommended re-audit triggers
- ...
## Self-rating
N/10 with stated blind spots
Empty sections stay in the report ("no items found in this dimension") — explicit "checked, nothing found" is more useful than absence.
Anchoring patterns (apply during fix, not audit)
When fixing drift, prefer these patterns to prevent re-drift:
- SHA anchor block at top of derived CLAUDE.md listing each upstream doc's current SHA256 + version. Future audits read this first.
- Version pin in the "Upstream governance" section: "Based on
INGEST-RULES.md v1.2 (2026-05-14)."
- "Last audited" stamp at bottom: "Last drift audit: YYYY-MM-DD by . Re-audit when: <triggers>."
- "See live data" pointers instead of inlined facts: "See
.meta/view-build-log.jsonl for current manifest snapshot" beats "currently links 4 wangwei handoffs + 1 douyin file."
Common mistakes
- Treating absence-of-mention as "intentional omission" by default. Upstream rules that affect the derived's advertised path are presumed required unless the derived explicitly states "X is out of scope here because Y."
- Skipping D3 because it feels nitpicky. Hardcoded facts are the silent killer — a file the agent reads as authoritative becomes a lie on the next rebuild.
- Forgetting to record audit metadata. Without auditor + date + upstream SHA, the next audit can't tell what changed.
- Auditing without anchoring fixes. A drift fix that doesn't add anchors will drift again. Always pair fix recipe with anchor recommendations.
- Treating D4 as low severity. Ordering omissions silently bypass mandatory steps; this is how compliance regressions ship.
Red flags — re-audit before declaring "PASS"
- Your audit found zero items. Either upstream didn't change since last audit (verify by checking upstream SHA), or you missed something — re-scan along all five dimensions explicitly.
- Your audit found only D1 items. D2/D3 nearly always exist on any derived file older than 30 days; their absence suggests you skipped checking them.
- Your fix recipe doesn't include any anchoring patterns. Re-derive will re-drift.
- Self-rating ≥ 9/10 with no stated blind spots. Honest audits almost always have a 6-8 confidence band with named gaps.
