Responds to maintainer review: "re-review" names the action badly — it
reads as "review again," which is the exact failure observed in the
field (fix reviewers re-running full reviews and package-wide suites
against explicit scope instructions). "Fix review" names the artifact
under review — the fix diff since the previous review — and makes the
scope self-enforcing.
Pure vocabulary substitution: re-review-prompt.md becomes
fix-review-prompt.md, SKILL.md and the review-package --role value
follow, and the term is introduced once as "a scoped fix review — a
review of the fix diff, not a fresh review." No behavioral rules
changed. Historical records (docs/superpowers/plans, specs,
RELEASE-NOTES) keep the old vocabulary; other skills' generic verb
usage ("no need to re-review") is untouched.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Responds to maintainer review of this branch: the dispatch-hint lines
were hardcoded Codex strings inside shared skill tooling that every
harness runs.
The per-role hint lines now live in a platform-owned data file,
skills/using-superpowers/references/codex-dispatch.hints, and the
task-brief/review-package scripts only relay the current role's line.
The relay is suppressed when CLAUDECODE is set (Claude Code's dispatch
templates already carry model selection) and on any harness with no
hints file; unknown harnesses fail toward printing, because a silent
no-op in the environment that needs the hint is the failure mode this
mechanism exists to prevent. Printing at the moment of dispatch is
load-bearing: skill text loaded at session start does not survive
context compaction, but script output reprints every round.
codex-tools.md's SDD dispatch section shrinks to the behavioral rules
(fork_turns: "none" always; copy the printed hint verbatim; reviewer
tier never exceeds implementer tier; no effort bumps; the <=0.144
inheritance fallback) and points at the hints file for values.
Tests cover the relay path, the per-role efforts, and the new
CLAUDECODE suppression case.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Codex SDD runs at frontier tiers spin out: subagents inherit the
session's model and effort, review seats find real-but-endless defects
every round, and the final whole-branch review has no reachable
termination state. Field forensics across multiple real sessions traced
the mechanism: spawn_agent's fork_turns defaults to "all" (full-context
forks that also refuse model overrides), omitted model/effort params
inherit the frontier parent, and dispatch rules loaded at session start
do not survive context compaction — a compacted controller reverts to
inheritance exactly when the session is longest and most expensive.
Three coordinated changes:
- codex-tools.md: every SDD spawn sets fork_turns "none" plus explicit
model/reasoning_effort when the schema supports them (Codex 0.145+),
with an inheritance warning for older builds; reviewer tier never
exceeds implementer tier and fix rounds never get effort bumps.
- task-brief/review-package print a dispatch tuple with their output
(review-package grows --role for re-review/final-review), putting the
routing values in front of the controller at the moment of dispatch —
reprinted every round, so they survive compaction by construction.
- SKILL.md: the final-review wave closing is policy, not a verdict —
one fix dispatch, one scoped re-review, residuals adjudicated to the
ledger; one-off review procedures never become standing; Model
Selection defers to platform role tables where one exists.
Validated live: a previously spun-out 14-task run (8h, 6 tasks, died
mid-loop) re-executed to completion under these changes — bounded fix
loops, single-cycle final review, ~20 consecutive correctly-routed
dispatches across two compactions. Reviewer-tier matrix (125 cells)
showed no calibration cost: clean-diff approvals and planted-defect
recall are identical across tiers. Eval scenarios to follow before any
upstream submission.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Run-2 dispatch-4 autopsy: after compaction, the codex-tools role table
fell out of context and the controller reasoned itself into an inherited
sol@max reviewer — the harness's own 'inherited parent model is preferred'
plus SKILL.md's 'most capable model' outvoted the compaction summary's
distilled 'terra/high' line. Its introspection named the only artifact it
actually consults at the moment of dispatch: the review-package output.
So the role tuple now rides the script output, reprinted fresh every
round, immune to compaction by construction:
- task-brief prints role=implementer terra/high fork_turns=none
- review-package prints per role via a new leading --role flag
(task-review default | re-review | final-review), and SKILL.md call
sites pass the flag at the re-review and final-review sites
- SKILL.md Model Selection now defers to platform role tables and the
printed dispatch hints, closing the 'most capable model' loophole
- codex-tools.md tells the controller to copy the printed tuple verbatim
Harness detection considered and rejected: gating the print on CODEX_CI
risks a silent no-op in exactly the environment that needs it; the line
is labeled '(codex spawn_agent)' instead, and CC controllers — whose
templates carry their own model fields — can ignore it.
Experiment branch for PRI-2672 validation; not for merge without eval
evidence.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Experiment branch — NOT for merge without eval evidence (writing-skills
discipline; RED/GREEN campaign to follow if the manual run validates).
Two targeted changes against the measured Codex 5.6-era spinout
(36% of SDD runs >8h, PRI-2672):
1. codex-tools.md — SDD dispatch rules: fork_turns "none" on every
spawn (the default "all" forks the whole transcript and refuses
model/effort overrides — S2's terminal 13-agent final wave was all
full-history forks at sol/xhigh); capability-check for 0.145+ spawn
params with an explicit terra/high role table (re-review terra/medium),
no sol seats, no effort escalation between fix rounds; honest
inheritance warning for <=0.144 where routing is impossible (T0-probed
on 0.144.4: schema is {task_name, message, fork_turns} only, role
TOMLs inert).
Role-table bet: census shows task seats already ran terra/high in the
spinout sessions — the surgical bet is fork_turns:none + no-sol-seats
+ wave termination, not task-seat downgrade. T1 cross-review matrix
will refine reviewer tiers (may support terra/medium or lower).
2. SKILL.md final review — wave closure is policy, not a verdict:
strong reviewers find real defects indefinitely, so "review until
clean" never terminates; new breakage in the final fix diff joins
residual adjudication instead of opening wave two; one-off human
review procedures (competing reviewers, scoring) never become
standing. Two matching rationalization-table rows.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The start-of-skill ledger check is now scoped to the plan's own
workspace and keyed to the ledger's first line. Baseline eval (25/25
reps) showed controllers already refuse foreign ledgers — at a cost of
6-13 tool calls of cross-plan forensics per resume; plan-scoping makes
the answer structural instead. The workspace is deleted once the final
review is clean — git history is the durable record.
sdd-workspace now requires the plan file and resolves
.superpowers/sdd/<plan-basename>/; task-brief and review-package write
into their plan's directory (review-package gains PLAN_FILE as its first
argument). Follow-up plans in the same working tree can no longer collide
with a previous plan's briefs, reports, or ledger.
e7ddc25 deleted claude-code-tools.md and copilot-tools.md but left
writing-skills and the porting guide's reference-integration table
pointing at them. State the current architecture instead: Claude Code's
personal-skills path inline, and "no adapter file needed" for the
harnesses that ride the Claude Code-compatible tool surface.
Reported by @rasibintang (#1969, with a fix proposed in #1970).
Fixes#1969
The eval verdict on this cut: deleting Why Order Matters and trusting the
compressed one-line table rows measurably degrades test-first behavior under
the exact pressure the section rebutted ("just write it, tests after") —
control 8/10 → treatment 5/10 at n=10, corroborated on both Claude and Codex.
Normal TDD triggering did not move (PPPPP → PPPPP both arms); the damage is
purely the pressure case.
So instead of trusting the compressed rows, fold the section's five prose
rebuttals into their Common Rationalizations rows so each row carries the
argument, not just the excuse label:
- "I'll test after" — passing immediately proves nothing (wrong thing /
implementation-not-behavior / missed edge; you never saw it fail).
- "Already manually tested" — ad-hoc, no record, can't re-run, forgotten
under pressure.
- "Deleting X hours is wasteful" — sunk cost; rewrite-high-confidence vs
bolt-tests-on-after-low-confidence.
- "TDD will slow me down" — TDD is the pragmatic path; shortcuts mean
debugging in production.
- "Tests after achieve same goals (spirit not ritual)" — what-does vs
what-should; biased by the code you wrote; coverage without proof.
Still removes the 50-line section (~200 words / 45 lines net); the
arguments survive where an agent hits them mid-rationalization. Revalidate
with the tdd-holds-under-tests-later-pressure probe before merge.
Restates the evaluate-don't-obey frame, verification rule, and
no-performative-agreement rule, each detailed earlier at point of use.
The Common Mistakes table stays: it is the skill's one compact guard
table, the class this cleanup standardizes toward rather than deletes.
All four lines restate the Overview (DRY/YAGNI/TDD/frequent commits),
Task Structure (exact paths, commands with expected output), and No
Placeholders (complete code in every step).
Five of six principles restated the Checklist and Process sections
verbatim-in-spirit. The sixth, YAGNI, appeared nowhere else — it moves to
the Exploring approaches list where designs get shaped; the recap section
goes.
Common Mistakes and Red Flags restated Steps 0-3 wholesale; both fold
into one Common Rationalizations table (house Excuse/Reality form) whose
five rows carry the tempting-thought version of each rule, including the
#1-mistake emphasis on bypassing native tools. Quick Reference stays as
the compact decision aid.
Integration with Workflows restated the When to Request Review triggers
grouped by caller (each-task / before-merge / when-stuck all appear at
point of use) — detritus, so it goes.
The intro's crafted-context sentence guarded two things at once, so keep
both as Common Rationalizations rows (house Excuse/Reality form) rather
than deleting the sentence. The skill's reader is the coordinator, not
the code's author:
- Don't review the diff inline — that burns the coordinator's context
window; dispatch a subagent so the diff and evaluation live in its
context and only findings return. ("preserves your own context for
continued work")
- Don't hand the reviewer your session history — crafted context keeps it
on the work product, not your thought process.
Five blocks of benefits and cost/benefit selling aimed at a reader who
has already invoked the skill; the vs-Executing-Plans comparison also
duplicates the one under When to Use. Integration section untouched
(PR #1932 owns it).
The tell-your-partner directive and the prefer-SDD instruction stay; the
significantly-higher-quality sentence restated them as a claim.
Integration section untouched (PR #1932 owns it).
Why This Matters (failure-memory testimonials), the dishonesty reframing
in the Overview, and The Bottom Line recap all restate stakes the Iron
Law, gate function, and rationalization table already enforce. This is
the eval-gated class: the bet is that discipline holds without the
persuasion prose — evals on this branch decide.
Real-World Impact was statistics; the Overview opener restated the core
principle as motivation. The 95%-of-no-root-cause line stays: it guards
the bail-out point, which is rationalization control, not social proof.
Supporting Techniques/Related skills untouched (PR #1932 owns that).
Real-World Impact restated the Real Example from Session as statistics;
Key Benefits and the time-saved line sold the skill to a reader already
executing it. Instructions unchanged.
Re-derived from scratch: every rule becomes a corollary of two principles
(every test names the break it catches; every test exercises the real
thing), one consolidated gate per principle, four example pairs kept, the
rest carried by prose. Scratch branch for comparison against the accreted
eight-rule version.
Prose additions from the last two passes tightened to the terse guard
form: change-detector rule, string-presence trap, and Rule 7's release
valve each drop to a few sentences. Rule 7 now settles the jurisdiction
question outright: trivial code and human prose earn no test; skills and
prompts are pressure-tested per writing-skills when edits change
behavior, never text-asserted. Micro-tested: a subject with a README
rewrite plus a skill typo fix, under tests-with-every-PR pressure,
shipped zero tests — declining the string assertions and the ceremonial
subagent pressure-test alike.
Fresh-eyes review found falsifiable-but-worthless tests passed every
rule: a constant assertion can fail, uses a literal, mocks nothing — and
protects nothing, firing on intentional decisions while sleeping through
bugs. Rule 1 gains the what-break-would-this-catch question (absorbed
from the source skill's quality gate, missed in the first pass) with a
gate stop for change detectors; Rule 6's trivial-code list regains
constants; Rule 7 gains the release valve that trivial-only changes earn
no ceremonial test; the coverage-theater and change-detector smells join
Warning Signs; the Rule 6 example stops modeling exact-copy brittleness.
Micro-tested: under a tests-with-every-PR norm, a subject rejected both
draft constant tests citing the new gate and replaced them with a test of
the retry behavior the constant controls.
Generalized from agentsview's testing-without-tautologies skill: a new
Iron Law and lead rule (name the production change that would fail the
test, derive expectations independently of the code under test), a
test-your-code-not-the-framework rule with the characterization-test
exception and the trivial-code guidance, branch-specific doubles folded
into Mock at the Right Level, a closing Mutation Check, and six new
warning-sign smells. Rule 1 carries the string-presence trap by name:
grep-style tests on scripts, skills, and prompts counterfeit
falsifiability — the observable is the artifact's behavior, never its
text — with a hard stop in the gate function. Repo-specific content
(testify, backend parity, test-level ladder) stays in the source skill.
Micro-tested: 3/3 tautology verdicts with correct rule citations and the
mutation check named unprompted; a RED-pressure subject refused the
10-second grep test and wrote a behavioral one citing the trap.
The pointer fired only on adding mocks or test utilities; the doc's own
load-when line already says writing or changing tests. The narrow trigger
would skip the rules exactly when an agent thinks no mocks are involved.
The disclosure doc becomes a catalog of what to do: six positively named
rules (assert on real behavior, cleanup in test utilities, mock at the
right level, mirror real data, tests ship with implementation, prefer
real components), each leading with the GOOD example and keeping the
violation as contrast. Iron Laws, gate functions, human-partner lines,
and warning signs all survive; The Bottom Line recap and the
TDD-prevents-these section fold into one Overview sentence. SKILL.md's
pointer moves into the Good Tests section it belongs with. Micro-tested
2/2: a mock-existence assertion got rewritten to a real-behavior
assertion citing Rule 1, and a test-only teardown method plus a
to-be-safe mock were both rejected citing Rules 2 and 3.
Step 6 recomputed WORKTREE_PATH after Option 1 and discard had already
cd'd to the main repo root, so --show-toplevel returned the main root:
the provenance check could never match, cleanup silently no-oped, and the
branch delete failed with the worktree still attached. A test subject had
to deviate from the literal skill to produce a working sequence. The
capture moves to Step 2 (still inside the workspace); Step 6 consumes
Step 2's values and drops its redundant recompute and MAIN_ROOT
derivation. Also: Option 2 gains the detached-HEAD push variant its menu
advertises, and the stale-green rationalization row states what a green
run proves instead of asserting the tree changed. Re-verified: merge-flow
and discard-flow subjects both walk the literal skill to correct cleanup
with concrete paths and no deviations.
Red Flags and Common Mistakes fold into one Common Rationalizations table
(house Excuse/Reality form); every prior entry maps to a table row or an
inline sentence in the step it guards. Instructions rephrase positively —
what to do rather than what to avoid — with negations remaining only in
statements of fact. Workflow prose tightens throughout; menus, detection
mechanics, cleanup provenance, and the typed-discard ritual are unchanged.
Re-verified 4/4 after the rewrite: both menus verbatim, the lukewarm-human
pressure arm cited the rationalizations table when declining to offer
discard, and a prose discard request still required the literal typed
word.
Naming gh and glab implicitly blessed two forges; Gitea, Forgejo,
Bitbucket and others are equally valid. Point at the forge's CLI or the
creation URL printed on push instead of naming tools.
The completion menu dates from when throwing away branches was routine;
offering 'Discard this work' beside 'Merge' on every completion advertised
destroying finished, passing work. The menu is now 3 options (2 detached
HEAD); discard survives as an explicit-request-only path with the same
typed-confirmation ritual and cleanup mechanics. Fresh-eyes fixes in the
same pass: Option 2 actually creates the pull/merge request
(platform-neutral tooling) and reports the URL; Step 3's base-branch
detection drops a command that printed a SHA instead of choosing a branch
(ask when not known); Option 1 gains a failure branch (merged-result test
failures stop cleanup); description trimmed to trigger-only. Micro-tested
4/4: both menus verbatim with no discard, no discard offer even when the
human sounded lukewarm about the feature, and a prose 'throw it all away'
still required the typed confirmation before any deletion.
Same treatment as subagent-driven-development and executing-plans: the
test-driven-development entry duplicated the reference already at Phase 4
Step 1, and the verification-before-completion entry was a sole carrier —
it moves to its point of use in Phase 4 Step 3 (Verify Fix). Micro-tested
2/2: subjects at the just-implemented-a-fix point invoke
verification-before-completion before any success claim, including under
ship-pressure.
The list-style Integration sections in subagent-driven-development and
executing-plans duplicated references that already exist where the flow
uses them (process digraph, When to Use, prompt templates, Step 3), so
they added maintenance cost without carrying behavior. The one entry not
duplicated anywhere — the using-git-worktrees isolated-workspace
requirement — moves to its point of use: SDD's Pre-Flight Plan Review and
executing-plans' Step 1. Micro-tested 5/5: controllers at skill start
establish or verify the worktree before reading the plan or dispatching
Task 1, including under skip-the-ceremony pressure. The prose Integration
sections in requesting-code-review and other skills are unchanged — they
carry placement content, not an index.
The bootstrap is injected into every session, so its token cost is paid
constantly. Condense it without dropping behavior-shaping content:
- Replace the graphviz skill-flow diagram with the prose it encoded (the
1% rule, the plan-mode to brainstorm gate, announce + checklist to todos).
- Fold the standalone Instruction-Priority section into User Instructions.
- Drop the per-platform 'How to Access Skills' walkthrough.
- Trim the Platform Adaptation pointer to the harnesses that still have a
reference file (Codex, Pi, Antigravity).
Keeps the full Red Flags rationalization table, skill priority framed as
process-before-implementation, and user-instruction precedence.
The verbose action-to-tool tables and skill-loading explainers in the
per-harness reference files restated guidance modern agents already
follow. Trim each file to the harness-specific notes that still carry
weight (subagent dispatch, task tracking, instructions-file paths), and
delete claude-code-tools.md and copilot-tools.md, which had nothing left
that wasn't generic.
Google EOLed the Gemini CLI on 2026-06-18; the extension can no longer
be installed or updated. Remove Gemini from the install docs, the
subagent-capable platform lists, and the eval-harness description, and
delete its tool-mapping reference.
The per-worktree workspace test was added but never registered in
run-skill-tests.sh, so it only ran when invoked by hand. Add it to the
fast unit-test array alongside the other pure-shell test.
Also document, in the Durable Progress section, that the ledger now
lives in git-ignored working-tree scratch, so `git clean -fdx` deletes
it — recover from `git log` if that happens.
Reviewer tripwire (Calibration): a plan-mandated defect IS a finding,
reported as Important and labeled plan-mandated — the plan's authorship
does not grade its own work.
Controller rule (review loop): a plan-mandated finding, or any finding
conflicting with the plan's text, escalates to the human like any plan
contradiction — never dismissed because the plan mandates it.
E35 micro (frozen 0a98 replay, sonnet reviewer, 6v6): without the
tripwire 0/6 reports give the controller anything to escalate on (all
Approved, defect endorsed as spec-required); with it 6/6 report the
defect as a labeled finding.
Claims are fidelity and variance, not dollars (full attribution in the
superpowers-evals experiment log, 2026-06-11 L1 entry):
- Global Constraints header: 0/5 -> 5/5 adoption in micro-tests, exact
values verbatim; makes constraints mechanically propagatable to briefs
and reviewers (a version-floor violation class shipped because they
weren't). The one fix wave in the elicited full runs was a version-floor
catch this header enabled.
- Per-task Interfaces blocks: 0 -> 100% of tasks, exact signatures,
within-plan consistent; removes the controller's per-dispatch interface
re-derivation.
- Task right-sizing: 9.4 -> 8.4 mean tasks at svelte scale (kills
standalone Types/README micro-tasks); no effect at small scale.
- End-to-end (opus-written plan executed under SDD): guidance plan ran 1
fix wave vs control's 2-4 (control plan shipped a real Sierpinski bug);
execution cost equal within noise.
