Auditing derived artifact claude md

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:

1. Standardized dimensions so nothing is forgotten across audits.
2. A consistent output shape so audits done six months apart are comparable.
3. Re-audit trigger recommendations so the audit isn't a one-shot.
4. 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 <auditor>. 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.