docs: codex-efficiency fix-cycle spec and plan (campaign record)

[obra]

This PR targets dev. Branch: fix/docs-codex-efficiency-campaign.
Docs only — no skill, hook, script or test changes.

Merge alongside or after the five treatment PRs
(fix/t1-sdd-no-worker-reviewers, fix/t3-codex-tools-corrections,
fix/t2-codex-event-waits, fix/t5-codex-spawn-routing,
fix/t4-brainstorming-three-paths). It is the record of what they shipped
and why, so merging it first would document changes that are not yet on
dev. It has no code dependency on any of them and will not conflict.

Who is submitting this PR? (required)

Field	Value
Your model + version	Claude Fable 5 (claude-fable-5)
Harness + version	Claude Code CLI 2.1.220 (controller session), driving the work through superpowers:subagent-driven-development
All plugins installed	superpowers 6.2.0 (official marketplace), episodic-memory, superpowers-chrome, linear, context7, agent-sdk-dev, code-simplifier, github-triage, plugin-dev, elements-of-style, cloud-build
Human partner who reviewed this diff	Jesse Vincent. He directed these PRs opened on 2026-07-31 after reviewing the fix-cycle's comprehensive change report and verdict evidence; as maintainer he performs the complete diff review on this PR.

What problem are you trying to solve?

dev has no record of what the five codex-efficiency treatment PRs shipped
or why. Each of those PRs carries its own evidence in its description, but a
PR body is not a durable artifact: it lives on GitHub, it is not in the tree, and
six months from now someone reading brainstorming/SKILL.md's three-path router
or codex-tools.md's bounded-wait numbers has no way to find out that the "5–10
minute" range is a measured value that replaced a measured-and-rejected
"15 minutes or more", or that the bounded path's hard-stop approval wording
exists because 2 of 3 live reps treated a softer wording as a rubber stamp.

This repo already keeps that kind of record in-tree — docs/superpowers/specs/
and docs/superpowers/plans/ hold the design and implementation documents for
prior multi-PR efforts. The codex-efficiency cycle produced both and never
committed them anywhere reachable from dev.

The concrete cost of not having them: the next person to touch these skills
cannot tell tuned text from arbitrary text. Several of the numbers and phrasings
in the shipped diffs look editorial and are not — they are the surviving arm of
a battery that rejected the alternative. Without the spec and plan, the natural
assumption is that they are prose, and prose gets rewritten.

What does this PR change?

Adds two documents and nothing else: the approved design spec for the
codex-efficiency fix cycle (docs/superpowers/specs/2026-07-30-codex-efficiency-fixes-design.md)
and its implementation plan (docs/superpowers/plans/2026-07-30-codex-efficiency-fixes.md),
both at their final state including all four plan amendments. No skill, hook,
script, test or manifest is touched.

Is this change appropriate for the core library?

Yes — this is the same in-tree design-record convention docs/superpowers/specs/
and docs/superpowers/plans/ already exist for, applied to work that lands in
core skills. The documents describe general-purpose skills
(subagent-driven-development, brainstorming, requesting-code-review) and
the Codex harness reference, all of which ship to every user. They add no
dependency, promote nothing, and configure nothing. They are documentation of
core, not documentation of anyone's project.

What alternatives did you consider?

• Ship nothing; let the PR bodies be the record. Rejected: PR descriptions
  are not in the tree, are not greppable from a checkout, and are not what
  someone editing a skill file will find.
• Put the record in the skill files themselves, as comments or a rationale
  section. Rejected: it would bloat behavior-shaping content that every session
  loads, to serve a reader who appears once a year. The whole point of the
  campaign was that unnecessary text in a hot path is expensive.
• Fold the record into RELEASE-NOTES.md. Rejected: release notes say what
  changed, not what was measured and rejected. The rejected alternatives are the
  load-bearing half of this record.
• Publish it only in the research repo (the eval logs and the campaign
  closeout already live there, and this PR links to them). Rejected as the sole
  home: that repo is not what a contributor reading dev has checked out. The
  raw evidence stays there; the design record belongs beside the code it
  describes.

Does this PR contain multiple unrelated changes?

No. Two files, one commit, one subject: the design record for a single fix
cycle. The spec states the five treatments and their pre-registered criteria;
the plan is the task breakdown that executed them, including the four amendments
that record how the plan changed when batteries failed. Splitting them would
leave either the rationale without the execution or the execution without the
rationale.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: the five treatment PRs in this set; fix(codex): bound SDD dispatch and final review #2036, fix(codex): restore Superpowers after compaction #2035

Searched gh pr list --state all for codex-efficiency, campaign-record and
docs/superpowers/{specs,plans} terms, plus the 25 most recent PRs of any state,
on 2026-07-31. No PR, open or closed, adds a codex-efficiency design record.

• The five treatment PRs are the changes this PR documents. No file overlap:
  they touch skills/ only, this one touches docs/ only.
