From 118855a1c8819a0d925b54e1ab36b559a0edbf53 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 11:49:55 -0400 Subject: [PATCH 1/6] feat(claude-config): extend the audit-instructions catalog with checks I12-I14 Folds the context-engineering criteria work into the incumbent `audit-instructions` catalog rather than standing up a second one. The catalog already carried the three axes, eleven seeded checks I1-I11, the surface partition, and the source list; its consuming skill is already report-only, so "never auto-applied" is inherited, not built. Three rows added, each cited to a page re-fetched this session: - **I12** (behavioral / warning / all surfaces) flags an instruction asserting a Claude Code *harness* behavior the current official page contradicts. The subject is the product, not the model, which is what separates it from I8; `claude-memory`'s C7 checks references against the repo, never against a vendor page. - **I13** (mechanical / warning / non-memory) flags an `@path` written where `@` carries no import meaning, so the cited content silently never arrives. Import syntax is a property of the CLAUDE.md family; the skills page defines none. Distinct from `check-skill.sh` check 5, which verifies that backtick-cited internal files resolve. - **I14** (mechanical / info / agent definitions and skill bodies) flags an instruction telling a subagent to read a surface its own startup context already contains. Each row carries its must-not-flag cases. Three official sources join the catalog's list: CLI reference, subagents, skills. A fourth candidate was drafted and then eliminated by the incumbent gate. "Flag a positive-form absolute pinning a style value the working context already exhibits" is covered on non-memory surfaces by I4 ("content the model can derive from the code, standard language conventions it already knows") and on memory surfaces by `claude-memory`'s C5, which carries the identical official quote. It is also refuted rather than merely unbacked: the memory page's Specificity section holds up *"Use 2-space indentation" instead of "Format code properly"* as the good example -- the exact phrasing the check would have flagged. With that candidate gone, the `Default state` axis and the widened `OPINION` gloss drafted alongside it had no consumer, so they are not shipped. The `Authority` gloss instead states the rule the gate applied: a candidate whose only backing is a practitioner's claim earns a row when an official page states the behavior it asserts, and is eliminated when the search finds none. All fourteen checks remain `ANTHROPIC-DOCS` and the axis stays a closed three-value set. Version: `0.9.2` -> `0.10.0` (new backward-compatible checks are a MINOR bump under the semver the plugin's own CHANGELOG header declares). Catalog header `1.0.0` -> `1.1.0`. Co-Authored-By: Claude Opus 5 (1M context) --- .../claude-config/.claude-plugin/plugin.json | 2 +- plugins/claude-config/CHANGELOG.md | 19 +++++ plugins/claude-config/README.md | 4 +- .../skills/audit-instructions/SKILL.md | 6 +- .../audit-instructions/evals/evals.json | 4 +- .../audit-instructions/reference/criteria.md | 75 +++++++++++++++++-- 6 files changed, 97 insertions(+), 13 deletions(-) diff --git a/plugins/claude-config/.claude-plugin/plugin.json b/plugins/claude-config/.claude-plugin/plugin.json index 7e28ecc80..d2196ff36 100644 --- a/plugins/claude-config/.claude-plugin/plugin.json +++ b/plugins/claude-config/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-config", - "version": "0.9.2", + "version": "0.10.0", "description": "Four audit skills for a repo's Claude Code configuration: audit (settings.json / .mcp.json / hooks / plugins / permissions drift), audit-automation-gaps (evidence-gated verdicts on automation gaps), audit-permission-grants (allow-rule / allowed-tools grants for auto-mode durability and portability), and audit-instructions (locally-owned instruction surfaces vs current model capability — proposes removals/rewrites of instructions the model no longer needs).", "author": { "name": "Melodic Software", diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index 0876ec9d4..6158ffdda 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -3,6 +3,25 @@ All notable changes to the `claude-config` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.10.0] + +### Added + +- **`audit-instructions` checks I12–I14**, extending the existing `reference/criteria.md` catalog + rather than standing up a second one. I12 flags an instruction asserting a Claude Code *harness* + behavior that the current official page contradicts — the product, not the model, which is what + separates it from I8. I13 flags an `@path` written where `@` carries no import meaning, so the + cited content silently never arrives. I14 flags an instruction telling a subagent to read a + surface its startup context already contains. Each row carries its must-not-flag cases, and the + three new official sources (CLI reference, subagents, skills) join the catalog's source list. + +### Changed + +- **`Authority` gloss states what an unbacked candidate earns.** A candidate whose only backing is + a practitioner's claim becomes a row when an official page states the behavior it asserts, and is + eliminated when the search finds none. All fourteen checks remain `ANTHROPIC-DOCS`, and the axis + stays a closed three-value set rather than widening under every existing consumer. + ## [0.9.2] ### Changed diff --git a/plugins/claude-config/README.md b/plugins/claude-config/README.md index 5af96b30b..6078d555f 100644 --- a/plugins/claude-config/README.md +++ b/plugins/claude-config/README.md @@ -72,8 +72,8 @@ Audits instruction *content* against current model capability — a different qu sibling audits (config-file correctness) and from `skill-quality:check` (structural lint) or `docs-hygiene:compress` (token brevity). It sweeps the locally-owned surfaces (user + project `CLAUDE.md`, `.claude/rules`, skill bodies, agent definitions, prompt-type hooks, output styles) -against an eleven-check catalog cited to current official prompting doctrine, running a fresh -read-only subagent per surface, then a fresh-context verify pass that re-judges every removal +against a fourteen-check catalog cited to current official prompting and harness doctrine, running +a fresh read-only subagent per surface, then a fresh-context verify pass that re-judges every removal proposal before it is surfaced. Findings are tiered mechanical vs behavioral and delivered as a report plus proposed diffs — report-only, never auto-applied. On memory-layer surfaces it runs only the model-era checks and routes hygiene findings to the `claude-memory` plugin's `audit` skill (with diff --git a/plugins/claude-config/skills/audit-instructions/SKILL.md b/plugins/claude-config/skills/audit-instructions/SKILL.md index d2c76e53f..9673436d0 100644 --- a/plugins/claude-config/skills/audit-instructions/SKILL.md +++ b/plugins/claude-config/skills/audit-instructions/SKILL.md @@ -17,7 +17,7 @@ doctrine, tiers it by how confident the evidence can be, and packages proposed r rewrites as a human-gated diff — so instruction surfaces shrink as models get better instead of only ever growing. -The check catalog — the eleven checks I1–I11, their evidence tier, authority tag, severity, and +The check catalog — the fourteen checks I1–I14, their evidence tier, authority tag, severity, and per-surface applicability — lives in [reference/criteria.md](reference/criteria.md). The deterministic pre-scan is `${CLAUDE_PLUGIN_ROOT}/skills/audit-instructions/scripts/instruction-scan.sh`. @@ -39,7 +39,7 @@ concerns its siblings already cover — route rather than re-answer: portability is `claude-config:audit-permission-grants`. On **memory-layer surfaces** (CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, `~/.claude/rules/`), -this skill runs only the model-era checks I6–I11. It never runs or reports the hygiene checks +this skill runs only the model-era checks I6–I12. It never runs or reports the hygiene checks I1–I5 (line-necessity, length, placement, inferable content, rule-to-hook) on these surfaces — that instruction-memory hygiene layer belongs to the `claude-memory` plugin. When that plugin is installed, route memory-layer hygiene to its `audit` skill; when it is not installed, emit a single @@ -47,7 +47,7 @@ one-line pointer to the official CLAUDE.md include/exclude guidance (recorded wi [reference/criteria.md](reference/criteria.md)) so the operator knows where that audit lives — this skill still does not perform it. Either way, no I1–I5 hygiene finding is ever produced here. On **non-memory surfaces** (skill bodies, agent definitions, prompt-type hooks, output styles) the -full catalog I1–I11 applies — no incumbent auditor covers instruction content there. +full catalog I1–I14 applies — no incumbent auditor covers instruction content there. **Upstream-owned surfaces are excluded from the editable set.** Installed plugin-cache content is owned by the publishing repository, and a managed materialization is owned by whatever upstream diff --git a/plugins/claude-config/skills/audit-instructions/evals/evals.json b/plugins/claude-config/skills/audit-instructions/evals/evals.json index 440c6dd48..b66d48435 100644 --- a/plugins/claude-config/skills/audit-instructions/evals/evals.json +++ b/plugins/claude-config/skills/audit-instructions/evals/evals.json @@ -17,11 +17,11 @@ "id": 2, "name": "scope-boundary-routes-out", "prompt": "/claude-config:audit-instructions is my CLAUDE.md too long, and can you prune the always-loaded hygiene lines out of it?", - "expected_output": "Recognizes memory-layer hygiene — line budget, whether CLAUDE.md is too long, pruning always-loaded content — as the claude-memory plugin's audit skill's concern. On memory-layer surfaces (CLAUDE.md, CLAUDE.local.md, .claude/rules) this skill runs only the model-era checks I6-I11 and routes the I1-I5 hygiene findings to claude-memory:audit when that plugin is installed, falling back to the official CLAUDE.md include/exclude guidance pointer when it is not, rather than answering the hygiene question itself.", + "expected_output": "Recognizes memory-layer hygiene — line budget, whether CLAUDE.md is too long, pruning always-loaded content — as the claude-memory plugin's audit skill's concern. On memory-layer surfaces (CLAUDE.md, CLAUDE.local.md, .claude/rules) this skill runs only the model-era checks I6-I12 and routes the I1-I5 hygiene findings to claude-memory:audit when that plugin is installed, falling back to the official CLAUDE.md include/exclude guidance pointer when it is not, rather than answering the hygiene question itself.", "files": [], "expectations": [ "Routes memory-layer hygiene (line budget, 'CLAUDE.md too long', pruning) to the claude-memory plugin's audit skill when installed", - "On memory-layer surfaces runs only the model-era checks I6-I11, not the I1-I5 hygiene checks", + "On memory-layer surfaces runs only the model-era checks I6-I12, not the I1-I5 hygiene checks", "Falls back to the official CLAUDE.md include/exclude guidance pointer when claude-memory is not installed instead of silently skipping" ] }, diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index 804aff19c..ce959f521 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -1,7 +1,7 @@ # Instruction-Audit Criteria -Version: 1.0.0 -Last updated: 2026-07-21 +Version: 1.1.0 +Last updated: 2026-07-25 The checks the `audit-instructions` skill runs, seeded from current official prompting doctrine. Each check carries an evidence tier, an authority tag, a default severity, its surface @@ -19,15 +19,17 @@ are superseded on each model generation. truth is observed model behavior, so findings ship as proposals verified by the delete-and-watch loop, never confident removals). - **Authority** — `ANTHROPIC-DOCS` (official documentation), `TALK` (a recorded talk), `OPINION` - (a practitioner's stated practice). All eleven seeds are `ANTHROPIC-DOCS`. + (a practitioner's stated practice). A closed three-value set. All fourteen checks are + `ANTHROPIC-DOCS`: a candidate whose only backing is a practitioner's claim earns a row when an + official page states the behavior it asserts, and is eliminated when the search finds none. - **Severity** — `error` / `warning` / `info`. **Surface partition.** Checks I1–I5 are the instruction-memory hygiene layer: they apply on non-memory surfaces (skill bodies, agent definitions, prompt-type hooks, output styles); on memory-layer surfaces (CLAUDE.md, CLAUDE.local.md, `.claude/rules/`, `~/.claude/rules/`) their findings route to the `claude-memory` plugin's `audit` skill when it is installed, and fall back -to the official include/exclude guidance (I1–I5 source below) when it is not. Checks I6–I11 apply -to all surfaces. +to the official include/exclude guidance (I1–I5 source below) when it is not. Checks I6–I12 apply +to all surfaces; I13 and I14 name narrower surface sets in their own rows. ## Sources @@ -40,6 +42,11 @@ to all surfaces. - The `.claude` directory — - Refusals and fallback (`reasoning_extraction`) — +- CLI reference (`claude doctor` and the other terminal forms) — + +- Subagents (what loads into a subagent at startup) — +- Skills (how a skill's supporting files are referenced and loaded) — + --- @@ -159,6 +166,64 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: - **Source:** best-practices — "CLI tools are the most context-efficient way to interact with external services." +### I12: Stale or misattributed harness-capability claim + +Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surfaces: all. + +- **Detect:** an instruction that asserts a Claude Code *harness* behavior — what a command does, + what a keystroke saves, what loads into which context window, what a mode persists — which the + current official page for that behavior contradicts or no longer documents. The subject is the + product, not the model, which is what separates this from I8. +- **Remediate:** correct the claim against the cited page, or cut it and point at the page instead + of restating it. Where the behavior is version-gated, carry the minimum version with the claim. +- **Must NOT flag:** prose that names two adjacent forms and distinguishes them correctly — the + terminal `claude doctor` being read-only while the in-session `/doctor` applies fixes is the + canonical pair, and a file that states both is right, not drifting. A bare routing pointer that + tells the reader to run a command without claiming what it does. Text that quotes a retired + affordance explicitly as retired. +- **Source:** CLI reference — "Print read-only installation and settings diagnostics from the + terminal without starting a session … For the in-session setup checkup that can also apply + fixes, run `/doctor`." + +### I13: Citation form that does not load + +Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surfaces: non-memory only +(skill bodies and their reference files, agent definitions, prompt-type hooks, output styles). + +- **Detect:** an `@path` written outside backticks and outside a fenced block on a surface where + `@` carries no import meaning, in a sentence that treats it as though the file arrives. Import + syntax is a property of the CLAUDE.md family; a skill's supporting files are reached by being + named so Claude knows when to read them, so an `@` there is inert text and its content silently + never arrives. +- **Remediate:** cite the file the way that surface actually resolves — a backticked path or a + markdown link the reader and the model can both follow. +- **Must NOT flag:** anything on a memory-layer surface, where `@path` genuinely imports. A + package scope (`@anthropic-ai/…`), a decorator, an email address, or a `@username` handle. A + backticked `` `@path` ``, which the import parser skips by design and which is the documented + way to mention a path without importing it. A path cited without an `@` at all. +- **Source:** memory — "CLAUDE.md files can import additional files using `@path/to/import` + syntax", against skills, where supporting files are instead referenced "so Claude knows what + each file contains and when to load it" and no import syntax is defined. + +### I14: Retrieval of an already-loaded surface + +Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: agent definitions and +skill bodies. + +- **Detect:** an instruction directing the agent to go read a surface that its own startup context + already contains — `CLAUDE.md`, `CLAUDE.local.md`, project rules, managed policy files. The read + spends a turn to retrieve text that is already present. +- **Remediate:** cut the retrieval step and state the requirement the read was meant to satisfy. +- **Must NOT flag:** an instruction to read a surface that is *not* auto-loaded — `AGENTS.md`, + contributing guides, ADRs, CI workflow files, per-ecosystem convention docs. Those are ordinary + progressive disclosure. An agent whose job is to audit an instruction surface, which must open + the file because inspecting it is the work rather than obeying it. A rule restated in a + delegation prompt for the built-in Explore and Plan agents, which are documented as the only + subagents that skip `CLAUDE.md` and have no per-agent setting to change that. +- **Source:** subagents, "What loads at startup" — a non-fork subagent's initial context contains + "every level of the CLAUDE.md hierarchy the main conversation loads, including + `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files." + --- ## Output format From 8faced0e0a4b9d8964e4dc609fae10595c804c44 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 18:06:57 -0400 Subject: [PATCH 2/6] fix(claude-config): close the three review findings on checks I12-I14 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Recheck triggers watched three pages while the catalog cites nine. Every check cites a page in the source list, so the trigger set is now the source list — a subset left the new harness-behavior rows depending on pages nothing watched. I12 treated a page that no longer documents a behavior as evidence the behavior drifted. Documentation silence is not evidence: pages are rewritten, condensed and reorganized, and this repository deliberately keeps empirical tests for behaviors the official pages never specified. Detection now requires an incompatible statement on the current page or a failed version-matched reproduction, and silence is called out as a must-not-flag rather than left implicit. I14 treated every CLAUDE.md and project rule as already resident, but the subagent guarantee it cites covers the hierarchy the main conversation loads. Nested CLAUDE.md files and path-scoped rules load lazily when work reaches their scope, so an instruction to read a package-local file before operating there can be doing real work. Detection is bounded to the startup-loaded set and the lazy-loaded surfaces are an explicit must-not-flag, with the memory page's own lazy-loading line carried in the source row as the bound. Also restates the Authority gloss descriptively: "all fourteen checks are currently ANTHROPIC-DOCS" is a statement about present contents, not a rule that would foreclose a future TALK or OPINION row. --- plugins/claude-config/CHANGELOG.md | 26 +++++++++--- .../audit-instructions/reference/criteria.md | 41 +++++++++++++------ 2 files changed, 48 insertions(+), 19 deletions(-) diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index 6158ffdda..ad70a1391 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -12,15 +12,29 @@ All notable changes to the `claude-config` plugin are documented here. Format fo behavior that the current official page contradicts — the product, not the model, which is what separates it from I8. I13 flags an `@path` written where `@` carries no import meaning, so the cited content silently never arrives. I14 flags an instruction telling a subagent to read a - surface its startup context already contains. Each row carries its must-not-flag cases, and the - three new official sources (CLI reference, subagents, skills) join the catalog's source list. + surface the main conversation loads at startup and therefore already carries. Each row carries its + must-not-flag cases, and the three new official sources (CLI reference, subagents, skills) join the + catalog's source list. ### Changed -- **`Authority` gloss states what an unbacked candidate earns.** A candidate whose only backing is - a practitioner's claim becomes a row when an official page states the behavior it asserts, and is - eliminated when the search finds none. All fourteen checks remain `ANTHROPIC-DOCS`, and the axis - stays a closed three-value set rather than widening under every existing consumer. +- **Recheck triggers now watch every page in the catalog's source list**, not the three originally + named. Each check cites one of those pages, so a subset left the new harness-behavior rows + depending on pages nothing watched. +- **I12 no longer treats documentation silence as drift.** Detection now requires an official page + stating something incompatible with the claim, or a failed version-matched reproduction. A page + that stops mentioning a behavior is not evidence the behavior changed — pages are routinely + rewritten and condensed, and this repository keeps empirical tests for behaviors the docs never + specified at all. +- **I14 is bounded to the surfaces actually loaded at startup.** The subagent guarantee it rests on + covers the hierarchy *the main conversation loads*; nested `CLAUDE.md` files and path-scoped rules + load lazily when work reaches their scope, so an instruction to read a package-local file before + operating there can be doing real work. Flagging it would have removed scoped instructions. + +- **`Authority` gloss restated descriptively.** It now reads "All fourteen checks are currently + `ANTHROPIC-DOCS`" — a statement about the catalog's present contents, not a rule. `TALK` and + `OPINION` stay reachable for a future row, and the axis stays a closed three-value set rather than + widening under every existing consumer. ## [0.9.2] diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index ce959f521..c0b446ab5 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -9,9 +9,10 @@ applicability, and one decisive source line (point-don't-copy — the full doctr cited URL, not restated here). **Recheck triggers** — treat these as staleness signals and re-verify the catalog against live -docs when any fires: a new frontier model release; any change to the two prompting-best-practices -pages; a change to the Claude Code best-practices page. Model-specific pages (the Fable 5 guide) -are superseded on each model generation. +docs when any fires: a new frontier model release; **a change to any page listed under Sources +below**. Every check cites one of those pages, so the trigger set is the source set — naming a +subset would leave the harness-behavior rows depending on pages nothing watches. Model-specific +pages (the Fable 5 guide) are superseded on each model generation. **Axes.** Three orthogonal axes, never conflated: @@ -19,9 +20,8 @@ are superseded on each model generation. truth is observed model behavior, so findings ship as proposals verified by the delete-and-watch loop, never confident removals). - **Authority** — `ANTHROPIC-DOCS` (official documentation), `TALK` (a recorded talk), `OPINION` - (a practitioner's stated practice). A closed three-value set. All fourteen checks are - `ANTHROPIC-DOCS`: a candidate whose only backing is a practitioner's claim earns a row when an - official page states the behavior it asserts, and is eliminated when the search finds none. + (a practitioner's stated practice). A closed three-value set. All fourteen checks are currently + `ANTHROPIC-DOCS`. - **Severity** — `error` / `warning` / `info`. **Surface partition.** Checks I1–I5 are the instruction-memory hygiene layer: they apply on @@ -171,11 +171,17 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surfaces: all. - **Detect:** an instruction that asserts a Claude Code *harness* behavior — what a command does, - what a keystroke saves, what loads into which context window, what a mode persists — which the - current official page for that behavior contradicts or no longer documents. The subject is the - product, not the model, which is what separates this from I8. + what a keystroke saves, what loads into which context window, what a mode persists — where + **either** the current official page for that behavior states something incompatible with it, + **or** a version-matched reproduction of the asserted behavior fails. The subject is the product, + not the model, which is what separates this from I8. - **Remediate:** correct the claim against the cited page, or cut it and point at the page instead of restating it. Where the behavior is version-gated, carry the minimum version with the claim. +- **Must NOT flag: silence.** A page that no longer mentions a behavior is not evidence the behavior + changed — product documentation is routinely rewritten, condensed, or reorganized, and this + repository deliberately keeps empirical smoke tests for behaviors the official pages never + specified at all. Absence of documentation raises the claim for reproduction; it does not + establish drift, and it never on its own justifies a removal. - **Must NOT flag:** prose that names two adjacent forms and distinguishes them correctly — the terminal `claude doctor` being read-only while the in-session `/doctor` applies fixes is the canonical pair, and a file that states both is right, not drifting. A bare routing pointer that @@ -210,10 +216,17 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: agent definitions and skill bodies. -- **Detect:** an instruction directing the agent to go read a surface that its own startup context - already contains — `CLAUDE.md`, `CLAUDE.local.md`, project rules, managed policy files. The read - spends a turn to retrieve text that is already present. +- **Detect:** an instruction directing the agent to go read a surface the main conversation loads at + startup and therefore already carries — the root `CLAUDE.md`, `~/.claude/CLAUDE.md`, + `CLAUDE.local.md`, unconditional project rules (no `paths` frontmatter), and managed policy files. + The read spends a turn to retrieve text that is already present. - **Remediate:** cut the retrieval step and state the requirement the read was meant to satisfy. +- **Must NOT flag: anything that loads on demand rather than at startup.** The guarantee this check + rests on covers the hierarchy *the main conversation loads*, which is not the whole memory family. + **Nested `CLAUDE.md` files in subdirectories and path-scoped rules (`paths` frontmatter) load + lazily when work reaches their scope**, so an instruction to read a package-local `CLAUDE.md` + before operating in that package can be doing real work. Flag only when the specific file named is + one of the startup-loaded set above; when a surface's residency is not established, leave it. - **Must NOT flag:** an instruction to read a surface that is *not* auto-loaded — `AGENTS.md`, contributing guides, ADRs, CI workflow files, per-ecosystem convention docs. Those are ordinary progressive disclosure. An agent whose job is to audit an instruction surface, which must open @@ -222,7 +235,9 @@ skill bodies. subagents that skip `CLAUDE.md` and have no per-agent setting to change that. - **Source:** subagents, "What loads at startup" — a non-fork subagent's initial context contains "every level of the CLAUDE.md hierarchy the main conversation loads, including - `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files." + `~/.claude/CLAUDE.md`, project rules, `CLAUDE.local.md`, and managed policy files." The qualifier + *the main conversation loads* is what bounds this check: memory documents lazy loading for + "path-specific rules or lazy-loaded files in subdirectories", so those are outside the guarantee. --- From 494b96993cc1d3d152971cd499d6df091eb87469 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 18:22:19 -0400 Subject: [PATCH 3/6] fix(claude-config): scope I14 to root-level memory files, both filename forms The startup list named CLAUDE.local.md without qualification while the must-not-flag exception covered only nested CLAUDE.md, so an instruction to open a package-local CLAUDE.local.md was flaggable. Lazy loading is a property of the location, not the name: both forms load when work reaches their subdirectory. The startup list now says root-level explicitly and the exception covers both forms. --- .../audit-instructions/reference/criteria.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index c0b446ab5..f59deaad2 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -217,16 +217,20 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: skill bodies. - **Detect:** an instruction directing the agent to go read a surface the main conversation loads at - startup and therefore already carries — the root `CLAUDE.md`, `~/.claude/CLAUDE.md`, - `CLAUDE.local.md`, unconditional project rules (no `paths` frontmatter), and managed policy files. - The read spends a turn to retrieve text that is already present. + startup and therefore already carries — the **root** `CLAUDE.md`, `~/.claude/CLAUDE.md`, the + **root** `CLAUDE.local.md`, unconditional project rules (no `paths` frontmatter), and managed + policy files. Root-level is load-bearing in that list: the startup guarantee is scoped to the + hierarchy discovered from the launch directory, not to every file of that name in the tree. The + read spends a turn to retrieve text that is already present. - **Remediate:** cut the retrieval step and state the requirement the read was meant to satisfy. - **Must NOT flag: anything that loads on demand rather than at startup.** The guarantee this check rests on covers the hierarchy *the main conversation loads*, which is not the whole memory family. - **Nested `CLAUDE.md` files in subdirectories and path-scoped rules (`paths` frontmatter) load - lazily when work reaches their scope**, so an instruction to read a package-local `CLAUDE.md` - before operating in that package can be doing real work. Flag only when the specific file named is - one of the startup-loaded set above; when a surface's residency is not established, leave it. + **Nested `CLAUDE.md` and nested `CLAUDE.local.md` files in subdirectories, and path-scoped rules + (`paths` frontmatter), load lazily when work reaches their scope** — both filename forms, since + the lazy-loading behavior is a property of the location rather than of the name. An instruction to + read either one before operating in that package can be doing real work. Flag only when the + specific file named is one of the startup-loaded set above; when a surface's residency is not + established, leave it. - **Must NOT flag:** an instruction to read a surface that is *not* auto-loaded — `AGENTS.md`, contributing guides, ADRs, CI workflow files, per-ecosystem convention docs. Those are ordinary progressive disclosure. An agent whose job is to audit an instruction surface, which must open From aee49bfb212b9fb689d3f8e444fca64cc8c2cfc5 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 18:29:05 -0400 Subject: [PATCH 4/6] fix(claude-config): match the version before matching the text in I12 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Detection compared a harness claim against the current page even when the claim was scoped to a pinned or supported older release, so an accurate version-gated instruction could be flagged and rewritten wrong. That contradicted I12's own remediation, which asks authors to carry a minimum version with such a claim. The comparison is now scoped to the version the claim is about, and a successful version-matched reproduction settles it — newer behavior on the latest page is then evidence of a version difference rather than of an inaccurate instruction. A claim carrying no version is about current behavior and is still measured against the current page. --- .../audit-instructions/reference/criteria.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index f59deaad2..6ddd425d7 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -172,9 +172,9 @@ Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface - **Detect:** an instruction that asserts a Claude Code *harness* behavior — what a command does, what a keystroke saves, what loads into which context window, what a mode persists — where - **either** the current official page for that behavior states something incompatible with it, - **or** a version-matched reproduction of the asserted behavior fails. The subject is the product, - not the model, which is what separates this from I8. + **either** the official documentation **for the version the claim is about** states something + incompatible with it, **or** a version-matched reproduction of the asserted behavior fails. The + subject is the product, not the model, which is what separates this from I8. - **Remediate:** correct the claim against the cited page, or cut it and point at the page instead of restating it. Where the behavior is version-gated, carry the minimum version with the claim. - **Must NOT flag: silence.** A page that no longer mentions a behavior is not evidence the behavior @@ -182,6 +182,14 @@ Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface repository deliberately keeps empirical smoke tests for behaviors the official pages never specified at all. Absence of documentation raises the claim for reproduction; it does not establish drift, and it never on its own justifies a removal. +- **Must NOT flag: a version-gated claim that still reproduces on its own version.** Match the + version before matching the text. A claim scoped to a pinned or supported older release is + measured against that release, not against the latest page, and **a successful version-matched + reproduction settles it** — the latest documentation describing newer behavior is then evidence of + a version difference, not of an inaccurate instruction. A claim carrying no version is about + current behavior and is measured against the current page. This is the mirror of the remediation + above: a catalog that asks authors to carry a minimum version must not then flag the claims that + do. - **Must NOT flag:** prose that names two adjacent forms and distinguishes them correctly — the terminal `claude doctor` being read-only while the in-session `/doctor` applies fixes is the canonical pair, and a file that states both is right, not drifting. A bare routing pointer that From 96bcb8c85c2e6fa82f522b87ddefcc137cbed146 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 18:40:44 -0400 Subject: [PATCH 5/6] fix(claude-config): make the new checks discoverable and narrow I13 The description framed the skill purely as finding instructions the model no longer needs, and only the description is available during skill selection. A request about a stale harness claim, a non-loading @path, or a redundant startup-surface read would not have selected the fourteen-check catalog that answers it. The description now names those three shapes and carries their trigger phrases; all six base-ref phrases are preserved. I13 treated the citation form itself as content loss, but an inert @path is still a legible path in the loaded prompt: "follow @reference/rules.md" works, and warning on it would flag a working instruction. Detection now requires prose asserting the file has already arrived, and the distinction is stated as a must-not-flag so a later edit does not widen it back. --- plugins/claude-config/CHANGELOG.md | 13 ++++++++++--- .../skills/audit-instructions/SKILL.md | 2 +- .../audit-instructions/reference/criteria.md | 16 +++++++++++----- 3 files changed, 22 insertions(+), 9 deletions(-) diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index 334fb8d46..c48af9668 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -10,14 +10,22 @@ All notable changes to the `claude-config` plugin are documented here. Format fo - **`audit-instructions` checks I12–I14**, extending the existing `reference/criteria.md` catalog rather than standing up a second one. I12 flags an instruction asserting a Claude Code *harness* behavior that the current official page contradicts — the product, not the model, which is what - separates it from I8. I13 flags an `@path` written where `@` carries no import meaning, so the - cited content silently never arrives. I14 flags an instruction telling a subagent to read a + separates it from I8. I13 flags prose written on the assumption that an `@path` imported on a + surface where `@` carries no import meaning. I14 flags an instruction telling a subagent to read a surface the main conversation loads at startup and therefore already carries. Each row carries its must-not-flag cases, and the three new official sources (CLI reference, subagents, skills) join the catalog's source list. ### Changed +- **Discovery vocabulary for the three new checks.** The `description` framed the skill purely as + finding instructions the model no longer needs, so a request about a stale harness claim, a + non-loading `@path`, or a redundant startup-surface read would not select it — and only the + description is available during selection. It now names those three shapes and carries their + trigger phrases. +- **I13 fires on the false assumption, not the citation form.** An inert `@path` on a skill surface + is still a legible path, so "follow `@reference/rules.md`" works and warning on it would flag a + working instruction. Detection now requires prose asserting the file has already arrived. - **Recheck triggers now watch every page in the catalog's source list**, not the three originally named. Each check cites one of those pages, so a subset left the new harness-behavior rows depending on pages nothing watched. @@ -30,7 +38,6 @@ All notable changes to the `claude-config` plugin are documented here. Format fo covers the hierarchy *the main conversation loads*; nested `CLAUDE.md` files and path-scoped rules load lazily when work reaches their scope, so an instruction to read a package-local file before operating there can be doing real work. Flagging it would have removed scoped instructions. - - **`Authority` gloss restated descriptively.** It now reads "All fourteen checks are currently `ANTHROPIC-DOCS`" — a statement about the catalog's present contents, not a rule. `TALK` and `OPINION` stay reachable for a future row, and the axis stays a closed three-value set rather than diff --git a/plugins/claude-config/skills/audit-instructions/SKILL.md b/plugins/claude-config/skills/audit-instructions/SKILL.md index 9673436d0..c64783fff 100644 --- a/plugins/claude-config/skills/audit-instructions/SKILL.md +++ b/plugins/claude-config/skills/audit-instructions/SKILL.md @@ -1,6 +1,6 @@ --- name: audit-instructions -description: "Audit locally-owned Claude Code instruction surfaces — user + project CLAUDE.md, .claude/rules, skill bodies, agent definitions, prompt-type hooks, output styles — for instructions current models no longer need: prior-model workarounds, over-prescriptive scaffolding, bare prohibitions, reasoning-echo directives, stale examples. Report-only: emits a findings report with proposed diffs, gated to the human, never auto-applied. Use when: 'after a model upgrade', 'are my instructions holding the model back', 'instructions the model no longer needs', 'too prescriptive', 'audit instructions', 'instruction audit'. Not a brevity pass and not memory-layer hygiene." +description: "Audit locally-owned Claude Code instruction surfaces — user + project CLAUDE.md, .claude/rules, skill bodies, agent definitions, prompt-type hooks, output styles — for instructions current models no longer need: prior-model workarounds, over-prescriptive scaffolding, bare prohibitions, reasoning-echo directives, stale examples — plus instructions that misstate Claude Code's own behavior, cite a file in a form that never loads, or re-read a surface already in context. Report-only: emits a findings report with proposed diffs, gated to the human, never auto-applied. Use when: 'after a model upgrade', 'are my instructions holding the model back', 'instructions the model no longer needs', 'too prescriptive', 'audit instructions', 'instruction audit', 'stale Claude Code behavior', 'outdated harness claim', 'my @path import is not loading', 'instruction re-reads CLAUDE.md'. Not a brevity pass and not memory-layer hygiene." argument-hint: "[scope] — scope: claude-md|rules|skills|agents|hooks|output-styles|all (default: all)" user-invocable: true disable-model-invocation: false diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index 6ddd425d7..f27df76bc 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -204,13 +204,19 @@ Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surfaces: non-memory only (skill bodies and their reference files, agent definitions, prompt-type hooks, output styles). -- **Detect:** an `@path` written outside backticks and outside a fenced block on a surface where - `@` carries no import meaning, in a sentence that treats it as though the file arrives. Import - syntax is a property of the CLAUDE.md family; a skill's supporting files are reached by being - named so Claude knows when to read them, so an `@` there is inert text and its content silently - never arrives. +- **Detect:** an `@path` written outside backticks and outside a fenced block on a surface where `@` + carries no import meaning, **in prose that asserts the file has already arrived** — "as specified + in @reference/rules.md above", "the criteria in @reference/criteria.md are loaded", a claim that + the content is present rather than an instruction to go get it. Import syntax is a property of the + CLAUDE.md family; on a skill or agent surface the `@` is inert, so an instruction written on the + assumption that it imported is describing a load that did not happen. - **Remediate:** cite the file the way that surface actually resolves — a backticked path or a markdown link the reader and the model can both follow. +- **Must NOT flag: an `@path` the surrounding prose treats as a file to read.** The path is still + legible in the loaded prompt, so "follow `@reference/rules.md`" works — the reader opens it, the + inert prefix costs one character. **The finding is the false assumption of automatic loading, not + the citation form**, and a warning on every inert `@` would flag working instructions. When the + prose does not say the content already arrived, leave it. - **Must NOT flag:** anything on a memory-layer surface, where `@path` genuinely imports. A package scope (`@anthropic-ai/…`), a decorator, an email address, or a `@username` handle. A backticked `` `@path` ``, which the import parser skips by design and which is the documented From 90ac21f9239e5acc7a23574353ca0448e86b73c8 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 18:49:34 -0400 Subject: [PATCH 6/6] fix(claude-config): bound each new check so it cannot manufacture findings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five review findings, all cases where a row was broader than the evidence supporting it. I12's reproduction arm matched only the version, so replaying a claim that is conditional on OS, a setting, an account tier, a feature flag or launch mode could fail for the wrong reason and be read as drift. It now requires every stated precondition to match, and treats a failure without them as inconclusive. I13's remediation changed the citation syntax while leaving the false assertion in place. Neither a backticked path nor a markdown link imports anything either, so the agent could still proceed without the content. The remediation now rewrites the assertion into an explicit read. I14 hardcoded ~/.claude/CLAUDE.md, but CLAUDE_CONFIG_DIR moves the whole config tree — the hardcoded path flags a read that is now necessary and misses the redundant read of the configured one. It resolves the variable, matching what Phase A already does. It also exempts any read where the file is the operation's subject: the startup copy is a launch-time snapshot, so cutting a pre-edit read patches stale text. The surface partition claimed the full catalog applies on non-memory surfaces while I13 and I14 declare narrower sets, so a lane could emit I14 findings on hooks and output styles the row excludes. Each row's own declaration now bounds it. The changelog entry is restructured to describe the checks as they ship rather than as a sequence of corrections to them. --- plugins/claude-config/CHANGELOG.md | 51 ++++++++++--------- .../skills/audit-instructions/SKILL.md | 4 +- .../audit-instructions/reference/criteria.md | 48 ++++++++++------- 3 files changed, 60 insertions(+), 43 deletions(-) diff --git a/plugins/claude-config/CHANGELOG.md b/plugins/claude-config/CHANGELOG.md index c48af9668..3c59beab5 100644 --- a/plugins/claude-config/CHANGELOG.md +++ b/plugins/claude-config/CHANGELOG.md @@ -8,36 +8,39 @@ All notable changes to the `claude-config` plugin are documented here. Format fo ### Added - **`audit-instructions` checks I12–I14**, extending the existing `reference/criteria.md` catalog - rather than standing up a second one. I12 flags an instruction asserting a Claude Code *harness* - behavior that the current official page contradicts — the product, not the model, which is what - separates it from I8. I13 flags prose written on the assumption that an `@path` imported on a - surface where `@` carries no import meaning. I14 flags an instruction telling a subagent to read a - surface the main conversation loads at startup and therefore already carries. Each row carries its - must-not-flag cases, and the three new official sources (CLI reference, subagents, skills) join the - catalog's source list. + rather than standing up a second one. Each row carries its must-not-flag cases, and the three new + official sources (CLI reference, subagents, skills) join the catalog's source list. +- **I12 — stale or misattributed harness-capability claim.** The subject is the product, not the + model, which separates it from I8. Detection needs an official page stating something incompatible + with the claim, or a failed reproduction — and each arm is bounded so the check cannot manufacture + findings. **Documentation silence is not drift**: pages are rewritten and condensed, and this + repository keeps empirical tests for behaviors the docs never specified. **A reproduction must + match every stated precondition** — version, OS, setting, account tier, feature flag, launch mode — + and a failure without them is inconclusive rather than a finding. +- **I13 — prose written on the assumption that an `@path` imported**, on a surface where `@` carries + no import meaning. The finding is the false premise, not the citation form: an inert `@path` is + still a legible path, so "follow `@reference/rules.md`" works and flagging it would report a + working instruction. Remediation rewrites the assertion into an explicit read, because swapping the + syntax alone leaves the claim false — no citation form imports anything on these surfaces. +- **I14 — an instruction to read a surface the main conversation already loads at startup.** Bounded + to the root `CLAUDE.md`, the user `CLAUDE.md` at the **resolved** `${CLAUDE_CONFIG_DIR:-~/.claude}`, + the root `CLAUDE.local.md`, unconditional project rules and managed policy files. Nested + `CLAUDE.md` and `CLAUDE.local.md` files and path-scoped rules load lazily and are exempt, as is any + read where **the file is the operation's subject** — the startup copy is a launch-time snapshot, so + cutting a pre-edit read produces a patch against stale content. ### Changed -- **Discovery vocabulary for the three new checks.** The `description` framed the skill purely as - finding instructions the model no longer needs, so a request about a stale harness claim, a - non-loading `@path`, or a redundant startup-surface read would not select it — and only the - description is available during selection. It now names those three shapes and carries their - trigger phrases. -- **I13 fires on the false assumption, not the citation form.** An inert `@path` on a skill surface - is still a legible path, so "follow `@reference/rules.md`" works and warning on it would flag a - working instruction. Detection now requires prose asserting the file has already arrived. - **Recheck triggers now watch every page in the catalog's source list**, not the three originally named. Each check cites one of those pages, so a subset left the new harness-behavior rows depending on pages nothing watched. -- **I12 no longer treats documentation silence as drift.** Detection now requires an official page - stating something incompatible with the claim, or a failed version-matched reproduction. A page - that stops mentioning a behavior is not evidence the behavior changed — pages are routinely - rewritten and condensed, and this repository keeps empirical tests for behaviors the docs never - specified at all. -- **I14 is bounded to the surfaces actually loaded at startup.** The subagent guarantee it rests on - covers the hierarchy *the main conversation loads*; nested `CLAUDE.md` files and path-scoped rules - load lazily when work reaches their scope, so an instruction to read a package-local file before - operating there can be doing real work. Flagging it would have removed scoped instructions. +- **The surface partition no longer widens a row.** It said the full catalog applies on non-memory + surfaces while I13 and I14 declare narrower surface sets, so a lane could emit I14 findings on + prompt-type hooks and output styles the criterion excludes. Each row's own declaration bounds it. +- **The `description` carries the new checks' trigger vocabulary.** It framed the skill purely as + finding instructions the model no longer needs, and only the description is available during skill + selection — so a request about a stale harness claim, a non-loading `@path`, or a redundant + startup-surface read would not have selected the catalog that answers it. - **`Authority` gloss restated descriptively.** It now reads "All fourteen checks are currently `ANTHROPIC-DOCS`" — a statement about the catalog's present contents, not a rule. `TALK` and `OPINION` stay reachable for a future row, and the axis stays a closed three-value set rather than diff --git a/plugins/claude-config/skills/audit-instructions/SKILL.md b/plugins/claude-config/skills/audit-instructions/SKILL.md index c64783fff..8cec11a74 100644 --- a/plugins/claude-config/skills/audit-instructions/SKILL.md +++ b/plugins/claude-config/skills/audit-instructions/SKILL.md @@ -47,7 +47,9 @@ one-line pointer to the official CLAUDE.md include/exclude guidance (recorded wi [reference/criteria.md](reference/criteria.md)) so the operator knows where that audit lives — this skill still does not perform it. Either way, no I1–I5 hygiene finding is ever produced here. On **non-memory surfaces** (skill bodies, agent definitions, prompt-type hooks, output styles) the -full catalog I1–I14 applies — no incumbent auditor covers instruction content there. +catalog applies — no incumbent auditor covers instruction content there — **bounded by each row's +own surface declaration**, which is narrower than the partition for some checks. I13 and I14 name +their own surface sets and are not run outside them; this partition never widens a row. **Upstream-owned surfaces are excluded from the editable set.** Installed plugin-cache content is owned by the publishing repository, and a managed materialization is owned by whatever upstream diff --git a/plugins/claude-config/skills/audit-instructions/reference/criteria.md b/plugins/claude-config/skills/audit-instructions/reference/criteria.md index f27df76bc..ae127bce9 100644 --- a/plugins/claude-config/skills/audit-instructions/reference/criteria.md +++ b/plugins/claude-config/skills/audit-instructions/reference/criteria.md @@ -173,7 +173,7 @@ Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface - **Detect:** an instruction that asserts a Claude Code *harness* behavior — what a command does, what a keystroke saves, what loads into which context window, what a mode persists — where **either** the official documentation **for the version the claim is about** states something - incompatible with it, **or** a version-matched reproduction of the asserted behavior fails. The + incompatible with it, **or** a reproduction matching **every** stated precondition fails. The subject is the product, not the model, which is what separates this from I8. - **Remediate:** correct the claim against the cited page, or cut it and point at the page instead of restating it. Where the behavior is version-gated, carry the minimum version with the claim. @@ -182,14 +182,16 @@ Tier `behavioral` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface repository deliberately keeps empirical smoke tests for behaviors the official pages never specified at all. Absence of documentation raises the claim for reproduction; it does not establish drift, and it never on its own justifies a removal. -- **Must NOT flag: a version-gated claim that still reproduces on its own version.** Match the - version before matching the text. A claim scoped to a pinned or supported older release is - measured against that release, not against the latest page, and **a successful version-matched - reproduction settles it** — the latest documentation describing newer behavior is then evidence of - a version difference, not of an inaccurate instruction. A claim carrying no version is about - current behavior and is measured against the current page. This is the mirror of the remediation - above: a catalog that asks authors to carry a minimum version must not then flag the claims that - do. +- **Must NOT flag: a gated claim that still reproduces under its own conditions.** Match the + conditions before matching the text. Version is the common one — a claim scoped to a pinned or + supported older release is measured against that release, not against the latest page — but it is + not the only one: **OS, a setting, an account tier, a feature flag, and launch mode are equally + preconditions**, and a replay under different conditions proves nothing about the instruction. + **A successful matched reproduction settles it**; a failed one settles it only when every stated + precondition was met, and is otherwise **inconclusive rather than a finding**. A claim carrying no + conditions is about current default behavior and is measured against the current page. This is the + mirror of the remediation above: a catalog that asks authors to carry a claim's conditions must not + then flag the claims that do. - **Must NOT flag:** prose that names two adjacent forms and distinguishes them correctly — the terminal `claude doctor` being read-only while the in-session `/doctor` applies fixes is the canonical pair, and a file that states both is right, not drifting. A bare routing pointer that @@ -210,8 +212,12 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `warning` · Surface the content is present rather than an instruction to go get it. Import syntax is a property of the CLAUDE.md family; on a skill or agent surface the `@` is inert, so an instruction written on the assumption that it imported is describing a load that did not happen. -- **Remediate:** cite the file the way that surface actually resolves — a backticked path or a - markdown link the reader and the model can both follow. +- **Remediate:** rewrite the assertion into an explicit read, and cite the file the way that surface + actually resolves — a backticked path or a markdown link. **Changing the citation syntax alone is + not the fix**: neither form imports anything either, so a diff that swaps `@reference/rules.md` for + a backticked path while leaving "as specified above" in place keeps the false claim and still lets + the agent proceed without the content. The false premise is the defect; the syntax is where it + shows. - **Must NOT flag: an `@path` the surrounding prose treats as a file to read.** The path is still legible in the loaded prompt, so "follow `@reference/rules.md`" works — the reader opens it, the inert prefix costs one character. **The finding is the false assumption of automatic loading, not @@ -231,11 +237,14 @@ Tier `mechanical` · Authority `ANTHROPIC-DOCS` · Severity `info` · Surfaces: skill bodies. - **Detect:** an instruction directing the agent to go read a surface the main conversation loads at - startup and therefore already carries — the **root** `CLAUDE.md`, `~/.claude/CLAUDE.md`, the - **root** `CLAUDE.local.md`, unconditional project rules (no `paths` frontmatter), and managed - policy files. Root-level is load-bearing in that list: the startup guarantee is scoped to the - hierarchy discovered from the launch directory, not to every file of that name in the tree. The - read spends a turn to retrieve text that is already present. + startup and therefore already carries — the **root** `CLAUDE.md`, the user `CLAUDE.md` at the + **resolved** `${CLAUDE_CONFIG_DIR:-~/.claude}`, the **root** `CLAUDE.local.md`, unconditional + project rules (no `paths` frontmatter), and managed policy files. Two qualifiers are load-bearing. + Root-level: the startup guarantee is scoped to the hierarchy discovered from the launch directory, + not to every file of that name in the tree. Resolved: `CLAUDE_CONFIG_DIR` moves the whole config + tree, so a hardcoded `~/.claude/CLAUDE.md` both flags a read that is now necessary and misses the + redundant read of the configured path. Phase A resolves this variable already (`SKILL.md:76-78`); + match it. The read spends a turn to retrieve text that is already present. - **Remediate:** cut the retrieval step and state the requirement the read was meant to satisfy. - **Must NOT flag: anything that loads on demand rather than at startup.** The guarantee this check rests on covers the hierarchy *the main conversation loads*, which is not the whole memory family. @@ -247,8 +256,11 @@ skill bodies. established, leave it. - **Must NOT flag:** an instruction to read a surface that is *not* auto-loaded — `AGENTS.md`, contributing guides, ADRs, CI workflow files, per-ecosystem convention docs. Those are ordinary - progressive disclosure. An agent whose job is to audit an instruction surface, which must open - the file because inspecting it is the work rather than obeying it. A rule restated in a + progressive disclosure. **Any read where the file is the operation's subject rather than its + instructions** — auditing it, editing it, patching it, reporting on it, or anything else needing + current disk contents. The startup copy is a snapshot taken at launch; another process can have + changed the file since, and a pre-edit read cut on the grounds that "it is already in context" + produces a patch against stale text. A rule restated in a delegation prompt for the built-in Explore and Plan agents, which are documented as the only subagents that skip `CLAUDE.md` and have no per-agent setting to change that. - **Source:** subagents, "What loads at startup" — a non-fork subagent's initial context contains