git:20260523.7ad65ae to git:20260523.c579973

60 added, 27 removed. Audit B to B.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: context-file-tuneup
description:
Audit, rewrite, and tighten a CLAUDE.md / AGENTS.md file so it actually helps
- a coding agent instead of bloating its context. Use this skill whenever the
- user wants to review, clean up, fix, shrink, restructure, or improve a
- CLAUDE.md / AGENTS.md file
+ a coding agent instead of bloating its context. Handles repos that use either
+ file name, both names, nested AGENTS.md files, or one file symlinked/aliased
+ to the other. Use this skill whenever the user wants to review, clean up, fix,
+ shrink, restructure, or improve a CLAUDE.md / AGENTS.md file
---
# Context File Tune-up
- A `CLAUDE.md` or `AGENTS.md` file is loaded into the agent's context on every
- task. That makes it the highest-leverage and most-abused file in a repo: a good
- one silently prevents whole classes of mistakes; a bloated or vague one wastes
- the context budget and gets ignored. This skill audits an existing CLAUDE.md /
- AGENTS.md against a known-good structure, derives what it _should_ contain by
- inspecting the repo, proposes a full rewrite, and applies it only after the user
- confirms.
+ A `CLAUDE.md` or `AGENTS.md` file is loaded into an agent's context on every
+ task. Different agents and repos use different filenames, and some repos keep
+ one as a symlink or compatibility alias to the other. Treat them as the same
+ class of file: high-leverage repo instructions for coding agents. A good one
+ silently prevents whole classes of mistakes; a bloated or vague one wastes the
+ context budget and gets ignored. This skill audits the target context file
+ against a known-good structure, derives what it _should_ contain by inspecting
+ the repo, proposes a full rewrite, and applies it only after the user confirms.
The core loop is **inspect → audit → propose → confirm → apply**. Never skip the
confirm step — this file encodes human judgment about a codebase, so the user
gets the final say before anything is written.
## What "good" looks like
Internalize this target before auditing anything. A great context file is
**short, specific, and verifiable**. The enemy is generic advice the model
already knows ("write clean code", "follow best practices") — it costs tokens
and teaches nothing.
**Hard length budget: ~300 lines.** If the content genuinely needs more, that is
a signal to extract a `rules/` directory and leave behind a _router_ — a few
lines in the main file telling the agent which rule file to read for which task
(see "The rules-router pattern" below). A 1,000-line CLAUDE.md is worse than
useless; the agent skims it.
**Ideal section order** (omit any section that has nothing real to say — empty
scaffolding is noise):
1. **One-liner** — what the project is and its motivation/direction, in a
sentence or two. Orients everything else.
2. **Non-obvious tooling / settings / version quirks** — the package manager
that isn't the default, the required env var, the Node version that breaks
the build, the lockfile that must not be regenerated.
3. **Concise architectural map** — only what isn't obvious and would otherwise
take reading several files to discover. Where the entry point is, how the
major pieces talk, where the surprising boundary sits. Not a file-by-file
tour.
4. **Rules with verifiable instructions** — each rule should be checkable.
"Parameterize all SQL" not "write safe database code". "Run `pnpm typecheck`
before committing" not "make sure types are correct".
5. **Hard constraints / anti-patterns** — the bright lines. "Never edit files in
`generated/`." "Do not add dependencies without asking." "Never call the prod
API from tests."
6. **Pointers to deeper docs** — link out instead of inlining.
`See docs/deployment.md for the release process.`
7. **Gotchas / tribal knowledge** — the load-bearing weirdness. "The retry logic
looks broken but is intentional — see PR #123." "`utils/legacy.ts` is dead
code we can't delete yet because of X." This is the highest-value,
hardest-to-recover content and almost never lives in the code itself.
A line earns its place only if it changes what the agent does. If removing a
line would not cause a single mistake, it is probably noise.
## Workflow
- ### Step 1 — Locate and read the file
+ ### Step 1 — Locate, classify, and read the target
- Find the target. Check the repo root and common locations: `CLAUDE.md`,
- `.claude/CLAUDE.md`. If the user named a path, use it. If none exists and the
- user wants one, jump to "Creating from scratch".
+ Find the target context file before auditing. If the user named a path, use that
+ path. Otherwise check the repo root and common locations:
- Read the full file. Count its lines — you will reference the number in the
- audit.
+ - `AGENTS.md`
+ - `CLAUDE.md`
+ - `.claude/CLAUDE.md`
+ - nested `AGENTS.md` files when the user is asking about a subproject or
+ directory-specific context
+ When more than one candidate exists, identify the relationship instead of
+ guessing:
+
+ - Run a symlink-aware check such as `ls -l <path>` or `test -L <path>` for each
+ candidate.
+ - If one file is a symlink to the other, treat the real target as the source of
+ truth. Say so in the audit and avoid editing both paths separately.
+ - If both files are regular files, compare their purpose. `AGENTS.md` is often
+ repo-agent routing while `CLAUDE.md` may be Claude-specific compatibility, but
+ do not assume that without reading them.
+ - If a nested `AGENTS.md` applies to the user's requested subdirectory, audit it
+ together with the nearest parent/root context file so the rewrite preserves
+ the routing relationship.
+
+ Read the full target file after resolving symlinks and hierarchy. Count its
+ lines — you will reference the number in the audit. Also note the target type in
+ your audit: `AGENTS.md`, `CLAUDE.md`, nested `AGENTS.md`, symlinked alias, or
+ multiple independent context files.
+
### Step 2 — Inspect the repo for ground truth
Do not audit in a vacuum. Spend a few minutes deriving what the file _should_
contain so you can spot what's missing, stale, or wrong. Cheap, high-signal
things to check:
- **Manifests / lockfiles** — `package.json`, `pyproject.toml`, `Cargo.toml`,
`go.mod`, `Gemfile`. Reveal the real package manager, scripts
(test/lint/build/typecheck), language version, and key dependencies.
- **Tooling config** — `Makefile`, `justfile`, `.tool-versions`, `.nvmrc`, CI
workflows in `.github/workflows/`. CI is gold: it shows the _actually
enforced_ checks, which are the rules worth stating.
- **Structure** — top-level directory layout (2 levels deep is plenty). Identify
the entry point and the major modules.
- **Existing docs** — a `docs/` folder, `README.md`, `CONTRIBUTING.md`. These
are pointer targets, and sometimes content has been duplicated into the
context file that should just be a link.
- **Tribal-knowledge signals** — gotchas usually aren't in the manifest, but
they leave fingerprints in the repo. Grep code comments for markers like
`HACK`, `XXX`, `FIXME`, `do not remove`, `do not edit`, `load-bearing`,
`intentional`, `workaround`, `gotcha`. Skim recent git history
(`git log --oneline -50`) and look for commit messages or PR references that
explain surprising decisions ("revert", "actually needed", "fixes flaky").
These are candidates for the gotchas section — surface them in the audit
rather than inventing gotchas from nothing.
Note discrepancies as you go: scripts the file mentions that don't exist, a Node
version that disagrees with `.nvmrc`, rules that contradict the CI config.
Keep this proportional. A quick scan is the goal, not an exhaustive code review.
If the repo is huge, sample the most relevant areas rather than reading
everything.
### Step 3 — Produce the audit
Present a structured audit before proposing any change. Lead with the headline
numbers, then go section by section. Use this shape:
```
- ## Audit: CLAUDE.md (<N> lines)
+ ## Audit: <context-file-path> (<N> lines)
**Verdict:** <one line — e.g. "Solid bones, ~40% is generic filler, missing the gotchas section.">
+ **Target:** <AGENTS.md / CLAUDE.md / nested AGENTS.md / symlink relationship / multiple files reviewed.>
+
**Length:** <N> lines vs ~300 target. <If over: what to cut or extract.>
**Section coverage:**
- ✅ One-liner — present and clear
- ⚠️ Tooling — mentions pnpm but omits the required NODE_OPTIONS env var (found in CI)
- ❌ Architectural map — absent; the worker/api split would take 4 files to discover
- ⚠️ Rules — present but vague ("write good tests" → unverifiable)
- ❌ Gotchas — absent
**Specific problems:**
1. Lines 12–28: generic advice the model already knows. Cut.
2. Line 34: references `npm run build`, but package.json uses pnpm and the script is `build:prod`. Stale.
3. ...
```
Be concrete and cite line numbers and evidence (especially repo evidence — "CI
runs `ruff check`, but the file says nothing about linting"). Praise what's
good; don't rewrite working sections for the sake of it. The point is signal,
not a full demolition.
### Step 4 — Derive the gotchas section from the repo
Tribal knowledge — the _why_ behind load-bearing weirdness — is the
highest-value content and the hardest to recover. Don't ask the user for it;
derive it from the signals gathered in Step 2 (comment markers, git history, PR
references). For each candidate, write a gotcha note that states the surprising
thing, why it exists, and a pointer to the evidence — e.g. "The retry logic in
`dispatch.ts` swallows the first failure on purpose; see commit a1b2c3d / PR
#123."
If the repo yields no real tribal-knowledge signal, leave the gotchas section
out entirely rather than padding it with guesses. An empty section is worse than
no section. (If the user volunteers a gotcha in conversation, fold it in — just
don't interrogate them for it.)
### Step 5 — Propose the full rewrite
- Show the complete rewritten CLAUDE.md in a code block — the whole file, ready to
- drop in, not a diff or a partial. Precede it with a short summary (a few lines)
- of the major moves you made so the user can orient quickly: what you cut, what
- you added, the new line count. The rewrite is the thing they're approving; the
- summary is just a map of it.
+ Show the complete rewritten target file in a code block — the whole file, ready
+ to drop in, not a diff or a partial. Use the actual filename in the heading and
+ summary (`AGENTS.md`, `CLAUDE.md`, `.claude/CLAUDE.md`, or the nested path).
+ Precede it with a short summary (a few lines) of the major moves you made so the
+ user can orient quickly: what you cut, what you added, the new line count, and
+ whether symlink or multi-file behavior changes.
```
Here's the rewrite. Major moves:
- Cut the generic-advice and React paragraphs (filler the model already knows)
- Fixed the stale commands (npm → pnpm, build → build:prod)
- Added an architectural map (api ↔ worker via Redis queue) and the enforced CI checks
- Added a gotchas section from the "do not remove" notes in dispatch.ts
+ - Preserved `CLAUDE.md` as a symlink to `AGENTS.md` instead of duplicating content
- 142 → 96 lines
<full rewritten file in a code block>
```
For a file being split into a `rules/` directory, show the rewritten main file
(with the router) plus each new `rules/*.md` file in full.
End by asking for confirmation: approve as-is, or tell you what to change. Treat
any pushback as input for another pass — re-propose, don't argue.
### Step 6 — Apply on confirmation
- Only after explicit approval, write the rewritten file to disk. If splitting
- into a `rules/` directory, create it and write the router into the main file.
- Confirm what was written and the final line count. If the user asked for
- feedback instead of approval, fold it in and re-present — back to Step 5.
+ Only after explicit approval, write the rewritten file to disk. If the approved
+ target is symlinked, write through the real target path and leave the symlink
+ intact unless the user explicitly asks to change the relationship. If two
+ independent files intentionally coexist, update only the approved file unless
+ the user approves a coordinated rewrite for both. If splitting into a `rules/`
+ directory, create it and write the router into the main file. Confirm what was
+ written, whether any symlink was preserved, and the final line count. If the
+ user asked for feedback instead of approval, fold it in and re-present — back to
+ Step 5.
## The rules-router pattern
When content legitimately exceeds ~300 lines, don't cram. Extract topic files
and leave a router. The main file stays a fast index; the agent reads a rule
file only when the task calls for it.
```
- CLAUDE.md ← stays lean; one-liner, tooling, map, hard constraints, + the router
+ AGENTS.md or CLAUDE.md
+ ← stays lean; one-liner, tooling, map, hard constraints, + the router
rules/
testing.md ← detailed testing conventions
database.md ← schema rules, migration process, SQL conventions
frontend.md ← component patterns, styling system
```
The router lives in the main file and reads like:
```markdown
## Detailed rules — read the relevant file before working in that area
- Writing or changing tests → read `rules/testing.md`
- Touching the database, schema, or migrations → read `rules/database.md`
- Frontend components or styling → read `rules/frontend.md`
```
The trigger condition ("when working on X") is the important part — without it
the agent doesn't know when to pull the file in. Each extracted file should
itself respect the spirit of the budget: focused and verifiable.
## Creating from scratch
If no file exists and the user wants one, run Step 2 (inspect) and Step 4
(derive gotchas from the repo) to gather material, then draft directly into the
ideal structure and confirm before writing. Start minimal — it is far better to
ship a tight 60-line file the team will extend than a speculative 300-line one
full of guesses. Only include sections you have real content for.
## Reference
For a richer set of before/after examples — vague rules rewritten as verifiable
ones, filler that should be cut, good gotcha notes — read
`references/examples.md`. Pull it in when you want concrete patterns to model
the rewrite on or to show the user.