Scope instructions: where each piece of guidance lives
The question about a repo's agent guidance is rarely what to write and
usually where. Each home loads on its own trigger and misses in silence:
the guidance is on disk, correct, and never read. The built-ins answer
the other questions. In a trial on 2026-10-15, CLAUDE_CODE_NEW_INIT=1
/init and the claude-md-improver skill each cut derivable lines,
surfaced a README's rule and caught a stale command, and in three runs
neither moved a section out of a root CLAUDE.md into a nested file or
a paths: rule. This skill asks what they skip, of every section:
what event loads its home, and does that event come before the mistake
it guards against?
The homes and how each fails live in one place, the user-scope rule
agent-instructions-scoping.md, which this skill applies and does not
restate. It proposes; files change only on approval, and committing
is commit-changes's.
Past that rule, the live page: code.claude.com by the
claude-code-docs MCP server or
curl -s https://code.claude.com/docs/en/<page>.md, and another
tool's file by that tool's own markdown source, else WebFetch, saying
it read a summary. A live page that contradicts a line here wins: say
so, act on the page, and route the fix by capture-learning, bar a
dated measured line that names the page it overrules and the call that
measured it, which a page changed since its date sends back to re-measure.
An observed claim is cited or marked pending a doc check, and stands, marked
observed, only where no page covers it.
0. Whose guidance
git rev-parse --show-toplevel
- This repo's project-scope files only:
CLAUDE.md, AGENTS.md and
CLAUDE.local.md at any depth, .claude/CLAUDE.md, .claude/rules/,
and other tools' files. A CLAUDE.local.md is one person's: propose
for it, never move another person's lines out of it.
- User scope is not this skill's. A section that belongs in every
repo on the machine, in
~/.claude/, is a capture-learning
learning: name it in the proposal and leave it.
- The repo's own conventions about its instruction files outrank the
table: a cap on root's length, a lint, a ban on nested files. Look
for them in root and
CONTRIBUTING.md first.
- An argument narrows the run to that file, or to that folder and
the files whose guidance is about it.
1. Read every instruction file, here, with Read
Glob for the set, then Read each file with the Read tool, in this
context:
CLAUDE.md, CLAUDE.local.md and AGENTS.md at any depth, and
.claude/CLAUDE.md
.claude/rules/**/*.md
.github/copilot-instructions.md and
.github/instructions/**/*.instructions.md
GEMINI.md, .cursor/rules/, .windsurfrules, .clinerules
- each folder's
README.md, since a must-know line can hide in one
Never through a subagent, and never in a compound Bash command. Both
are how the trial's built-ins lost the rule. A subagent's Read loads a
nested file or rule into the subagent only, so /init, which hands its
exploring to one, wrote its proposal in a context that held none. A
loop, a pipe or a cat of several files loads nothing, which is how the
improver read. A single-file cat or head loads as a Read does since
2.1.293, but Read is the route that loads on every version.
Then check the rule is in context. The first Read of a CLAUDE.md,
AGENTS.md or rule loads agent-instructions-scoping.md by its glob:
its table headed "Guidance is…" should now be in context. If it is not,
Read it directly from the rules/ folder of the user's config
directory, CLAUDE_CONFIG_DIR or else ~/.claude, or cat that one
file if Read refuses a path outside the working directory. A
project-scope copy of the same name supersedes it; then that one is the
table. With neither, say so: the user's config holds no scoping
rule, so weigh each home by the load events below, and name that the
proposal stands on them alone.
For each file, note its length and when it loads: root and every
ancestor at launch, a nested file at the session's first Read, Write or
Edit in its folder, a rule with paths: on a match and one without at
launch, an @path import at launch with its parent.
Find the silent files. Claude Code reads an AGENTS.md only when no
CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md sits in the working
directory or above it, so a root CLAUDE.md silences every AGENTS.md
in the repo, nested ones included. One that claudeMdExcludes skips does
not count. A silent file's unique lines are guidance no Claude session
has read.
Then read what already enforces guidance, which no instruction file
lists: .claude/settings.json and settings.local.json (permissions
and hooks), the git hooks (git config core.hooksPath, else
.git/hooks, and .pre-commit-config.yaml) and any CI job that fails a
guarded change. A line a guard already holds answers step 4's question
5 with evidence, for Claude; Copilot reads no .claude/settings.json,
so for it the line may still be needed (one client repo, 2026-10-26,
where a deny rule, a hook and a git hook moved three rows).
2. Who reads them
git shortlog -sne HEAD for who commits. One author means the user
alone: design for their tools, not for teammates.
- The tools come from the files found in step 1. The rule says what
Codex, Copilot and GitHub.com's Copilot agent read. For Cursor,
Windsurf, Cline and Gemini CLI this skill says nothing of when their
files load: keep them, and flag a fact they hold apart.
- Ask the user only about readers who never commit.
3. Measure the sessions
uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/folder-sessions.py
Run it from the repo, or from one of its worktrees. Per folder it prints
how many past sessions Read, Wrote or Edited there and how many edited;
whether each opened the folder's README first, later or
never, and how many of the first were named in a prompt; which
nested files and rules loaded on calls there; and how many of those
sessions compacted. --folder <path> narrows it, --depth, --min and
--limit shape it, --json is for parsing.
- A README is the agent's choice to open; a nested file or a rule is
not. Many
never beside many sessions is the evidence that the
folder's must-know lines belong in a rule or a nested file.
loaded shows what already reaches the folder's work, so a move
there may be into a home that exists. A home that loads covers a
README only for the lines it holds: check the README's must-know lines
against it before calling the folder covered.
compacted counts sessions that lost them for a while: after
/compact, root returns at once while nested files and paths: rules
return only at the next matching Read, Write or Edit.
- The last lines give the reach: the oldest transcript, which
cleanupPeriodDays bounds (30 days by default), the versions seen, and
the loads it could pin to no folder, by what they followed.
- Misses are an upper bound. Only Read, Write and Edit count as work
in a folder, so a README viewed by
cat reads as never opened, and an
edit made through Bash is not seen. A folder with under five sessions
is an anecdote; say so.
- Exit 1, no session ran here: sort on content alone and say so.
Exit 2, the transcript format moved: report it, and do not grep the
transcripts by hand as a stand-in.
4. Sort each section
Every ## section of a root file gets one home, and so does each part
of any other file the rule's sizes flag: root past about 200 lines, a
nested file past about 60. Ask in order, and stop at the first yes:
- Does a live command or a sync trigger the mistake? No file touch
comes before it, so no rule or nested file can: it stays in root. In
a client Fabric repo's hand trim, 4 of 15 silent-failure gotchas
stayed for exactly this reason (2026-09-29).
- Is it about one directory's work? A nested file there, or a
paths: rule on that folder: a nested file where the folder's owners
keep their own conventions with the code, a rule where all
conventions are kept in one place (the large-codebases docs' split).
On Windows, prefer the paths: rule either way: a nested file misses
every Read, Write or Edit whose drive letter is cased unlike the
launch directory's, and a rule loads on both (the drive-letter bullet
of agent-instructions-scoping.md).
A section that also governs files outside the folder is split, each
line going where the files it governs are touched.
- Is it about one kind of file, wherever it sits? A
paths: rule
globbed on that kind, **/*.sql and not *.sql, which matches the
repo root only.
- Is it a procedure someone asks for in words? A skill.
- Must it hold before the agent acts? A hook or a
permissions.deny rule.
- Is it long reference for people? A README, its must-know lines
going by this same list.
- Can it be derived from the code? Nowhere: what a formatter
config, a linter or the layout already says.
/doctor's checkup cuts
the same.
- Otherwise, root.
In the same pass:
- The other direction. A README's must-know lines and a silent
file's unique lines move to where a session will load them. A silent
root
AGENTS.md becomes the import form, @AGENTS.md at the top of
the CLAUDE.md, never a copy, which leaves two homes to drift.
- A home the agent opens by choice, a README, a script's header or
its
-h, guards a mistake only when a home that loads before the
mistake sends the agent there. Propose that pointer in the same row,
or leave the line where it loads; a pointer that fires only for a
guess misses the session that already knows the command.
- One fact, one home across tools. Where Copilot's file and the
CLAUDE.md disagree, say on a line length the formatter config
settles, the config wins and the duplicates go; shared long form
sits in one doc that each tool's file points at, by code span in
Copilot's (the rule's import-form conditions).
- Stale lines. Check each command, make target, script and path a
section names against the repo (
Makefile, package.json, the disk)
and flag what is missing. A full pass for staleness, contradiction and
prompting written for older models is /doctor prompt-audit's, from
2.1.283: name it rather than redo it.
- Memory, the session's own. An auto-memory index loads at launch
as root does, so a memory that contradicts an instruction file or the
repo, as one saying where guidance goes, is a row like any other:
proposed, never corrected in passing. One recording a placement the
user approved, a line kept in root on a probe's evidence, binds its row
as a decision does: grep the memory directory for
CLAUDE.md,
AGENTS.md and "keep" (a draft that moved such a line out, 2026-10-26).
- A nested file's name follows the rule's table:
CLAUDE.md under a
root CLAUDE.md, AGENTS.md under a bare root AGENTS.md, and under
the import form a CLAUDE.md importing a sibling AGENTS.md where
other tools need it.
5. Where a new file never goes
- Inside a Fabric item folder (
<name>.<ItemType>/): untested
against Git sync. A markdown file at a workspace's sync root coexists.
- Under
.claude/, except .claude/rules/: .claude/CLAUDE.md is
the project file's second home, loaded at launch beside a root one.
- In a folder copied elsewhere, such as a skill's or a template's:
the file travels with every copy.
- At or above test fixtures or samples: an instruction file there is
live, and loads on a Read like any other.
- Never a bare
AGENTS.md in place of a root CLAUDE.md: the rule
lists five things it loses, each silently.
- No
claudeMdExcludes or instructionFiles change unasked.
instructionFiles is read only from user, managed and --settings
files, so a repo cannot set it for its readers. A committed exclude
travels into every worktree, and **/.claude/worktrees/** strips a
worktree session's own root CLAUDE.md (probed 2026-09-27, held on
2.1.293 on 2026-10-15).
6. Propose
One table, a row for every section, moved or kept:
| Section |
Now |
Proposed home |
Loads when |
Evidence |
Under it: each new file's full text, root's line count before and
after, the silent files and what becomes of them, the stale lines
flagged, and what goes to capture-learning, to /doctor (trimming
derivable lines from a file that stays) or to /doctor prompt-audit
(stale and contradicting lines). Then stop.
The user approves rows, not the table: some may go and some stay.
7. Apply what was approved
Exactly the approved rows. A section moves; it is not copied. Its
old text leaves in the same edit, or two homes start to drift.
Prove a new nested file or rule loads, in a session that did not
write it. This session wrote it, so it is in context already and
never arrives as a nested load here. The docs' own test is a fresh
session reading a file in that folder. Offer a cold probe, which costs
cents, and run it only on a yes. It drops this session's CLAUDE*
variables first, as this machine's loader probes do, so that it starts
as a session of its own rather than a child of this one. On Windows,
name the file by its absolute path, its drive letter in upper case.
Git Bash starts the probe on an upper-case drive, C:\ and not
c:\ (2026-10-15), and a nested file loads only on a path whose
drive letter is cased as the launch directory's (the rule), so a
c:\ path copied from elsewhere misses a file that is in place.
( for v in $(compgen -e | grep -E '^(CLAUDE|MCP_CONNECTION_NONBLOCKING)'); do unset "$v"; done
claude -p "Read <a file in that folder>, then reply done" -n "probe: scope-instructions" --model haiku --tools Read --strict-mcp-config )
uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/folder-sessions.py --probes --folder <that folder> --min 1
The new file listed under loaded is the proof. Its absence, with the
file in place and the path so spelled, means a glob or a name is
wrong.
Hand off to commit-changes. The repo's own checks run there.
Constraints
- Proposes first. Nothing changes before the user approves a row,
this session's own auto-memory included.
- Reads in its own context, with Read, never through a subagent or
a compound Bash command.
- Edits no user-scope file; those learnings are
capture-learning's.
- Removes no guidance without its new home in the same change.
- The repo's conventions win over the table.
- A client's evidence stays in that repo. Folder names and session
counts belong in that repo's files, never in another repo's.
- Not this skill: a first
CLAUDE.md for a repo with none is
/init's; trimming a well-placed file of derivable lines is
/doctor's; staleness and contradiction are /doctor prompt-audit's;
how the loader behaves is capture-learning's.
1---2name: scope-instructions3model: inherit4effort: xhigh5disable-model-invocation: false6argument-hint: "[file-or-folder]"7allowed-tools: Read Grep Glob Bash(git rev-parse *) Bash(git ls-files *) Bash(git shortlog *) Bash(git log *) Bash(uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/folder-sessions.py *)8description: "Sorts a repo's agent instructions into the homes that load them when they are needed. Weighs each section of a root CLAUDE.md or AGENTS.md, each folder README's must-know lines and each file another coding tool reads against root, a paths: rule, a nested CLAUDE.md or AGENTS.md, a skill, a hook, a README or nowhere, by the event that loads each home and whether that event comes before the mistake. Reads every instruction file itself, in its own context, so the scoping rule loads where the proposal is written. Measures the repo's own session transcripts per folder with a bundled script: who worked there, whether they opened its README first, which nested files and rules loaded, how often they compacted. Finds an AGENTS.md a CLAUDE.md silences and a fact two tools' files hold apart. Proposes every move in one table and edits only on approval. Where /init and /doctor refresh and trim a root file, this moves what does not belong there."9when_to_use: "Use when asked where a piece of guidance should live, whether a repo or folder needs a nested CLAUDE.md or AGENTS.md, to split, slim or reorganize a CLAUDE.md, to move instructions into .claude/rules/, to audit instruction files across Claude, Copilot and other tools, or why a folder's README or an AGENTS.md is never read. A learning about how Claude Code loads these files is capture-learning's, into its user-scope rule."10metadata:11 source: https://skillmd.com/skills/wardawgmalvicious/scope-instructions12---1314# Scope instructions: where each piece of guidance lives1516The question about a repo's agent guidance is rarely what to write and17usually where. Each home loads on its own trigger and misses in silence:18the guidance is on disk, correct, and never read. The built-ins answer19the other questions. In a trial on 2026-10-15, `CLAUDE_CODE_NEW_INIT=1`20`/init` and the `claude-md-improver` skill each cut derivable lines,21surfaced a README's rule and caught a stale command, and in three runs22neither moved a section out of a root `CLAUDE.md` into a nested file or23a `paths:` rule. This skill asks what they skip, of every section:24**what event loads its home, and does that event come before the mistake25it guards against?**2627The homes and how each fails live in one place, the user-scope rule28`agent-instructions-scoping.md`, which this skill applies and does not29restate. It **proposes**; files change only on approval, and committing30is `commit-changes`'s.3132Past that rule, the live page: code.claude.com by the33`claude-code-docs` MCP server or34`curl -s https://code.claude.com/docs/en/<page>.md`, and another35tool's file by that tool's own markdown source, else `WebFetch`, saying36it read a summary. A live page that contradicts a line here wins: say37so, act on the page, and route the fix by `capture-learning`, bar a38dated measured line that names the page it overrules and the call that39measured it, which a page changed since its date sends back to re-measure.40An observed claim is cited or marked pending a doc check, and stands, marked41observed, only where no page covers it.4243## 0. Whose guidance4445```bash46git rev-parse --show-toplevel47```4849- **This repo's project-scope files only**: `CLAUDE.md`, `AGENTS.md` and50 `CLAUDE.local.md` at any depth, `.claude/CLAUDE.md`, `.claude/rules/`,51 and other tools' files. A `CLAUDE.local.md` is one person's: propose52 for it, never move another person's lines out of it.53- **User scope is not this skill's.** A section that belongs in every54 repo on the machine, in `~/.claude/`, is a `capture-learning`55 learning: name it in the proposal and leave it.56- **The repo's own conventions about its instruction files outrank the57 table**: a cap on root's length, a lint, a ban on nested files. Look58 for them in root and `CONTRIBUTING.md` first.59- **An argument narrows the run** to that file, or to that folder and60 the files whose guidance is about it.6162## 1. Read every instruction file, here, with Read6364Glob for the set, then Read each file with the Read tool, in this65context:6667- `CLAUDE.md`, `CLAUDE.local.md` and `AGENTS.md` at any depth, and68 `.claude/CLAUDE.md`69- `.claude/rules/**/*.md`70- `.github/copilot-instructions.md` and71 `.github/instructions/**/*.instructions.md`72- `GEMINI.md`, `.cursor/rules/`, `.windsurfrules`, `.clinerules`73- each folder's `README.md`, since a must-know line can hide in one7475**Never through a subagent, and never in a compound Bash command.** Both76are how the trial's built-ins lost the rule. A subagent's Read loads a77nested file or rule into the subagent only, so `/init`, which hands its78exploring to one, wrote its proposal in a context that held none. A79loop, a pipe or a `cat` of several files loads nothing, which is how the80improver read. A single-file `cat` or `head` loads as a Read does since812.1.293, but Read is the route that loads on every version.8283**Then check the rule is in context.** The first Read of a `CLAUDE.md`,84`AGENTS.md` or rule loads `agent-instructions-scoping.md` by its glob:85its table headed "Guidance is…" should now be in context. If it is not,86Read it directly from the `rules/` folder of the user's config87directory, `CLAUDE_CONFIG_DIR` or else `~/.claude`, or `cat` that one88file if Read refuses a path outside the working directory. A89project-scope copy of the same name supersedes it; then that one is the90table. **With neither, say so**: the user's config holds no scoping91rule, so weigh each home by the load events below, and name that the92proposal stands on them alone.9394For each file, note its length and when it loads: root and every95ancestor at launch, a nested file at the session's first Read, Write or96Edit in its folder, a rule with `paths:` on a match and one without at97launch, an `@path` import at launch with its parent.9899**Find the silent files.** Claude Code reads an `AGENTS.md` only when no100`CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` sits in the working101directory or above it, so a root `CLAUDE.md` silences every `AGENTS.md`102in the repo, nested ones included. One that `claudeMdExcludes` skips does103not count. A silent file's unique lines are guidance no Claude session104has read.105106**Then read what already enforces guidance**, which no instruction file107lists: `.claude/settings.json` and `settings.local.json` (`permissions`108and `hooks`), the git hooks (`git config core.hooksPath`, else109`.git/hooks`, and `.pre-commit-config.yaml`) and any CI job that fails a110guarded change. A line a guard already holds answers step 4's question1115 with evidence, for Claude; Copilot reads no `.claude/settings.json`,112so for it the line may still be needed (one client repo, 2026-10-26,113where a deny rule, a hook and a git hook moved three rows).114115## 2. Who reads them116117- `git shortlog -sne HEAD` for who commits. One author means the user118 alone: design for their tools, not for teammates.119- **The tools come from the files found in step 1**. The rule says what120 Codex, Copilot and GitHub.com's Copilot agent read. For Cursor,121 Windsurf, Cline and Gemini CLI this skill says nothing of when their122 files load: keep them, and flag a fact they hold apart.123- Ask the user only about readers who never commit.124125## 3. Measure the sessions126127```bash128uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/folder-sessions.py129```130131Run it from the repo, or from one of its worktrees. Per folder it prints132how many past sessions Read, Wrote or Edited there and how many edited;133whether each opened the folder's README **first**, **later** or134**never**, and how many of the first were named in a prompt; which135nested files and rules **loaded** on calls there; and how many of those136sessions compacted. `--folder <path>` narrows it, `--depth`, `--min` and137`--limit` shape it, `--json` is for parsing.138139- **A README is the agent's choice to open; a nested file or a rule is140 not.** Many `never` beside many sessions is the evidence that the141 folder's must-know lines belong in a rule or a nested file.142- **`loaded` shows what already reaches the folder's work**, so a move143 there may be into a home that exists. A home that loads covers a144 README only for the lines it holds: check the README's must-know lines145 against it before calling the folder covered.146- **`compacted` counts sessions that lost them for a while**: after147 `/compact`, root returns at once while nested files and `paths:` rules148 return only at the next matching Read, Write or Edit.149- **The last lines give the reach**: the oldest transcript, which150 `cleanupPeriodDays` bounds (30 days by default), the versions seen, and151 the loads it could pin to no folder, by what they followed.152- **Misses are an upper bound.** Only Read, Write and Edit count as work153 in a folder, so a README viewed by `cat` reads as never opened, and an154 edit made through Bash is not seen. A folder with under five sessions155 is an anecdote; say so.156- **Exit 1**, no session ran here: sort on content alone and say so.157 **Exit 2**, the transcript format moved: report it, and do not grep the158 transcripts by hand as a stand-in.159160## 4. Sort each section161162Every `##` section of a root file gets one home, and so does each part163of any other file the rule's sizes flag: root past about 200 lines, a164nested file past about 60. Ask in order, and stop at the first yes:1651661. **Does a live command or a sync trigger the mistake?** No file touch167 comes before it, so no rule or nested file can: it stays in root. In168 a client Fabric repo's hand trim, 4 of 15 silent-failure gotchas169 stayed for exactly this reason (2026-09-29).1702. **Is it about one directory's work?** A nested file there, or a171 `paths:` rule on that folder: a nested file where the folder's owners172 keep their own conventions with the code, a rule where all173 conventions are kept in one place (the large-codebases docs' split).174 On Windows, prefer the `paths:` rule either way: a nested file misses175 every Read, Write or Edit whose drive letter is cased unlike the176 launch directory's, and a rule loads on both (the drive-letter bullet177 of `agent-instructions-scoping.md`).178 A section that also governs files outside the folder is split, each179 line going where the files it governs are touched.1803. **Is it about one kind of file, wherever it sits?** A `paths:` rule181 globbed on that kind, `**/*.sql` and not `*.sql`, which matches the182 repo root only.1834. **Is it a procedure someone asks for in words?** A skill.1845. **Must it hold before the agent acts?** A hook or a185 `permissions.deny` rule.1866. **Is it long reference for people?** A README, its must-know lines187 going by this same list.1887. **Can it be derived from the code?** Nowhere: what a formatter189 config, a linter or the layout already says. `/doctor`'s checkup cuts190 the same.1918. **Otherwise**, root.192193In the same pass:194195- **The other direction.** A README's must-know lines and a silent196 file's unique lines move to where a session will load them. A silent197 root `AGENTS.md` becomes the import form, `@AGENTS.md` at the top of198 the `CLAUDE.md`, never a copy, which leaves two homes to drift.199- **A home the agent opens by choice**, a README, a script's header or200 its `-h`, guards a mistake only when a home that loads before the201 mistake sends the agent there. Propose that pointer in the same row,202 or leave the line where it loads; a pointer that fires only for a203 guess misses the session that already knows the command.204- **One fact, one home across tools.** Where Copilot's file and the205 `CLAUDE.md` disagree, say on a line length the formatter config206 settles, the config wins and the duplicates go; shared long form207 sits in one doc that each tool's file points at, by code span in208 Copilot's (the rule's import-form conditions).209- **Stale lines.** Check each command, make target, script and path a210 section names against the repo (`Makefile`, `package.json`, the disk)211 and flag what is missing. A full pass for staleness, contradiction and212 prompting written for older models is `/doctor prompt-audit`'s, from213 2.1.283: name it rather than redo it.214- **Memory, the session's own.** An auto-memory index loads at launch215 as root does, so a memory that contradicts an instruction file or the216 repo, as one saying where guidance goes, is a row like any other:217 proposed, never corrected in passing. One recording a placement the218 user approved, a line kept in root on a probe's evidence, binds its row219 as a decision does: grep the memory directory for `CLAUDE.md`,220 `AGENTS.md` and "keep" (a draft that moved such a line out, 2026-10-26).221- **A nested file's name** follows the rule's table: `CLAUDE.md` under a222 root `CLAUDE.md`, `AGENTS.md` under a bare root `AGENTS.md`, and under223 the import form a `CLAUDE.md` importing a sibling `AGENTS.md` where224 other tools need it.225226## 5. Where a new file never goes227228- **Inside a Fabric item folder** (`<name>.<ItemType>/`): untested229 against Git sync. A markdown file at a workspace's sync root coexists.230- **Under `.claude/`**, except `.claude/rules/`: `.claude/CLAUDE.md` is231 the project file's second home, loaded at launch beside a root one.232- **In a folder copied elsewhere**, such as a skill's or a template's:233 the file travels with every copy.234- **At or above test fixtures or samples**: an instruction file there is235 live, and loads on a Read like any other.236- **Never a bare `AGENTS.md` in place of a root `CLAUDE.md`**: the rule237 lists five things it loses, each silently.238- **No `claudeMdExcludes` or `instructionFiles` change unasked.**239 `instructionFiles` is read only from user, managed and `--settings`240 files, so a repo cannot set it for its readers. A committed exclude241 travels into every worktree, and `**/.claude/worktrees/**` strips a242 worktree session's own root `CLAUDE.md` (probed 2026-09-27, held on243 2.1.293 on 2026-10-15).244245## 6. Propose246247One table, a row for every section, moved or kept:248249| Section | Now | Proposed home | Loads when | Evidence |250| --- | --- | --- | --- | --- |251252Under it: each new file's full text, root's line count before and253after, the silent files and what becomes of them, the stale lines254flagged, and what goes to `capture-learning`, to `/doctor` (trimming255derivable lines from a file that stays) or to `/doctor prompt-audit`256(stale and contradicting lines). Then stop.257The user approves rows, not the table: some may go and some stay.258259## 7. Apply what was approved260261- **Exactly the approved rows.** A section moves; it is not copied. Its262 old text leaves in the same edit, or two homes start to drift.263- **Prove a new nested file or rule loads, in a session that did not264 write it.** This session wrote it, so it is in context already and265 never arrives as a nested load here. The docs' own test is a fresh266 session reading a file in that folder. Offer a cold probe, which costs267 cents, and run it only on a yes. It drops this session's `CLAUDE*`268 variables first, as this machine's loader probes do, so that it starts269 as a session of its own rather than a child of this one. On Windows,270 name the file by its absolute path, its drive letter in upper case.271 Git Bash starts the probe on an upper-case drive, `C:\` and not272 `c:\` (2026-10-15), and a nested file loads only on a path whose273 drive letter is cased as the launch directory's (the rule), so a274 `c:\` path copied from elsewhere misses a file that is in place.275276 ```bash277 ( for v in $(compgen -e | grep -E '^(CLAUDE|MCP_CONNECTION_NONBLOCKING)'); do unset "$v"; done278 claude -p "Read <a file in that folder>, then reply done" -n "probe: scope-instructions" --model haiku --tools Read --strict-mcp-config )279 uv run --no-project ${CLAUDE_SKILL_DIR}/scripts/folder-sessions.py --probes --folder <that folder> --min 1280 ```281282 The new file listed under `loaded` is the proof. Its absence, with the283 file in place and the path so spelled, means a glob or a name is284 wrong.285- **Hand off to `commit-changes`.** The repo's own checks run there.286287## Constraints288289- **Proposes first.** Nothing changes before the user approves a row,290 this session's own auto-memory included.291- **Reads in its own context, with Read**, never through a subagent or292 a compound Bash command.293- **Edits no user-scope file**; those learnings are `capture-learning`'s.294- **Removes no guidance without its new home in the same change.**295- **The repo's conventions win** over the table.296- **A client's evidence stays in that repo.** Folder names and session297 counts belong in that repo's files, never in another repo's.298- **Not this skill**: a first `CLAUDE.md` for a repo with none is299 `/init`'s; trimming a well-placed file of derivable lines is300 `/doctor`'s; staleness and contradiction are `/doctor prompt-audit`'s;301 how the loader behaves is `capture-learning`'s.