Skill-description tuning: measured fire rates, collision score 23->13, routing table alignment

README.md

@@ -203,7 +203,7 @@ CLI wrappers under `~/.config/agents/bin/`.
 
 Skills are not slash commands. They fire on the situation from their description — writing prose
 reaches for `unslop`, reviewing TypeScript reaches for `typescript-best-practices` — and
-`tests/auto-trigger.sh` asserts that with 28 cases against the live model.
+`tests/auto-trigger.sh` asserts that with 30 cases against the live model.
 
 ## Checks that can fail
 

claude/skills/executing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: executing-plans
-description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+description: "A written plan or numbered task list already exists and the ask is to carry it out: work the tasks in order, verify each, pause at the review checkpoint between phases."
 ---
 
 > **Ported here, and some of what it names is not.** This skill comes from upstream, where it

claude/skills/swarm/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: swarm
-description: "Use when work splits into independent parts or approaches should be raced — 'in parallel', 'at once', 'all of these', 'try N ways'. Fans out N agents in ONE batched message, returns one table."
+description: "Three or more independent units of work exist (files, packages, endpoints, rival approaches) and none needs another's result. Fans out N agents in ONE batched message, returns one table."
 ---
 
 # Swarm

claude/skills/test-driven-development/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-driven-development
-description: "Third, once the shape is known, including any bugfix: write the failing test before the implementation code."
+description: "About to write implementation code or a bugfix and no test fails for that behaviour yet: write the failing test first, watch it fail, then write the minimum that passes."
 ---
 
 # Test-Driven Development (TDD)

claude/skills/writing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: "Second, once the shape is agreed and before code: turn a spec or requirements into a written multi-step plan."
+description: "Requirements are settled, nothing is written down about how, and the work is more than one edit: produce the plan document, file map, bite-sized tasks, one verification per task."
 ---
 
 > **Ported here, and some of what it names is not.** This skill comes from upstream, where it

docs/how-skills-fire.md

@@ -75,7 +75,7 @@ its own.
 
 `tests/auto-trigger.sh` runs real prompts through the CLI and reports which skills fired. A
 version of the hook that dropped the routing table in favour of "the descriptions are the
-triggers" was measured against 28 cases:
+triggers" was measured against the 28 auto-trigger cases the suite carried on 2026-08-23:
 
 | Hook version | Result |
 |---|---|

docs/what-this-actually-does.md

@@ -61,7 +61,7 @@ The thing does what it says. Nobody has shown it changes an outcome.
 |---|---|
 | Does delegation rate fall off across a session's own lifetime? | `tests/delegation-drift.sh` exists, is pre-registered (first-third vs. last-third breadth-eligible delegation rate, with explicit floors on eligible windows and contributing sessions), and states its own reverse-causality confound up front: late-session work may just be less delegable, independent of anything the model does differently. It reports `NOT EVALUATED` rather than a rate below its own floors, the expected, correct result on day one, not a bug. |
 | Does auto-compaction correlate with worse behaviour in the turns after it? | `tests/compaction-effect.sh` is pre-registered the same way (is_error rate in a 15-tool-call window before and after a compaction boundary, with floors on boundary count and pooled calls) and states plainly that any result is correlational, not causal. A session long enough to hit auto-compaction is not a random draw from the same population as a short one. The one published result in this space, Governance Decay (arXiv 2606.22528), is from a different harness and does not transfer by citation alone. |
-| Do the skills outside the measured subsets actually dispatch? | `tests/auto-trigger.sh` declares 28 cases. Category 1 above accounts for a 9-case routing-table ablation and 8 principle-prefix-naming fixes, whose re-run is "not yet authorised" per CHANGELOG.md, "1.35.0" (roughly 24 headless calls). The dispatch rate for the remaining cases is not separately recorded in this document's sources. |
+| Do the skills outside the measured subsets actually dispatch? | `tests/auto-trigger.sh` declares 30 cases. Category 1 above accounts for a 9-case routing-table ablation and 8 principle-prefix-naming fixes, whose re-run is "not yet authorised" per CHANGELOG.md, "1.35.0" (roughly 24 headless calls). The dispatch rate for the remaining cases is not separately recorded in this document's sources. |
 | Does any of this improve output quality on a frontier model? | Three independent local measurements found no gain and no loss large enough to trust: the review pathway (category 1), a regression-scored SWE-bench Lite pass that tied all four arms at 0 of 2 resolved once neighbour-breaking counted, and the false-completion pilot. `docs/research/do-harnesses-help.md` names the honest reading directly: these are ceiling effects on small, well-specified tasks, which read as "no difference" when the accurate statement is "this could not tell." `docs/research/harness-value-literature-2026-08.md`, surveying roughly 70 published sources, reaches the same split independently: no well-powered published result shows a config-layer gain on issue-resolution tasks with a frontier model, while the tail-behaviour literature (test-exploitation, cheating, out-of-scope destructive actions) shows some of the largest effect sizes in the field. |
 
 ### The failures, not smoothed over

tests/README.md

