polish: six fixes from skill-migration reviews
Three minor-issues + three optional follow-ups identified by the three parallel reviewers of debug/docwriter/audit, fieldtest/planner/brainstorm, and implement. None blocking; all close calibrated gaps the bulk migration left. Minor-issues: - audit/SKILL.md: handoff field `regression_results` now explicitly carries "raw output verbatim (no rounding, no summarisation)" — restores the verbatim-numbers emphasis the original `bench_numbers` field name implied. - audit/agents/bencher.md: hypothesis examples grouped by axis (Tail-latency / Count reduction / Scalability / Overhead vs floor) with concrete numerical anchors (2× of median, ≥80%, 10-million-element, ±15%). Subjects stay domain-neutral but the calibrated bite returns. The preamble enumerates plausible subjects (allocators, query plans, request handlers, parsing strategies, codecs, caches) so the reader has concrete domains to anchor on. - implement/agents/implementer.md: "Architecture rules" section gains a 5-bullet kind-list (determinism contracts; backend / FFI constraints; schema versions; memory / resource models; effect / capability discipline) so the implementer has scaffolding to look for even when the project's CLAUDE.md is sparse. The "BLOCKED on contradiction" mechanism stays the load-bearing rule. Optional follow-ups: - brainstorm/SKILL.md Step 7.5: failure-mode procedure restores the structured backlog-issue fields (Title / Label / Body with `depends on:` and `context:` lines) and the milestone-container option for big deferred work (Gitea milestones, GitHub milestones, Linear projects). - templates/CLAUDE.md.fragment: adds an optional "Lockstep-invariant pairs" section so projects that have cross-file pairings can declare them in a way the architect agent and plan-recon agent already know to consult. Projects without such pairings omit the section; both agents handle absence gracefully. No discipline regressions; no Iron Law / Common Rationalisations / Red Flags edits. Pure scaffold-and-anchor improvements.
This commit is contained in:
+1
-1
@@ -116,7 +116,7 @@ The orchestrator picks per item:
|
||||
| Field | Content |
|
||||
|-------|---------|
|
||||
| `drift_items` | prioritised list (path + 1-line justification) from architect |
|
||||
| `regression_results` | per script: exit code + raw output |
|
||||
| `regression_results` | per script: exit code + **raw output verbatim** (no rounding, no summarisation — the orchestrator second-guesses with the full numbers) |
|
||||
| `recommendation` | per-item: `fix` / `ratify` / `carry-on` |
|
||||
|
||||
The orchestrator decides the per-item outcome; `audit` does
|
||||
|
||||
+18
-12
@@ -68,19 +68,25 @@ NO POLICY VERDICTS. THE ORCHESTRATOR DECIDES; YOU SUPPLY EVIDENCE.
|
||||
## Standard methodology
|
||||
|
||||
Every measurement starts with a hypothesis stated as a
|
||||
falsifiable claim, not a vague comparison. Examples (the
|
||||
specific subject varies per project):
|
||||
falsifiable claim, not a vague comparison. The subject
|
||||
varies per project (allocator variants, query plans,
|
||||
request handlers, parsing strategies, codec implementations,
|
||||
cache layers, …); the *shape* of a useful hypothesis does
|
||||
not:
|
||||
|
||||
- "Variant A's p99 per-operation latency is within 2× of
|
||||
median under continuous pressure with a >100 MB working
|
||||
set."
|
||||
- "Optimisation X reduces total resource consumption by ≥80%
|
||||
on the canonical fixture vs the same fixture without it."
|
||||
- "Variant A allows running the long-form workload without
|
||||
resource exhaustion; the unoptimised variant exhausts
|
||||
before completion."
|
||||
- "Variant A's overhead vs the raw-cost floor on the canonical
|
||||
fixture is within ±15% of the recorded baseline."
|
||||
- **Tail-latency under pressure:** "Subject A's p99
|
||||
per-operation latency is within 2× of its median under
|
||||
continuous pressure with a >100 MB working set."
|
||||
- **Count / volume reduction:** "Optimisation X reduces
|
||||
total resource consumption by ≥80% on a workload that
|
||||
exercises the optimised code path vs the same workload
|
||||
bypassing it."
|
||||
- **Scalability ceiling:** "Subject A successfully
|
||||
processes a 10-million-element workload without resource
|
||||
exhaustion; the unoptimised variant fails below 1 million."
|
||||
- **Overhead vs floor:** "Subject A's overhead vs the
|
||||
raw-cost floor on the canonical fixture is within ±15% of
|
||||
the recorded baseline."
|
||||
|
||||
Then design the workload to *exercise* the claim. Specifically:
|
||||
|
||||
|
||||
+25
-8
@@ -259,16 +259,33 @@ Orchestrator interpretation:
|
||||
1. Delete the just-written spec file from the working tree
|
||||
(`rm <spec_path>` — a shell delete on the working tree,
|
||||
NOT `git rm`; the file was never committed).
|
||||
2. Open a backlog issue (via the command configured under
|
||||
`git.issue_tracker.list_cmd`'s sibling create command —
|
||||
typically `tea issues create` for Gitea, `gh issue create`
|
||||
for GitHub) pointing forward to a future re-brainstorm,
|
||||
under the appropriate priority bucket.
|
||||
2. Open a backlog issue (via the project's issue-tracker
|
||||
create command — `tea issues create` for Gitea,
|
||||
`gh issue create` for GitHub, analogous for Linear /
|
||||
Jira / etc.) pointing forward to a future re-brainstorm.
|
||||
Include in the issue:
|
||||
|
||||
- **Title:** one-line identity of the deferred work
|
||||
- **Label:** matching the project's vocabulary (often
|
||||
`feature` / `bug` / `idea`; promote to `BLOCKER` if
|
||||
the unratified mechanism is on a core-functionality
|
||||
path)
|
||||
- **Body:** short description, plus two structured
|
||||
lines:
|
||||
- `depends on: <name of the unratified mechanism>`
|
||||
- `context: <why this is deferred>`
|
||||
|
||||
If the deferred work is large enough to need its own
|
||||
spec on resumption — multi-iteration scope, cross-
|
||||
subsystem — file it as a **milestone container**
|
||||
instead (Gitea milestones, GitHub milestones, Linear
|
||||
projects, whatever the project's tracker calls a
|
||||
long-running work scope), not as a single issue.
|
||||
|
||||
3. Tell the user the spec was retired and which backlog
|
||||
issue was filed (include the issue number). No commit is
|
||||
needed for the backlog entry — the issue tracker is the
|
||||
live store.
|
||||
entry was filed (include the issue or milestone number).
|
||||
No commit is needed for the backlog entry — the issue
|
||||
tracker is the live store.
|
||||
|
||||
After the failure-mode procedure runs, the brainstorm
|
||||
session ENDS. There is no Step 8, no Step 9. The idea is
|
||||
|
||||
@@ -95,11 +95,29 @@ is yes — write the test.
|
||||
|
||||
The binding architectural rules of the project are declared
|
||||
in `CLAUDE.md` and (if the project has one) the design
|
||||
ledger at `paths.design_ledger`. Read them as part of the
|
||||
standing reading list. Respect them in the diff. If the
|
||||
task text appears to ask for something a binding rule
|
||||
forbids, return `BLOCKED` with the contradiction named — do
|
||||
not silently substitute.
|
||||
ledger at `paths.design_ledger`. The specific rules are
|
||||
project-specific, but they typically cover:
|
||||
|
||||
- **Determinism contracts.** Canonical forms, sort orders,
|
||||
hash schemes, anything where the project commits to a
|
||||
fixed byte-level output.
|
||||
- **Backend / foreign-function constraints.** Which library
|
||||
calls are forbidden, which are required, which version
|
||||
is pinned.
|
||||
- **Schema / format versions.** What `v0` / `v1` shapes
|
||||
are, what counts as a breaking change, what migration
|
||||
notes a schema bump requires.
|
||||
- **Memory / resource models.** Reference counting,
|
||||
ownership, lifetime invariants, capacity bounds.
|
||||
- **Effect / capability discipline.** What functions may
|
||||
perform IO / network / unsafe, how effect annotations
|
||||
flow.
|
||||
|
||||
Read the project's rules as part of the standing reading
|
||||
list. Respect them in the diff. If the task text appears
|
||||
to ask for something a binding rule forbids, return
|
||||
`BLOCKED` with the contradiction named — do not silently
|
||||
substitute.
|
||||
|
||||
## The Process
|
||||
|
||||
|
||||
@@ -67,3 +67,22 @@ debug skill is mandatory for any observable misbehaviour
|
||||
(failing test, segfault, wrong stdout, panic). See the debug
|
||||
SKILL.md and debugger agent for the Iron Law and four-phase
|
||||
process.
|
||||
|
||||
## Lockstep-invariant pairs (optional)
|
||||
|
||||
Some projects have cross-file pairings where a change in one
|
||||
location must be mirrored in another — a new arm in one
|
||||
without the matching update in the other ships silently
|
||||
broken. The `architect` agent walks these pairs during
|
||||
audit drift review, and `plan-recon` consults this section
|
||||
when computing the cross-references column of a file-map.
|
||||
|
||||
Projects that have such pairings enumerate them as a table
|
||||
in this section. Projects that don't, omit the section
|
||||
entirely (both agents handle absence gracefully).
|
||||
|
||||
Example shape:
|
||||
|
||||
| Pair | Failure mode |
|
||||
|------|--------------|
|
||||
| `<file A>:<func A>` ↔ `<file B>:<func B>` | <what breaks when the pair is not updated together> |
|
||||
|
||||
Reference in New Issue
Block a user