skills: cut blabla and redundancy from skill prose

Per-skill prose tightening from the same audit swarm; each finding
passed an adversarial second reviewer. No behavioural change.

- audit: drop garbled "Conventions require deferred audits to
  compound" sentence (says the opposite of intent; the preceding
  line already closes the loophole).
- brainstorm: drop forward-pointing meta-comment about the
  Rationalisations table.
- debug: drop third restatement that debugger.md is the single
  source for the carrier/handoff fields.
- docwriter: drop motivational opener; Overview starts at the
  waste argument.
- fieldtest: fold the 2-4-examples rationale into the dispatch
  sentence instead of restating the count a fourth time.
- implement: drop "known platform constraint at the time" aside.
- planner: cut the verbose anti-drift paragraph (which restated
  the very table it claimed not to) down to a cross-reference.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-31 13:21:25 +02:00
parent 586298ff31
commit fc0e1d0d46
7 changed files with 14 additions and 33 deletions
+1 -3
View File
@@ -25,9 +25,7 @@ explicit backlog issue (issue tracker configured under
- the reason for deferral, - the reason for deferral,
- the date the audit will be re-run. - the date the audit will be re-run.
"We want to keep moving" is not a valid reason. Conventions "We want to keep moving" is not a valid reason.
require deferred audits to compound, which is the failure mode
the skill prevents.
Also triggered manually when baseline drift is suspected Also triggered manually when baseline drift is suspected
outside a cycle close (e.g. the bencher reports an unexplained outside a cycle close (e.g. the bencher reports an unexplained
-4
View File
@@ -42,10 +42,6 @@ Triggers:
- A cycle described as "small, only two iterations". - A cycle described as "small, only two iterations".
- A cycle where you are confident you know what to build. - A cycle where you are confident you know what to build.
The first two cases above are the most common pressure to
skip; both are explicitly resisted by this skill (see Common
Rationalisations).
## The Hard-Gate ## The Hard-Gate
``` ```
+2 -5
View File
@@ -87,11 +87,8 @@ separate one.
- **Agent dispatched:** `agents/debugger.md` — carries the - **Agent dispatched:** `agents/debugger.md` — carries the
four-phase process, the Phase 4.5 escalation rule, the four-phase process, the Phase 4.5 escalation rule, the
Common Rationalisations table, and the Red Flags list. It is Common Rationalisations table, and the Red Flags list. The
also the single source for the carrier and handoff field orchestrator does not execute these phases directly.
definitions (Carrier contract / Output format); this skill
names the fields but does not redefine them. The orchestrator
does not execute these phases directly.
- **Hand-off target:** `../implement/SKILL.md` — runs the - **Hand-off target:** `../implement/SKILL.md` — runs the
GREEN side after the orchestrator has decided whether to GREEN side after the orchestrator has decided whether to
commit the RED test separately or as part of the final fix commit the RED test separately or as part of the final fix
+2 -4
View File
@@ -9,10 +9,8 @@ description: Use when the API surface of one or more components has stabilized a
## Overview ## Overview
API documentation rots silently. Every iteration changes APIs Running this sweep per-cycle is waste — documenting an item
and module boundaries; doc comments lag. Running this sweep that gets renamed two iterations later just burns context. The right moment is
per-cycle is waste — documenting an item that gets renamed two
iterations later just burns context. The right moment is
post-stability: after a stretch of cycles in which the surface post-stability: after a stretch of cycles in which the surface
in question has held still. This skill is the third bucket in in question has held still. This skill is the third bucket in
the cadence taxonomy (per-cycle-mandatory audit; orchestrator- the cadence taxonomy (per-cycle-mandatory audit; orchestrator-
+5 -8
View File
@@ -115,17 +115,14 @@ carrier.
Dispatch `fieldtester` with the carrier from the Handoff Dispatch `fieldtester` with the carrier from the Handoff
Contract below. The agent picks 2-4 examples (one per axis Contract below. The agent picks 2-4 examples (one per axis
the cycle touched), implements them as downstream consumers, the cycle touched; fewer loses the signal on variation, more
runs them, classifies findings, and writes the spec. All overflows one readable report), implements them as downstream
artefacts (fixtures + spec) stay in the working tree as consumers, runs them, classifies findings, and writes the
unstaged changes; the orchestrator commits them after spec. All artefacts (fixtures + spec) stay in the working tree
as unstaged changes; the orchestrator commits them after
reviewing the report (suggested commit subject: reviewing the report (suggested commit subject:
`fieldtest: <cycle> — <N> examples, <K> findings`). `fieldtest: <cycle> — <N> examples, <K> findings`).
Two to four examples is the right size. One is too few (no
signal on variation); five is too many for one report to
stay readable.
## Handoff Contract ## Handoff Contract
`fieldtest` consumes (from orchestrator at cycle close) the carrier `fieldtest` consumes (from orchestrator at cycle close) the carrier
+1 -2
View File
@@ -243,8 +243,7 @@ independently at cycle close.
does not permit a subagent to spawn other subagents. The does not permit a subagent to spawn other subagents. The
orchestrator-agent cannot dispatch the role-agents above; orchestrator-agent cannot dispatch the role-agents above;
it adopts each role as a sequential phase in its own it adopts each role as a sequential phase in its own
context. This was a known platform constraint at the time context.
the role was designed.
- **Input sources:** - **Input sources:**
- `../planner/SKILL.md` — produces the plan files this - `../planner/SKILL.md` — produces the plan files this
skill consumes skill consumes
+3 -7
View File
@@ -72,13 +72,9 @@ Read the returned file-map. Lift the relevant entries into
the plan's "Files this plan creates or modifies" section; the the plan's "Files this plan creates or modifies" section; the
orchestrator may add or amend entries that recon missed. orchestrator may add or amend entries that recon missed.
Dispatch carrier — the fields `spec_path`, `iteration_scope`, and Dispatch carrier: see the **Carrier contract** table in
`focus_hint`, defined authoritatively under **Carrier contract** `agents/plan-recon.md` (single source for `spec_path`,
in `agents/plan-recon.md` (which marks `spec_path`/`iteration_scope` `iteration_scope`, `focus_hint`).
mandatory and `focus_hint` optional, and specifies the
BLOCKED-on-missing rule). That table is the single source for those
fields; it is deliberately not restated here, so the two files
cannot drift.
Recon does NOT decide decomposition. Two recon dispatches per Recon does NOT decide decomposition. Two recon dispatches per
planner run is unusual but legitimate (e.g. one for the main planner run is unusual but legitimate (e.g. one for the main