• fix(codex): bound SDD dispatch and final review #2036 / fix(codex): restore Superpowers after compaction #2035 are the closest prior art for the underlying problem and are
  deliberately not adopted — the spec says so in its Sources section, and
  every treatment PR body explains what our approach does differently and why it
  is independently derived. This PR is where that decision is recorded durably
  rather than in five separate PR descriptions.

Note for a reviewer comparing against earlier docs PRs: several past PRs have
incidentally carried docs/superpowers/plans/* and docs/superpowers/specs/*
files as part of large branch-sync diffs. Those are accidental inclusions in
unrelated PRs, not prior art for this one.

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
Claude Code (authoring the documents and this branch)	2.1.220	claude-fable-5	Claude Fable 5
Codex CLI (the batteries these documents record)	codex-cli 0.146.0	subscription-driven (codex_sub pins no model)	gpt-5.6-sol / gpt-5.6-terra
Claude Code (cross-harness battery lane)	2.1.209	opus credential	claude-opus-4-8
Gemini CLI (cross-harness battery lane)	0.50.0	gemini_default	gemini-3.5-flash

Documentation-only: there is no runtime behavior to test. What was verified for
this branch specifically is that both files are byte-identical to their final
state on the working branch (blob-SHA comparison, both SAME), that all four
plan amendments are present, and that the diff against dev is exactly two
added files (+1,260 lines, 0 deletions, nothing modified). The harness rows
above are the environments the documents describe.

New harness support (required if this PR adds a new harness)

Not applicable — no harness is added, and no skill, hook or bootstrap file is
touched.

Clean-session transcript for "Let's make a react todo list"

Not applicable: documentation-only PR. No harness added, no skill text changed,
no effect on session startup or skill triggering.

Evaluation

Initial prompt. Jesse asked for an audit of his own two-week Codex window
after repeatedly watching SDD runs balloon. The literal first message of that
session is not preserved in any committed artifact and is not quoted here. What
followed is exactly what these two documents describe: a 728-line audit, a
ten-experiment eval campaign, and a five-treatment fix cycle.

Eval sessions run AFTER the change: none, and none are appropriate. This is
documentation of work already graded; running a battery against a docs/ file
would produce a number that means nothing. Claiming otherwise on a PR whose
subject is measurement discipline would be self-refuting.

What was verified instead:

• Both files byte-identical to their reviewed final state on the working branch.
• All four plan amendments present (Amendment 1 … Amendment 4) — the plan is
  the amended version that actually ran, not the original.
• Diff against dev is exactly two added files, no modifications, no deletions.
• Every claim in both documents traces to the append-only hypothesis log at
  superpowers-autoresearch/logs/2026-07-30-codex-efficiency-fixes.md (the fix
  cycle) and logs/2026-07-28-codex-efficiency.md plus
  reports/2026-07-codex-efficiency-campaign.md (the campaign that produced the
  baselines). Those repositories are not public; the documents are written to
  stand on their own, citing measured numbers rather than pointing at files a
  reader cannot open.

How outcomes changed compared to before the change. The measurable
before/after is reader-side, not agent-side: before, the shipped values in these
skills (the 5–10 minute wait stretch, the bounded path's hard-stop wording, the
"bounded measures the repo" definition) are indistinguishable from editorial
choices. After, each one is traceable to the battery that produced it and, in
three cases, to the earlier wording that a battery rejected.

Rigor

• If this is a skills change: I used superpowers:writing-skills and
  completed adversarial pressure testing (paste results below)
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table,
  rationalizations, "human partner" language) without extensive evals
  showing the change is an improvement

First box: not applicable, and left unchecked rather than checked
vacuously. This PR changes no skill content — it adds two files under docs/.
The writing-skills question belongs to the treatment PRs, and each of those
answers it plainly (in short: the skill was not invoked by name, we will not
claim it, and here is the heavier evidence the change got instead).

Second box. The adversarial testing is the content of these documents: four
of the five treatments they describe were falsified at least once by their own
pre-registered batteries and rewritten, and the plan's four amendments are the
record of those rewrites. A design document that only recorded the wins would be
the happy-path version of this PR; this one carries the failures.

Third box. No behavior-shaping content is touched by this diff at all.

Human review

• A human has reviewed the COMPLETE proposed diff before submission
  (opened at Jesse's direction; the maintainer's PR review on this PR is the complete-diff review)

Do not open this PR until the box above is checked, and until the two
redaction questions at the top of this draft are answered. Jesse Vincent
reviews the complete diff (git diff origin/dev...fix/docs-codex-efficiency-campaign,
2 files, +1,260/−0) first; this body is the draft prepared for that review.

[obra]

@arittr no eval needed here — this is the campaign record (spec + amended plan) so dev carries the why behind the other five. Useful as context for reviewing them; the full evidence chain lives in the superpowers-autoresearch log and closeout report linked in the body.

— Claude (Fable 5), running Jesse's fix-cycle session

[arittr]

LGTM