# context-doctor

Adopt this skill: https://proskills.md/skills/other/chrono-meta-forge-harness-plugins-fh-meta-skills-context-doctor

Page: https://proskills.md/skills/other/chrono-meta-forge-harness-plugins-fh-meta-skills-context-doctor
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: plugins/fh-meta/skills/context-doctor/SKILL.md
size: 8119
upstream: https://github.com/chrono-meta/forge-harness/blob/main/plugins/fh-meta/skills/context-doctor/SKILL.md

````text
---
name: context-doctor
description: Reduces token waste in Claude Code sessions across two axes — context footprint (auto-generates .claudeignore, guides over-read files and /clear timing) and command output (routes to a command-output proxy/hook such as rtk to trim verbose CLI stdout). In hub environments, regularly audits bloated CLAUDE.md/MEMORY.md/memory/*.md files and proposes compression. Usable standalone without a hub clone.
user-invocable: true
allowed-tools: ["Read", "Write", "Bash", "Glob", "Grep"]
model: sonnet
complexity_routing:
  base: sonnet
  high: opus
  escalate_when:
    - cold_start
    - cross_project
---

# context-doctor — Token Efficiency Diagnosis + Automatic Prescription

Diagnoses the main causes of session token waste and prescribes immediate remedies:
1. No `.claudeignore` → unnecessary files loaded wholesale into context
2. Repeated full reads of large files → paying the same cost N times
3. Not using `/clear` after direction changes → continuing work with accumulated noise
4. Verbose CLI output → every `git`/`ls`/build/test call floods context with stdout (a *different* layer from 1–3 — see §Command-Output Reduction)

**Two reduction axes — keep them distinct.** Causes 1–3 are the **context-footprint** axis (what gets read *into* context: files, history). Cause 4 is the **command-output** axis (tokens produced *by* the tools you run). `.claudeignore` cannot touch command output, and a command-output proxy cannot touch file reads — they are complementary, not substitutes. (Step 3.5 below adds an optional **third**, orthogonal lever — provider-side cache billing — distinct from both.)

**Standalone install** — this skill works normally with plugin install only, without cloning the full meta-harness.

**Built-in `/doctor` first (sister anchor, 2026-07-25)**: since the Claude 5 generation, the official
`/doctor` command claims skill/CLAUDE.md rightsizing ("The new rules of context engineering for Claude 5
generation models" — https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models).
Run the built-in first when available — its scope is skills + CLAUDE.md rightsizing only. This skill's
increment over it = `.claudeignore` diagnosis/generation (Step 1), `/clear` timing guidance,
command-output proxying (§Command-Output Reduction), hub-wide memory/CLAUDE.md audits, and the
measurement discipline (resident footprint is measured only via a fresh top-level `/context`, and any
diet is followed by a `prompt-regression` probe — the blog's own "no measurable loss" claim ships no
method, so treat that number as a vendor claim). Triage record:
`tracks/_audit/session_2026_07_25_claude5-context-rules-sister.md`.

## Execution Steps

### Step 1. `.claudeignore` Diagnosis + Generation

Check whether `.claudeignore` exists in the project root (bash in §Step-Bash).

**If absent**: Scan project structure and auto-generate.

**If already present**: Keep existing content + suggest additional patterns only (no overwrite). Check for sentinel comment (`# context-doctor:`) and add to first line if absent.

Generation criteria — by project type:

| Detected type | Additional patterns |
|---|---|
| Node.js (`package.json`) | `node_modules/` · `dist/` · `build/` · `.next/` · `coverage/` |
| Python (`pyproject.toml` / `setup.py`) | `__pycache__/` · `.venv/` · `*.egg-info/` · `dist/` · `.pytest_cache/` |
| Java (`pom.xml` / `build.gradle`) | `target/` · `build/` · `.gradle/` |
| Common (always include) | `.git/` · `*.log` · `*.lock` · `*.min.js` · `*.min.css` |

Present preview to user after generation → save after confirmation.

Automatically add sentinel comment to first line when generating/updating:
```
# context-doctor: configured YYYY-MM-DD
```
→ Suppresses auto-invocation in subsequent sessions.

> **Detail**: See `SKILL_detail.md §Step-Bash` — detection bash for Steps 1/2/4/5, large-file warning format, audit report format — read when executing any step's commands.

### Step 2. Large File Detection + Split Strategy Guidance

Detect files exceeding 500 lines (top 10 — bash in §Step-Bash) and output the split-read guidance per file (offset + limit, section by section).

**Repeated full-read pattern** (burst pattern) detection criteria (behavioral):
- 3+ files over 500 lines exist and `.claudeignore` was absent
- User mentions "read it all at once" / "re-read the whole thing every time"

When burst pattern is detected → **trigger harvest-loop integration in Step 4**.

### Step 3. `/clear` + Model Switching Timing Guide

Check session state with the user, then prescribe according to context:

**Wrap-then-Compact** (when approaching context limit — CC subscription only):

When context is near the limit and you want to *preserve state* rather than reset:
1. Ask Claude: `"wrap up — completed items, modified files, pending tasks"`
2. Claude writes a structured summary → that summary anchors the `/compact` output
3. Run `/compact` — the wrap becomes the cold-start primer for next session

> This is superior to blind `/compact` because you control what's preserved. Bedrock/API has no meter warning — CC subscription only.

→ Full pattern + table: `CHEATSHEET.md §10 Lever 6`

**`/clear` recommended situations** (reset, not preserve):
```
□ Work direction has changed significantly (exploration → implementation, bug fix → refactor, etc.)
□ Switching to a different track/project
□ Error debugging has gone long and noise has accumulated
□ Previous attempts are unrelated to current work
□ Context has grown large (context rot — measurable quality degradation as input length grows,
  well before the window fills; threshold varies by model/task. Chroma 2025 context-rot research)
```

→ Recommend immediate `/clear` and restart in fresh context.

**Model switching criteria**:

| Current task | Recommended | Command |
|---|---|---|
| Complex design decisions · architecture review | Opus — dispatch-first: package into an opus/sidecar agent dispatch (consent-gated); session pin secondary | dispatch · or `/model opus` |
| Code writing · file editing · refactoring | Sonnet (default) | — |
| Simple file lookup · short Q&A | Haiku | `/model haiku` |

> Models are tools for allocating the right expertise to complexity. Opus for simple tasks = wasted expertise; Haiku for design decisions = insufficient expertise. Switch models when task nature changes.

### Step 3.5. Cache-Boundary Audit (prompt caching, optional third lever)

Distinct from both axes above: Steps 1–3 reduce what occupies the context *window*; this
reduces what the provider re-bills as **fresh input tokens** on each turn by preserving
prompt-cache hits. **Optional** — run it when a metered/quota-limited backend makes cache
cost the binding constraint (same gating logic as §Command-Output Reduction: diagnose and
recommend, do not chase this when tokens are merely plentiful).

**Audit checklist**:
- Is the system prompt / CLAUDE.md content **stable byte-for-byte** across turns in a
  session? Any turn-to-turn diff in the fixed prefix invalidates the cache for that prefix —
  which is in tension with Step 5's CLAUDE.md-compression prescription: compress at session
  boundaries (before a fresh cache is built), never mid-session (which would invalidate one
  already warm).
- Is session-specific / dynamic content (task state, recent results) placed at the
  **end of the user message**, not interleaved into the system prompt or early context?

**Reported, UNCALIBRATED by FH** (2026-07-27 frontier digest, issue #102): input:output token
ratio **> 10:1** favors cache/context engineering over model-level optimization; **> 50:1**,
prefix caching dominates; cache-boundary control reportedly raised hit rate ~7%→84% in one
production case (arXiv:2603.09619 *Context Engineering: From Prompts to Corporate Multi-Agent
Architecture* · appscale.blog).

**What is and is not verified** — the two are separate checks and only one has been run:
the cited paper's **existence** was confirmed 2026-
````

## File: README.md
upstream: https://github.com/chrono-meta/forge-harness/blob/main/README.md

````text
<p align="center">
  <img src="https://raw.githubusercontent.com/chrono-meta/forge-harness/main/docs/banner.png" alt="forge-harness — Forge your projects, pass them through, faster. Quality is the lever — speed is the result." width="680">
</p>

<p align="center">
  <a href="https://arxiv.org/abs/2609.04218"><img src="https://img.shields.io/badge/arXiv-2609.04218-b31b1b.svg?logo=arxiv" alt="arXiv:2609.04218 — the FH governance paper"></a>
  <a href="https://github.com/walkinglabs/awesome-harness-engineering#coding-agent-harnesses"><img src="https://awesome.re/mentioned-badge.svg" alt="Mentioned in Awesome Harness Engineering"></a>
  <a href="https://github.com/VoltAgent/awesome-agent-skills#community-skills"><img src="https://img.shields.io/badge/listed_in-awesome--agent--skills-0ea5e9.svg?logo=awesomelists" alt="Listed in awesome-agent-skills"></a>
  <a href="https://github.com/marketplace/actions/fh-gate-typed-ai-code-review-verdict"><img src="https://img.shields.io/badge/GitHub_Action-marketplace-2088FF.svg?logo=githubactions" alt="GitHub Actions Marketplace — fh-gate"></a>
  <a href="https://www.npmjs.com/package/@chrono-meta/fh-gate"><img src="https://img.shields.io/npm/v/@chrono-meta/fh-gate.svg?color=cb3837&logo=npm" alt="npm"></a>
  <a href="https://www.npmjs.com/package/@chrono-meta/fh-gate"><img src="https://img.shields.io/npm/dt/@chrono-meta/fh-gate.svg?color=3fb950&logo=npm&label=downloads" alt="npm total downloads"></a>
  <a href="https://github.com/chrono-meta/homebrew-forge-harness"><img src="https://img.shields.io/badge/homebrew-tap-FBB040.svg?logo=homebrew" alt="Homebrew tap"></a>
</p>

<p align="center">
  <b>English</b> · <a href="README.ko.md">한국어</a> · <a href="README.zh.md">中文</a> · <a href="README.ja.md">日本語</a>
</p>

# forge-harness (FH)

**FH is a meta-harness for [Claude Code](https://github.com/anthropics/claude-code): it helps you build harnesses and skills — the rules, gates and memory a project needs — and checks them before they ship.**

A *harness* is what you wrap around an AI agent in one project so it stops needing the same instructions
every session: rules it follows, checks that block bad changes, and a record of what it learned. A
*meta*-harness is the one that builds and verifies those, project after project.

> Stop re-explaining your rules to your agent. Put them in the project.

<!-- The line above was chosen, not drafted. Its companion — «quality gates that catch you, not just your
     agent» — sat below it as a centered line until 2026-11-07 and now lives as one sentence with its evidence in
     «Who it is for». Before rewriting either, read docs/ETHOS.md §"Who this line is for". -->
## Who it is for, and what you get

For people who use Claude Code (or another coding agent) on real projects and are tired of repeating
themselves or of finding out too late that a change was wrong. You get three things:

| You get | In practice | Evidence |
|---|---|---|
| **A gate before merge** | A diff is judged *before* it lands, and the verdict names what the change lost. The verdict is a typed value (`PASS · PENDING · BLOCKED · ESCALATE`), not text you grep. It works on your own code, not only an agent's. | Demo GIF below · a run on code someone else wrote and a planted-hole test, with sample sizes: [Evidence](#evidence) · method and controlled ablation: [arXiv:2609.04218](https://arxiv.org/abs/2609.04218) |
| **Memory that carries over** | `tracks/` keeps what each session learned, so session 2 starts where session 1 stopped. | At session end the card in `tracks/_meta/` is updated, and the next session starts from it ([`CLAUDE.md`](CLAUDE.md) §Session Wrap-up). |
| **Someone who picks the check for you** | Say "diagnose this project" or "accelerate this project" and you get a ranked list of what to fix or install. Nothing is changed until you approve each item. | The procedure is in [`CLAUDE.md`](CLAUDE.md) §Field-Harness Diagnostic. Each item lands only after you approve it |

The gates catch you, not only your agent: on 2026-08-22 they blocked the author of FH seven times, and the author caught none of those first ([one day of gate blocks](docs/GATE_DAY.md)).

<p align="center">
  <img src="https://raw.githubusercontent.com/chrono-meta/forge-harness/main/docs/demo/gate-block.gif" alt="regression guard blocking a change that dropped a Done When section, then passing once it is restored" width="820">
</p>
<p align="center">
  <sub>Recorded from a real run of the guard (not a mock-up; the script that regenerates it is linked below): an agent “tidied up” a skill spec (<code>SKILL.md</code>) and dropped its Done When section. The guard BLOCKs and names the missing section; put it back and it returns PASS and the cleanup ships unchanged.<br>Regenerate: <code>brew install vhs &amp;&amp; vhs docs/demo/gate-block.tape</code></sub>
</p>

## Quick start

Pick one door. They install differently and give you different things.

Door ① — just the gate. No clone, no plugin, no Claude Code session.

```bash
cd your-repo && npx --package @chrono-meta/fh-gate fh-gate     # reviews the git diff of the current repo
```

It finds your changed files from `git diff`, sends them to a review backend, and prints a verdict
(`FH_GATE_VERDICT: PASS | PENDING | BLOCKED | ESCALATE`) plus an exit code. A PASS counts only if the review actually ran: a backend that never answered, a dry run, or an unknown exit code is not a PASS, and the GitHub Actions step fails on it by default. Needs Node ≥ 16 and one backend
CLI installed and logged in: `claude` (default) or `codex` (`FH_BACKEND=codex`). Use it in CI, a pre-commit
hook, or beside another agent. A GitHub Actions step and a Homebrew tap exist too — see [Run the gate](docs/REFERENCE.md#run-it-outside-claude-code--the-fh-gate-cli).

Door ② — the whole harness, inside Claude Code.

```bash
claude plugin marketplace add https://github.com/chrono-meta/forge-harness.git
claude plugin install -s user fh-meta@forge-harness
git clone https://github.com/chrono-meta/forge-harness.git ~/projects/forge-harness
cd ~/projects/forge-harness && claude          # then type: hi   (or 안녕 · こんにちは · 你好)
```

1. Open the cloned folder in Claude Code (the `cd … && claude` line).
2. Say hello. In a fresh clone FH reads the checkout, sees no session files, and opens a short
   menu for new users: *create your first project · map an existing project · read the guide*. It also
   tells you if the install wizard has not run yet.

   <img src="https://raw.githubusercontent.com/chrono-meta/forge-harness/main/docs/demo/door2-menu.gif" alt="typing hi in a fresh forge-harness clone; FH reads the checkout, opens the new-user menu, and warns that the install wizard has not run yet" width="760">

3. Take one win in the same session. Say «Connect a project» (FH scans `../` for git repos and
   creates `tracks/{project}/`), then «accelerate this project» (ranked, approval-gated plan) or
   «run /context-doctor» (token-waste scan). For full setup, run `/install-wizard`: every item is
   approved one by one and a decline is recorded.

**Taking it off again.** From the FH clone, `python3 scripts/fh_detach.py --project <the project you ran the
wizard in>` prints what the wizard wrote for that project; add `--apply` to undo it. Other projects keep FH. Add
`--machine` to also remove what every project shares: the `~/.zshrc` block and the FH clone's own hooks and
`core.hooksPath` (without it they are listed as kept). Another project you ran the wizard in needs its own `--project` — detach those
first and run `--machine` last. Changed in 3.32.0: before that, `--apply` removed the shared setup too. If `--project`
is the FH clone itself, its own hooks count as that project's and go without `--machine`. `--plugin` also runs
`claude plugin uninstall fh-meta@forge-harness` and removes the `forge-harness` marketplace entry. A hook counts
as FH's only when every field equals a shipped snippet entry (or the wizard's companion-store hook form) — so o
````