@@ -332,6 +332,29 @@ hand, the same status `bin-scripts.sh` and `container-matrix.sh` started from.
 tests/hook-latency.sh
 ```
 
+## evals/autofire/
+
+Whether the four planning-chain skills route from a situation with no user instruction naming
+them. `tests/evals/autofire/RESULTS.md` carries the arm, its reporting rules and its cost.
+
+The raw samples, one JSON object per line, written by `auto-trigger.sh` in SAMPLES mode:
+
+- `tests/evals/autofire/runlog-baseline-turns3-writing-plans-spec-to-steps.jsonl`
+- `tests/evals/autofire/runlog-baseline-turns3-swarm-audit.jsonl`
+- `tests/evals/autofire/runlog-baseline-turns3-executing-plans-checkpoints.jsonl`
+- `tests/evals/autofire/runlog-baseline-turns3-tdd-known-bugfix.jsonl`
+- `tests/evals/autofire/runlog-baseline-turns12-executing-plans-checkpoints.jsonl`
+- `tests/evals/autofire/runlog-baseline-turns12-tdd-known-bugfix.jsonl`
+- `tests/evals/autofire/runlog-after-writing-plans-spec-to-steps.jsonl`
+- `tests/evals/autofire/runlog-after-swarm-audit.jsonl`
+- `tests/evals/autofire/runlog-after-tdd-known-bugfix.jsonl`
+- `tests/evals/autofire/runlog-after-executing-plans-checkpoints.jsonl`
+
+Read the turns=3 and turns=12 tables together or not at all. Every turns=3 sample terminated
+`error_max_turns`, including the arms that fired, so being cut off separates nothing there. That
+is why two of those four numbers were re-taken at a budget nothing exhausted rather than
+published as results.
+
 ## evals/
 
 `evals/run-pathways.sh` and `evals/swebench/run.sh` score this bundle against
@@ -376,7 +399,7 @@ script prints `SKIP: ...` and exits 0. That is a valid, non-failing outcome,
 not a bug in the test.
 
 Each case runs in its own `mktemp -d` under `/tmp` (never this repo), so
-nothing here pollutes the working tree the model sees. The test suite covers 28 cases:
+nothing here pollutes the working tree the model sees. The test suite covers 30 cases:
 readme-writing, typescript-review, swarm-audit, blast-radius-auth, feature-chain,
 root-cause-guard, overnight-audit-trail, ui-iterate-styles, component-registry-combobox,
 idempotent-cron, negative-arithmetic, and negative-factual.
@@ -389,7 +412,7 @@ idempotent-cron, negative-arithmetic, and negative-factual.
    never report `loggedIn: true` there. The script detects this and skips
    rather than failing the build.
 2. **It would bill tokens.** Every case makes real API calls, up to 3 turns
-   each across 28 cases. Running this on every push or pull request in CI
+   each across 30 cases. Running this on every push or pull request in CI
    would spend real money on a check that mostly guards against
    skill-routing regressions. Those regressions are infrequent. Run the
    script by hand instead, or schedule it on a machine that already has an
@@ -568,6 +591,59 @@ Known gap: `hooks.json` names two of the eight scripts under `claude/hooks/` dir
 plugin lane carries routing only. The rest are invoked from inside those or wired through
 `claude/settings.json` in the full install, so renaming one of them is not caught here.
 
+## description-collision.sh
+
+Scores every shipped skill description for shared trigger n-grams and names the overlapping
+pairs. No model calls, no network. Splits each description at its first colon, period or em dash
+into the discriminator clause and the rest, then weights shared 2- and 3-grams by where they
+land: 3 for both first clauses, 2 for one, 1 for neither.
+
+The only failing condition is a 3-gram opening two descriptions. That is the defect `aebeebb`
+fixed by hand, where `grill-me` and `interrogate` both led with "tear this apart". Everything
+else prints and passes, and the threshold is echoed on every run so nobody reads a green as "no
+overlap".
+
+Read the header before citing it. This is design discipline, not a dispatch law. The claim that
+colliding triggers suppress both skills was withdrawn in 1.47.0 for having no surviving runlog,
+and the pre-registered replacement at `evals/collision/` found the hypothesis unsupported.
+
+```
+tests/description-collision.sh              # score claude/skills
+tests/description-collision.sh --self-test  # prove it can fail, then that it passes
+```
+
+`--self-test` plants a collision that survives stopword normalisation, asserts the check fails
+and names the pair, then scores a clean corpus and asserts it passes. It found three defects in
+its own scorer before the live corpus did: a wrapped stoplist that made BSD awk exit without
+scoring anything, a `score()` that returned awk's status without telling a parse error apart from
+"no collisions", and an em dash that aborts BSD awk under a UTF-8 locale. `LC_ALL=C` is pinned
+for the third.
+
+## stage-skill-descriptions.sh
+
+Installs the repo's description line for named skills into `~/.claude/skills`, and puts it back.
+
+`auto-trigger.sh` runs the CLI in a scratch workdir, so the descriptions that reach the matcher
+are the installed ones. Measured 2026-09-01: a project-local `.claude/skills/<name>/SKILL.md` is
+loaded and listed, but a user-level skill of the same name wins. Asked to quote its own listing
+for `swarm`, the model returned the installed text and reported no duplicate. So an after-arm
+measured without installing would measure the before-arm's bytes and publish it as a result.
+Running `install.sh` instead installs the whole tree, including whatever another session has in
+flight.
+
+```
+tests/stage-skill-descriptions.sh --stage swarm writing-plans
+tests/stage-skill-descriptions.sh --status
+tests/stage-skill-descriptions.sh --restore
+```
+
+Both directions refuse rather than guess. `--stage` aborts if any installed copy already differs
+from repo HEAD, and pre-flights every named skill before touching any, so a half-applied stage
+cannot happen. `--restore` compares each file against the checksum it wrote and refuses that file
+if it changed, keeping the original instead of overwriting a foreign edit. Every `cp` is checked:
+without that, a failed copy would record a manifest checksum of the unchanged destination, and
+the restore path would delete the only backup after failing to use it.
+
 ## dispatch-fleet.sh
 
 `dispatch-fleet.sh` measures the 54-fixture set in `~/vstack-dispatch/` — recall, precision,