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 date the audit will be re-run.
"We want to keep moving" is not a valid reason. Conventions
require deferred audits to compound, which is the failure mode
the skill prevents.
"We want to keep moving" is not a valid reason.
Also triggered manually when baseline drift is suspected
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 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
```
+2 -5
View File
@@ -87,11 +87,8 @@ separate one.
- **Agent dispatched:** `agents/debugger.md` — carries the
four-phase process, the Phase 4.5 escalation rule, the
Common Rationalisations table, and the Red Flags list. It is
also the single source for the carrier and handoff field
definitions (Carrier contract / Output format); this skill
names the fields but does not redefine them. The orchestrator
does not execute these phases directly.
Common Rationalisations table, and the Red Flags list. The
orchestrator does not execute these phases directly.
- **Hand-off target:** `../implement/SKILL.md` — runs the
GREEN side after the orchestrator has decided whether to
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
API documentation rots silently. Every iteration changes APIs
and module boundaries; doc comments lag. Running this sweep
per-cycle is waste — documenting an item that gets renamed two
iterations later just burns context. The right moment is
Running this sweep 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
in question has held still. This skill is the third bucket in
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
Contract below. The agent picks 2-4 examples (one per axis
the cycle touched), implements them as downstream consumers,
runs them, classifies findings, and writes the spec. All
artefacts (fixtures + spec) stay in the working tree as
unstaged changes; the orchestrator commits them after
the cycle touched; fewer loses the signal on variation, more
overflows one readable report), implements them as downstream
consumers, runs them, classifies findings, and writes the
spec. All artefacts (fixtures + spec) stay in the working tree
as unstaged changes; the orchestrator commits them after
reviewing the report (suggested commit subject:
`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
`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
orchestrator-agent cannot dispatch the role-agents above;
it adopts each role as a sequential phase in its own
context. This was a known platform constraint at the time
the role was designed.
context.
- **Input sources:**
- `../planner/SKILL.md` — produces the plan files this
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
orchestrator may add or amend entries that recon missed.
Dispatch carrier — the fields `spec_path`, `iteration_scope`, and
`focus_hint`, defined authoritatively under **Carrier contract**
in `agents/plan-recon.md` (which marks `spec_path`/`iteration_scope`
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.
Dispatch carrier: see the **Carrier contract** table in
`agents/plan-recon.md` (single source for `spec_path`,
`iteration_scope`, `focus_hint`).
Recon does NOT decide decomposition. Two recon dispatches per
planner run is unusual but legitimate (e.g. one for the main