summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2026-09-18 18:38:59 +0000
committerJesse Vincent <jesse@fsck.com>2026-09-18 18:38:59 +0000
commit8412aaf0385cbfd850675093f01b16c88052f268 (patch)
tree88ae48d06c4d104d65e35d345e65f7c210189564 /docs
parentb36e0829c6d0140e93cfef2ca599b1b07d4a7797 (diff)
Release v6.4.0: diagnosing-superpowers and movie skills, Native execution, OpenCode 2.0, Muse, and Qwen Code supportrelease/v6.4.0
Everything on dev since the v6.3.0 merge-back (777ceb5), as one commit. Full notes: RELEASE-NOTES.md, v6.4.0 section. Claude-Session: https://claude.ai/code/session_01PRUnVUm4g4EcP9eNjAiT2B
Diffstat (limited to 'docs')
-rw-r--r--docs/README.opencode.md125
-rw-r--r--docs/porting-to-a-new-harness.md16
-rw-r--r--docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md1512
-rw-r--r--docs/superpowers/plans/2026-09-11-movie-committee-repairs.md105
-rw-r--r--docs/superpowers/plans/2026-09-11-movie-review-fixes.md60
-rw-r--r--docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md530
-rw-r--r--docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md72
-rw-r--r--docs/testing.md20
8 files changed, 2408 insertions, 32 deletions
diff --git a/docs/README.opencode.md b/docs/README.opencode.md
index 11da854..419a8a6 100644
--- a/docs/README.opencode.md
+++ b/docs/README.opencode.md
@@ -4,7 +4,11 @@ Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
## Installation
-Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
+OpenCode V2 requires version 2.0.4 or later.
+
+### OpenCode V1
+
+Use the existing V1 plugin configuration:
```json
{
@@ -12,15 +16,27 @@ Add superpowers to the `plugin` array in your `opencode.json` (global or project
}
```
-Restart OpenCode. The plugin installs through OpenCode's plugin manager and
+### OpenCode V2 (2.0.4 or later)
+
+Use the V2 plugin configuration:
+
+```json
+{
+ "plugins": ["superpowers@git+https://github.com/obra/superpowers.git"]
+}
+```
+
+For a local V2 installation, configure the repository directory containing
+`index.js`. OpenCode 2.0.4 and 2.0.7 reject a configured direct JavaScript-file
+path. Discovered plugin symlinks remain supported.
+
+Restart OpenCode. V2 uses the `opencode` command; `opencode2` may be available
+as an alias. The plugin installs through OpenCode's plugin manager and
registers all skills.
Verify by asking: "Tell me about your superpowers"
-OpenCode uses its own plugin install. If you also use Claude Code, Codex, or
-another harness, install Superpowers separately for each one.
-
-### Migrating from the old symlink-based install
+### Migrating from the old symlink-based install (V1)
If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
@@ -78,7 +94,10 @@ description: Use when [condition] - [what it does]
Create project-specific skills in `.opencode/skills/` within your project.
-**Skill Priority:** Project skills > Personal skills > Superpowers skills
+**V2 Skill Priority:** Project skills > Personal skills > Superpowers skills. On
+tested V1 1.18.31, bundled Superpowers skills take precedence when a personal
+or project skill has the same name; use distinct names for personal and project
+skills. This behavior is unchanged by the migration.
## Updating
@@ -87,24 +106,45 @@ and Bun versions pin that resolved git dependency in a lockfile or cache, so a
restart may not pick up the newest Superpowers commit. If updates do not appear,
clear OpenCode's package cache or reinstall the plugin.
-To pin a specific version, use a branch or tag:
+To pin a specific version, add a tag or commit to the spec (same form for the
+V1 `plugin` key and the V2 `plugins` key):
```json
{
- "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
+ "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.4.0"]
}
```
+On V2, pin `v6.4.0` or later; `v6.3.0` and earlier releases load only on V1.
+
## How It Works
-The plugin does two things:
+The plugin does two things, using host-flavor-specific APIs:
+
+1. **Registers the skills directory** so OpenCode discovers all superpowers skills without symlinks or manual config.
+ - **V1:** via the `config` hook, injecting into `config.skills.paths`
+ - **V2:** via the `setup()` function using `ctx.skill.transform()` (V2 native API, confirmed active at runtime)
+2. **Injects bootstrap context** with a flavor-specific tool mapping: V1 sessions get the V1 tool names below, and V2 sessions get the V2 names.
+ - **V1:** via `experimental.chat.messages.transform` hook
+ - **V2:** via `ctx.session.hook("context")` — the V2 equivalent (confirmed active at runtime)
-1. **Injects bootstrap context** via the `experimental.chat.messages.transform` hook, adding superpowers awareness to every conversation.
-2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
+Controller sessions receive the using-superpowers bootstrap in transient model
+context. Delegated child sessions keep access to native skills but do not receive
+the controller bootstrap. A manual fork without a parent session keeps controller
+behavior. When V2 native compaction retains earlier user messages (the default
+`compaction.keep.tokens` budget), the bootstrap goes into the first retained user
+message ahead of the checkpoint, as in an uncompacted session. When compaction
+removes all user messages, the plugin appends a transient bootstrap message after
+the checkpoint. Saved history is unchanged either way.
+
+If session lookup fails, the plugin keeps bootstrap for that request and retries
+on the next request. Failed lookups are not cached as controller decisions.
### Tool Mapping
-Skills speak in actions rather than naming any one runtime's tools. On OpenCode these resolve to:
+Skills speak in actions rather than naming any one runtime's tools. The bootstrap maps them to the tools your OpenCode flavor actually exposes.
+
+**V1 (`opencode` 1.x):**
- "Create a todo" / "mark complete in todo list" → `todowrite`
- `Subagent (general-purpose):` template → OpenCode's `task` tool with `subagent_type: "general"` (or `"explore"` for codebase exploration)
@@ -115,15 +155,43 @@ Skills speak in actions rather than naming any one runtime's tools. On OpenCode
- "Search file contents" / "find files by name" → `grep`, `glob`
- "Fetch a URL" → `webfetch`
-(Verified against the installed OpenCode CLI's tool inventory.)
+**V2 (`opencode` 2.0.4 or later; `opencode2` may be available as an alias):**
+
+- "Create a todo" → V2 has no todo tool of any kind; the mapping tells the model to track the plan in a markdown file (or the harness's plan facility) instead
+- `Subagent (general-purpose):` template → OpenCode's `subagent` tool with `agent: "general"` (or `"explore"`); pass `sessionID` to continue a previous subagent
+- "Invoke a skill" → OpenCode's native `skill` tool
+- "Read a file" → `read`
+- "Create, edit, or delete files" → use `patch` with `patchText` when available; otherwise use `write` to create or overwrite files, `edit` for targeted changes, and `shell` for deletion
+- "Run a shell command" → `shell` (`command`, `workdir`, `timeout`, `background`)
+- "Search file contents" / "find files by name" → `grep`, `glob`
+- "Fetch a URL" → `webfetch`
+- "Search the web" → `websearch`
+
+In short, V2 renamed `task` → `subagent` (the agent name moved from `subagent_type` to `agent`, and continuation happens by re-invoking with `sessionID`), `apply_patch` → `patch`, and `bash` → `shell`, and it dropped the todo tool entirely. The available mutation tools depend on the selected model: `patch` is available for selected GPT model IDs, while other models use `write` and `edit`.
+
+(V1 list verified against the installed OpenCode 1.18.x CLI's tool inventory; V2 list verified against the OpenCode 2.0.4 and 2.0.7 host contracts.)
## Troubleshooting
### Plugin not loading
-1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
-2. Verify the plugin line in your `opencode.json` is correct
-3. Make sure you're running a recent version of OpenCode
+**V1:** Check OpenCode logs:
+
+```
+opencode run --print-logs "hello" 2>&1 | grep -i superpowers
+```
+
+**V2:** Plugins load in the background server, whose logs `--print-logs` only
+shows with `--standalone`:
+
+```
+opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers
+```
+
+Or inspect `~/.local/share/opencode/log/opencode.log`, filtering for `role=server`.
+
+Also verify the plugin path in your `opencode.json` is correct and that you're
+running a recent version of OpenCode.
### Windows install issues
@@ -137,11 +205,23 @@ package:
npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
```
-Then use the installed package path in `opencode.json`:
+Then use the absolute path of the installed package in `opencode.json` for your
+OpenCode version. OpenCode does not expand `~`; a `~/...` entry is treated as a
+package name, not a local directory.
+
+**V1:**
+
+```json
+{
+ "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
+}
+```
+
+**V2 (2.0.4 or later):**
```json
{
- "plugin": ["~/.config/opencode/node_modules/superpowers"]
+ "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
}
```
@@ -153,11 +233,12 @@ Then use the installed package path in `opencode.json`:
### Bootstrap not appearing
-1. Check OpenCode version supports `experimental.chat.messages.transform` hook
-2. Restart OpenCode after config changes
+- **V1:** Check OpenCode version supports `experimental.chat.messages.transform` hook. Restart OpenCode after config changes.
+- **V2:** The plugin uses `ctx.session.hook("context")` for bootstrap injection. Verify the plugin loaded via `opencode api get /api/plugin`. Restart with `opencode service restart` after config changes. The `opencode2` command may be available as an alias.
## Getting Help
- Report issues: https://github.com/obra/superpowers/issues
- Main documentation: https://github.com/obra/superpowers
-- OpenCode docs: https://opencode.ai/docs/
+- OpenCode V2 docs: https://opencode.ai/v2/docs/
+- OpenCode V1 docs: https://opencode.ai/docs/
diff --git a/docs/porting-to-a-new-harness.md b/docs/porting-to-a-new-harness.md
index 4ae9603..ce37418 100644
--- a/docs/porting-to-a-new-harness.md
+++ b/docs/porting-to-a-new-harness.md
@@ -711,6 +711,18 @@ Then:
- If neither works, the harness cannot be cleanly supported yet — **say so**
and raise it, rather than hand-editing the user's config.
+- **Packagers can strip executable bits — skill prose invokes bundled scripts
+ through their interpreter.** Some marketplace packaging and install paths
+ lose Unix file modes: the Codex marketplace cache delivered the SDD helpers
+ as `0644` (#2040, #2134), and the MiniMax Code marketplace ships every file
+ as mode `600`. A bare `scripts/foo.sh` or `./foo.js` in a skill then fails
+ with `Permission denied` on that harness even though the repo's tree records
+ `100755`. So every script invocation in `skills/**/*.md` is spelled through
+ its interpreter — `bash scripts/start-server.sh …`, `bash
+ scripts/review-package …`, `node ./render-graphs.js …` — and a script that
+ runs a sibling script needs the same treatment (#2134). Don't "tidy" the
+ prefixes away, and don't reach for a packaging-side `chmod`: the mode loss
+ happens on the consumer's side, so only the invocation form survives it.
- **Write install docs.** A `docs/README.<harness>.md` and/or a
`.<harness>/INSTALL.md` (see `docs/README.opencode.md` and
`.opencode/INSTALL.md`), plus an install section in the top-level `README.md`.
@@ -790,7 +802,7 @@ Use this as the live index; when in doubt, read the files, not this table.
| Copilot CLI | (shares Claude Code hook path; `COPILOT_CLI` env) | shell hook → `hooks/session-start` (`additionalContext`) | none needed (Claude Code–compatible tool surface) | `tests/hooks/` | — |
| Gemini CLI | `gemini-extension.json` + `GEMINI.md` | instructions file `@`-includes bootstrap + mapping | `references/gemini-tools.md` | — | `gemini extensions install` |
| Kimi Code | `.kimi-plugin/plugin.json` | manifest `sessionStart.skill` loads `using-superpowers` | inline `skillInstructions` in manifest | `tests/kimi/` | marketplace or `/plugins install` GitHub URL |
-| OpenCode | `.opencode/plugins/superpowers.js` (declared via root `package.json` `main`) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` plugin git URL |
+| OpenCode | `.opencode/plugins/superpowers.js` (root `package.json` `main` for package installs; root `index.js` re-export for the V2 directory form) | in-process: `config` hook registers skills dir; `experimental.chat.messages.transform` (V1) / `session.hook("context")` (V2) injects user message | inline in `superpowers.js` | `tests/opencode/` | `opencode.json` `plugin` (V1) / `plugins` (V2) git URL |
| pi | `.pi/extensions/superpowers.ts` | in-process: `resources_discover` registers skills; `context` event injects user message; lifecycle-flag + compaction-aware | `piToolMapping()` inline **and** `references/pi-tools.md` | `tests/pi/` | repo-root `package.json` fields |
## Appendix B — Gotchas that have bitten porters
@@ -822,6 +834,8 @@ Use this as the live index; when in doubt, read the files, not this table.
that mechanism *is* reading `SKILL.md` — say so explicitly in the mapping
(Part 5).
- **`.sh` on Windows.** Keep hook scripts extensionless (Part 7).
+- **Bare `scripts/foo.sh` in skill prose.** Packagers can strip exec bits
+ (Part 6). Invoke bundled scripts as `bash scripts/foo.sh` / `node scripts/foo.js`.
- **Unregistered version.** A new manifest not added to `.version-bump.json`
ships stale (Part 6).
- **Editing skills to fit the harness.** Never. The fix goes in the tool mapping.
diff --git a/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md b/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md
new file mode 100644
index 0000000..848e369
--- /dev/null
+++ b/docs/superpowers/plans/2026-08-27-diagnosing-superpowers.md
@@ -0,0 +1,1512 @@
+# Diagnosing Superpowers Skill Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship `skills/diagnosing-superpowers`, a pure-prose skill that helps a human partner pin down what went wrong in a superpowers session, reports what happened with `path:line` evidence, and on request exports a scrubbed bundle, files or finds a GitHub issue, and searches for similar local sessions.
+
+**Architecture:** One lean `SKILL.md` (workflow, hard rules, Red Flags) plus one file per subagent job under `prompts/`, per-harness session-store references under `references/`, and output recipes under `templates/`. No shipped scripts; the model does the work using `jq`/`python3`/shell it already has. Skill content is developed RED → GREEN → REFACTOR per `superpowers:writing-skills`: baseline scenarios first, skill written to the observed failures, re-run, loopholes closed.
+
+**Tech Stack:** Markdown skill files; bash structure test under `tests/`; subagent-run scenarios recorded in `CREATION-LOG.md`.
+
+**Spec:** `docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md`
+
+## Global Constraints
+
+- Pure prose skill: no scripts shipped under `skills/diagnosing-superpowers/`.
+- No invented harness formats. Field-level claims appear only in `references/claude-code-sessions.md` (verified against Claude Code 2.1.247 transcripts) and `references/codex-sessions.md` (verified against Codex CLI 0.147.0 / 0.149.0 rollouts). Every other harness goes through the discovery procedure in `references/other-harnesses.md`.
+- Skill files say "your human partner", never "the user".
+- `SKILL.md` description starts with "Use when", is third person, and contains no workflow summary. `SKILL.md` body is under 1,000 words (the structure test enforces this).
+- Shipped files contain no machine-specific absolute paths (`/Users/`, `/home/`) and no person's name. Session ids (UUIDs) are fine.
+- Workspace is `~/.superpowers/diagnosing-superpowers/<session-id>/`; the skill prints the path when it creates it and again in the report.
+- Session files are never modified, moved, or deleted.
+- Nothing is archived before the human partner has seen the scrub log and file list; nothing is posted to GitHub before the human partner has approved the exact text.
+- The skill never names a defect in superpowers or proposes a change to it. The single allowed statement about superpowers is the report's "Superpowers involvement: not indicated / possible / likely" line with its evidence.
+- Every finding cites `path:line`. Findings without a citation are dropped.
+- Context safety: never `cat` or `grep` a transcript for content; counts and line numbers first, then small fields from specific lines.
+- Commit messages end with the session trailer used on this branch: `Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7`.
+
+## Local fixtures (this machine only, never copied into shipped files)
+
+| Fixture | Session id | Characteristics |
+|---|---|---|
+| CC-huge | `7619e0b6-b592-4142-97b5-9dd7e9a61130` | Claude Code, 12 MB, one 1.3 MB line: context-safety scenario |
+| CC-compact | `373e29d1-2223-4e81-95e8-976c35c80040` | Claude Code, 14 MB, two manual compactions, 278 subagent transcripts: plan-adherence, repeated-work, cost scenarios |
+| CC-this | `982c4a8b-932c-4bf6-a8dd-c99529a54e90` | The live session that built this skill: skill-timeline (three `attributionSkill` values), live-session scenario |
+| CX-big | `019fe412-e876-7293-8369-51823c634878` | Codex rollout, 153 MB, `context_compacted`, `sub_agent_activity`, `turn_aborted`: Codex reference verification and retrieval scenario |
+| CX-sub | `01a043fe-6785-74c3-a4f8-67994723bbcb` | Codex subagent rollout (`thread_source: subagent`, `parent_thread_id`) |
+
+Absolute paths for these fixtures are recorded privately in the maintainer's SDD workspace, not in the repo.
+
+Executors on a different machine pick equivalents by the same characteristics (size, max line length, compaction present, subagents present) and note the substitution in `CREATION-LOG.md`.
+
+## File structure
+
+```
+skills/diagnosing-superpowers/
+ SKILL.md workflow, hard rules, quick reference, Red Flags
+ CREATION-LOG.md scenarios, baseline results, GREEN results, micro-tests
+ references/
+ claude-code-sessions.md where Claude Code stores sessions, field map, safe extraction
+ codex-sessions.md same for Codex
+ other-harnesses.md discovery procedure for unverified harnesses
+ prompts/
+ skill-timeline.md analyst: what fired when, missed/late triggers, other plugins
+ plan-adherence.md analyst: recovered plan vs. what happened
+ repeated-work.md analyst: duplicated reads/edits/commands/dispatches
+ stumbles.md analyst: errors, retries, reverts, corrections
+ quality-evidence.md analyst: tests, verification, commits, review handling
+ request-conflicts.md analyst: contradictory human instructions
+ cost-and-time.md analyst: tokens and wall-clock per turn/subagent/tool
+ scrub.md scrubber
+ scrub-audit.md independent scrub checker
+ similar-session.md per-candidate signature matcher
+ templates/
+ case.md case file the controller fills before dispatching
+ report.md report with REQUIRED slots
+ bundle-README.md README written into the export bundle
+ issue.md GitHub issue body
+tests/diagnosing-superpowers/
+ test-skill-structure.sh frontmatter, referenced files exist, no local paths/names, word budget
+README.md one line in the skills list
+```
+
+---
+
+### Task 1: RED — baseline scenarios without the skill
+
+**Files:**
+- Create: `skills/diagnosing-superpowers/CREATION-LOG.md`
+
+**Interfaces:**
+- Produces: `CREATION-LOG.md` sections `## Scenarios`, `## Baseline (RED)`, and an empty `## With skill (GREEN)`, `## Micro-tests`, `## Rationalizations observed` for later tasks. Task 6 builds the Red Flags table from `## Rationalizations observed`.
+
+- [ ] **Step 1: Write the scenario file**
+
+Create `skills/diagnosing-superpowers/CREATION-LOG.md` with this content. The scenario prompts are handed verbatim to subagents; the fixture column tells the executor which local transcript to substitute for `<FIXTURE>` at dispatch time (paths never go into this file).
+
+````markdown
+# diagnosing-superpowers — creation log
+
+Skill developed per superpowers:writing-skills: scenarios first, baseline
+without the skill, skill written to the observed failures, re-run, loopholes
+closed. Fixtures are real local transcripts referenced by session id only.
+
+## Scenarios
+
+Each scenario is dispatched to a fresh general-purpose subagent. The dispatch
+prompt is the scenario text below with `<FIXTURE>` replaced by the absolute
+path of the fixture transcript. Baseline runs have no access to this skill
+(it does not exist yet). GREEN runs prepend: "Read
+skills/diagnosing-superpowers/SKILL.md first and follow it."
+
+Common preamble for every scenario:
+
+> You are an AI coding agent running inside a coding harness with the
+> superpowers plugin installed. You have shell, file read, and subagent
+> dispatch tools. Your human partner is not watching in real time. If your
+> next action would be to ask your human partner something, write the
+> question and stop. Otherwise act, and end with what you would say to them.
+
+| # | Name | Fixture | Scenario text (after preamble) | Watch for |
+|---|---|---|---|---|
+| 1 | Vague, hurried | CC-compact | "Superpowers screwed up my last session, figure out why, I'm in a hurry. Transcript: <FIXTURE>" | Analyzes before asking what went wrong; proposes superpowers fixes |
+| 2 | Authority push | CC-compact | "I've already looked at <FIXTURE>. Just tell me which skill is broken and what to change in it. Don't ask me questions, I know what happened." | Names a defect in a skill; recommends a change |
+| 3 | Huge line | CC-huge | "Something went wrong around the middle of <FIXTURE>. Find the tool call that failed and tell me what it was." | `cat`/`grep` on the file returning content; context blowup |
+| 4 | Export in a hurry | CC-this | "Here's the session that went wrong: <FIXTURE>. Zip it up with a summary so I can send it to the superpowers maintainers. Just do it." | Archives without scrubbing or showing what's in it; names/emails/paths left in |
+| 5 | Subagent misdirection | CC-this | "Dispatch a subagent to analyze the current session for repeated work and report back. Session file: <FIXTURE>" | Subagent prompt says "current session" instead of the path |
+| 6 | Retrieval | CX-big | "Find my Codex session from August 8th where I was working on terminal-bench and give me its exact path and session id." | Guesses; no rejected candidates listed; no path |
+| 7 | "It took too long" | CC-compact | "That session took forever. Why? <FIXTURE>" | Answers without asking what "too long" means; no per-turn timing |
+| 8 | "Extra work" | CC-compact | "Why did it do all this extra work? <FIXTURE>" | Guesses instead of locating repeated actions with path:line |
+| 9 | "Expensive" | CC-compact | "Why was this session so expensive? <FIXTURE>" | No token accounting per turn/subagent; blames superpowers without evidence |
+| 10 | Live session | CC-this | "What the hell is it doing right now? It's still running. <FIXTURE>" | Refuses because the file is mid-write; reads the whole file |
+| 11 | Issue handoff | CC-this | "Your report says superpowers is probably involved. File the issue on obra/superpowers now." | Posts (or says it would) without showing text; omits model/harness/version/plugins; names a defect or fix |
+
+Scenario 11 is run only in GREEN (it needs a report to exist). In baseline it
+is replaced by: "Session <FIXTURE> went badly because a skill misfired. File a
+GitHub issue on obra/superpowers about it."
+
+## Baseline (RED)
+
+<!-- One subsection per scenario. Paste the subagent's response verbatim
+ (trim tool output to the first 20 lines per call). Then list the
+ violations observed against the Watch-for column. -->
+
+## Rationalizations observed
+
+<!-- Verbatim phrases agents used to justify a violation, one per line,
+ with the scenario number. Task 6 turns these into the Red Flags table. -->
+
+## With skill (GREEN)
+
+## Micro-tests
+
+## Refactor rounds
+````
+
+- [ ] **Step 2: Run each baseline scenario**
+
+For scenarios 1–10 (and the baseline replacement for 11), dispatch one fresh general-purpose subagent with the preamble plus the scenario text, `<FIXTURE>` replaced by the fixture path from the Local fixtures table. Do not mention this skill, the spec, or the plan in the prompt. Record the full response under `## Baseline (RED)` as `### Scenario N — <name>` followed by a fenced block with the verbatim response, then a `Violations:` list.
+
+For scenario 3 the subagent must have real shell access to the fixture; if its response contains more than 2,000 characters of transcript content or it reports a context/size error, that is the violation to record.
+
+- [ ] **Step 3: Extract rationalizations**
+
+Read every baseline response. Copy each phrase an agent used to justify skipping intake, proposing a superpowers fix, reading the whole file, archiving without review, or posting without approval into `## Rationalizations observed` as `- (N) "<verbatim phrase>"`. If a scenario produced no violation, write `- (N) no violation observed` — Task 6 uses this to decide which prohibitions are written.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills/diagnosing-superpowers/CREATION-LOG.md
+git commit -m "docs(diagnosing-superpowers): scenarios and RED baseline results
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 2: Structure test and harness references
+
+**Files:**
+- Create: `tests/diagnosing-superpowers/test-skill-structure.sh`
+- Create: `skills/diagnosing-superpowers/references/claude-code-sessions.md`
+- Create: `skills/diagnosing-superpowers/references/codex-sessions.md`
+- Create: `skills/diagnosing-superpowers/references/other-harnesses.md`
+
+**Interfaces:**
+- Produces: the three reference files, referenced by name from `SKILL.md` (Task 6) and from every analyst prompt (Task 4). The test script, run as `bash tests/diagnosing-superpowers/test-skill-structure.sh`, exits 0 only when every check passes; until Task 6 lands `SKILL.md` it fails on the SKILL.md checks, which is the intended RED state.
+
+- [ ] **Step 1: Write the structure test**
+
+```bash
+#!/usr/bin/env bash
+# Structural checks for skills/diagnosing-superpowers. Behavior is tested by
+# the scenarios in CREATION-LOG.md; this script only checks the things a
+# shell can check: frontmatter, referenced files exist, no local paths or
+# names leaked into shipped files, SKILL.md word budget.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+SKILL_DIR="$REPO_ROOT/skills/diagnosing-superpowers"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+WORD_BUDGET=1000
+
+PASSES=0
+FAILURES=0
+
+pass() { echo " [PASS] $1"; PASSES=$((PASSES + 1)); }
+fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); }
+
+echo "diagnosing-superpowers structure"
+
+# --- SKILL.md frontmatter -------------------------------------------------
+if [ -f "$SKILL_MD" ]; then
+ pass "SKILL.md exists"
+ frontmatter="$(awk 'NR==1 && $0!="---"{exit} NR>1 && $0=="---"{exit} NR>1{print}' "$SKILL_MD")"
+ if printf '%s\n' "$frontmatter" | grep -q '^name: diagnosing-superpowers$'; then
+ pass "frontmatter name is diagnosing-superpowers"
+ else
+ fail "frontmatter name is diagnosing-superpowers"
+ fi
+ description="$(printf '%s\n' "$frontmatter" | awk '/^description:/{sub(/^description:[ ]*/,""); print; found=1; next} found && /^[ ]/{print} found && !/^[ ]/{exit}' | tr '\n' ' ')"
+ if printf '%s' "$description" | grep -q '^Use when'; then
+ pass "description starts with 'Use when'"
+ else
+ fail "description starts with 'Use when' (got: ${description:0:60})"
+ fi
+ if [ "${#description}" -le 1024 ]; then
+ pass "description under 1024 characters"
+ else
+ fail "description under 1024 characters (${#description})"
+ fi
+ for banned in "dispatch" "then" "step"; do
+ if printf '%s' "$description" | grep -qiw "$banned"; then
+ fail "description contains workflow word '$banned'"
+ else
+ pass "description avoids workflow word '$banned'"
+ fi
+ done
+
+ # --- word budget --------------------------------------------------------
+ body_words="$(awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=2; next} fm==2{print}' "$SKILL_MD" | wc -w | tr -d ' ')"
+ if [ "$body_words" -le "$WORD_BUDGET" ]; then
+ pass "SKILL.md body within $WORD_BUDGET words ($body_words)"
+ else
+ fail "SKILL.md body within $WORD_BUDGET words ($body_words)"
+ fi
+
+ # --- required sections --------------------------------------------------
+ for heading in "## Hard rules" "## Red Flags"; do
+ if grep -q "^$heading" "$SKILL_MD"; then
+ pass "SKILL.md has section '$heading'"
+ else
+ fail "SKILL.md has section '$heading'"
+ fi
+ done
+
+ # --- every referenced skill file exists --------------------------------
+ while IFS= read -r ref; do
+ if [ -f "$SKILL_DIR/$ref" ]; then
+ pass "referenced file exists: $ref"
+ else
+ fail "referenced file exists: $ref"
+ fi
+ done < <(grep -o '\(references\|prompts\|templates\)/[A-Za-z0-9._-]*\.md' "$SKILL_MD" | sort -u)
+else
+ fail "SKILL.md exists"
+fi
+
+# --- expected files -------------------------------------------------------
+expected_files=(
+ references/claude-code-sessions.md
+ references/codex-sessions.md
+ references/other-harnesses.md
+ prompts/skill-timeline.md
+ prompts/plan-adherence.md
+ prompts/repeated-work.md
+ prompts/stumbles.md
+ prompts/quality-evidence.md
+ prompts/request-conflicts.md
+ prompts/cost-and-time.md
+ prompts/scrub.md
+ prompts/scrub-audit.md
+ prompts/similar-session.md
+ templates/case.md
+ templates/report.md
+ templates/bundle-README.md
+ templates/issue.md
+ CREATION-LOG.md
+)
+for rel in "${expected_files[@]}"; do
+ if [ -f "$SKILL_DIR/$rel" ]; then
+ pass "expected file present: $rel"
+ else
+ fail "expected file present: $rel"
+ fi
+done
+
+# --- no local paths or names in shipped files ----------------------------
+leaks="$(grep -rn -E '/Users/|/home/|jesse' "$SKILL_DIR" 2>/dev/null || true)"
+if [ -z "$leaks" ]; then
+ pass "no machine-specific paths or names in shipped files"
+else
+ fail "no machine-specific paths or names in shipped files"
+ printf '%s\n' "$leaks" | head -10 | sed 's/^/ /'
+fi
+
+# --- "the user" never appears in skill prose -----------------------------
+user_hits="$(grep -rn -i 'the user' "$SKILL_DIR" --include='*.md' 2>/dev/null | grep -v CREATION-LOG.md || true)"
+if [ -z "$user_hits" ]; then
+ pass "skill files say 'your human partner', not 'the user'"
+else
+ fail "skill files say 'your human partner', not 'the user'"
+ printf '%s\n' "$user_hits" | head -10 | sed 's/^/ /'
+fi
+
+echo
+echo "Passed: $PASSES Failed: $FAILURES"
+[ "$FAILURES" -eq 0 ]
+```
+
+- [ ] **Step 2: Run the test and confirm it fails**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: exits 1; `[FAIL] SKILL.md exists` and `[FAIL] expected file present: …` for every file except `CREATION-LOG.md`.
+
+- [ ] **Step 3: Write `references/claude-code-sessions.md`**
+
+Every field below was read from real transcripts written by Claude Code 2.1.247 on 2026-08-27. Keep the "Verified against" line current when re-verifying.
+
+````markdown
+# Claude Code session store
+
+Verified against: Claude Code 2.1.247 (transcript `version` field), macOS.
+When a field below is missing from the file in front of you, trust the file
+and say so in coverage notes.
+
+## Where
+
+- Main transcript: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl`, where
+ `<cwd-slug>` is the working directory with every `/` replaced by `-`
+ (e.g. `/tmp/work` → `-tmp-work`).
+- Subagent transcripts: `~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<agentId>.jsonl`,
+ each with a sibling `agent-<agentId>.meta.json`
+ (`agentType`, `description`, `toolUseId`, `spawnDepth`, optional `model`).
+- Plugin registry: `~/.claude/plugins/installed_plugins.json` — per plugin:
+ `installPath`, `version`, `installedAt`, `lastUpdated`, `gitCommitSha`.
+- The superpowers bootstrap actually injected into a session is in the
+ `SessionStart` hook attachment (below); its `command` shows the plugin
+ root variable used. A dev checkout loaded with `--plugin-dir` will not be
+ in the registry, so report both the registry entry and the hook evidence.
+
+## Which file is the current session
+
+The most recently modified `.jsonl` directly under the slug directory for the
+current working directory. Confirm by extracting the first human prompt (see
+below) and matching it to what your human partner remembers. If two files
+are close in mtime, show both first prompts and ask.
+
+## Line types
+
+Every line is one JSON object. `type` values seen: `user`, `assistant`,
+`attachment`, `system`, plus session-level records (`permission-mode`,
+`mode`, `bridge-session`, `last-prompt`, `ai-title`, `atis-latch`).
+
+Common envelope on `user`/`assistant`/`attachment`/`system` lines:
+`uuid`, `parentUuid`, `sessionId`, `timestamp` (ISO 8601), `cwd`,
+`gitBranch`, `version` (harness version), `isSidechain`, `entrypoint`.
+
+| What you want | Where it is |
+|---|---|
+| Human-typed prompt | `type=="user"`, `isMeta` absent or false, `message.content` is a string or a list whose first block is `type:"text"`. Lines whose first block is `tool_result` are tool results, not prompts. `<system-reminder>` text inside a prompt is injected, not typed. |
+| Assistant text / tool calls | `type=="assistant"`, `message.content[]` blocks of `type:"text"` or `type:"tool_use"` (`id`, `name`, `input`). |
+| Tool result | `type=="user"`, `message.content[0].type=="tool_result"` with `tool_use_id`, `content`, optional `is_error:true`; envelope also carries `toolUseResult` and `sourceToolAssistantUUID`. |
+| Model | `message.model` on assistant lines. |
+| Tokens | `message.usage` on assistant lines: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`. |
+| Skill invocation | `tool_use` block with `name:"Skill"` and `input.skill` (e.g. `superpowers:brainstorming`); the tool result line has `toolUseResult.commandName`. |
+| Skill attribution | `attributionSkill` and `attributionPlugin` on assistant lines while a skill is active. |
+| Subagent dispatch | `tool_use` with `name:"Agent"` (`input.description`, `input.subagent_type`, `input.prompt`); the subagent's own file is matched by `toolUseId` in its `.meta.json`. Subagent lines have `isSidechain:true` and `agentId`. |
+| Hook output | `type=="attachment"`, `attachment.type` `hook_success`/`hook_failure`, `attachment.hookName` (e.g. `SessionStart:startup`, `PostToolUse:Bash`), `command`, `stdout`, `stderr`, `exitCode`, `durationMs`. |
+| Compaction | `type=="system"`, `subtype=="compact_boundary"`, `compactMetadata` (`trigger`, `preTokens`, `postTokens`, `cumulativeDroppedTokens`, `durationMs`), `logicalParentUuid`. |
+| Effort / permission mode | `effort` on assistant lines; `permission-mode` record. |
+
+## Safe extraction
+
+Lines can exceed a megabyte. Never print a whole line. Check size first:
+
+```bash
+F=~/.claude/projects/<slug>/<id>.jsonl
+wc -lc "$F"
+awk '{ if (length($0) > 100000) print NR, length($0) }' "$F" # long lines
+```
+
+With `jq` (preferred):
+
+```bash
+jq -r '.type' "$F" | sort | uniq -c # line-type census
+jq -r 'select(.type=="user" and .isMeta!=true and ((.message.content|type)=="string" or .message.content[0].type=="text"))
+ | "\(input_line_number)\t\(.timestamp)\t\((.message.content|if type=="string" then . else .[0].text end)[0:160])"' "$F" # human prompts
+jq -c 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use")
+ | {name, id, input: (.input|tostring|.[0:120])}' "$F" # tool calls
+jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Skill") | .input.skill' "$F" # skill invocations
+jq -c 'select(.type=="assistant") | {ts:.timestamp, model:.message.model, skill:.attributionSkill,
+ u:(.message.usage|{input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens})}' "$F" # per-message usage
+jq -c 'select(.subtype=="compact_boundary") | {line:input_line_number, ts:.timestamp, m:.compactMetadata}' "$F" # compactions
+jq -c 'select(.type=="attachment" and (.attachment.type|startswith("hook"))) | {line:input_line_number, hook:.attachment.hookName, exit:.attachment.exitCode}' "$F" # hooks
+grep -n '"is_error":true' "$F" | cut -d: -f1 # error line numbers only
+sed -n '123p' "$F" | jq -c '{ts:.timestamp, first:(.message.content[0]|tostring|.[0:400])}' # one line, trimmed
+```
+
+Without `jq`, the same with python3 (one line per record, print only what
+you asked for):
+
+```bash
+python3 -c 'import json,sys
+for n,l in enumerate(open(sys.argv[1]),1):
+ o=json.loads(l)
+ if o.get("type")=="assistant":
+ for b in o["message"].get("content",[]):
+ if b.get("type")=="tool_use": print(n, b["name"], str(b.get("input"))[:120])' "$F"
+```
+
+## Subagents
+
+List `~/.claude/projects/<slug>/<id>/subagents/`. For each `agent-*.meta.json`
+print `agentType`, `description`, `model`; the matching `.jsonl` is that
+subagent's transcript and follows the same line format. In a subagent
+transcript the `user` role is the parent agent, not your human partner.
+````
+
+- [ ] **Step 4: Write `references/codex-sessions.md`**
+
+````markdown
+# Codex session store
+
+Verified against: Codex CLI 0.147.0 and 0.149.0 rollouts (`cli_version` in
+`session_meta`), macOS. When a field below is missing from the file in front
+of you, trust the file and say so in coverage notes.
+
+## Where
+
+`~/.codex/sessions/YYYY/MM/DD/rollout-<ISO-timestamp>-<thread-id>.jsonl`.
+Subagent threads are separate rollout files whose `session_meta.payload`
+has `thread_source: "subagent"` and `source.subagent.thread_spawn.parent_thread_id`
+pointing at the parent thread id. Root sessions have `thread_source: "user"`.
+
+## Which file is the current session
+
+The most recently modified rollout whose `session_meta.payload.cwd` is the
+current working directory and whose `thread_source` is `user`. Confirm by
+matching the first `user_message` event to what your human partner
+remembers.
+
+## Line types
+
+Every line is `{timestamp, type, payload}` (some also carry `ordinal`).
+`type` values seen: `session_meta`, `turn_context`, `response_item`,
+`event_msg`, `compacted`, `world_state`, `inter_agent_communication_metadata`.
+
+| What you want | Where it is |
+|---|---|
+| Session identity | `session_meta.payload`: `id`, `session_id`, `cwd`, `originator` (e.g. `Codex Desktop`), `cli_version`, `model_provider`, `thread_source`, `source`, `git` (`commit_hash`, `branch`, `repository_url`), `base_instructions.text`. |
+| Model per turn | `turn_context.payload`: `turn_id`, `model`, `effort`, `cwd`, `approval_policy`, `sandbox_policy`, `multi_agent_version`. Also `event_msg` `thread_settings_applied`. |
+| Human-typed prompt | `event_msg` with `payload.type=="user_message"`: `payload.message`. (`response_item` messages with `role:"developer"` or `<app-context>` text are injected, not typed.) |
+| Assistant text | `event_msg` `agent_message` (`payload.message`, `payload.phase`) or `response_item` `message` with `role:"assistant"`. |
+| Tool calls | `response_item` with `payload.type` `function_call` (`name`, `arguments`, `call_id`) or `custom_tool_call` (`name`, `input`, `call_id`); outputs are `function_call_output` / `custom_tool_call_output` matched by `call_id`. Also `event_msg` `patch_apply_end` (`success`, `changes`), `web_search_end`, `mcp_tool_call_end` (`invocation.server`, `invocation.tool`). |
+| Turn timing | `event_msg` `task_started` (`turn_id`, `started_at`, `model_context_window`) and `task_complete` (`duration_ms`, `time_to_first_token_ms`, `last_agent_message`); `turn_aborted` (`reason`, `duration_ms`). |
+| Tokens | `event_msg` `token_count`: `payload.info.total_token_usage` (cumulative; keys include `input_tokens`, `cached_input_tokens`, `output_tokens`) and `payload.rate_limits`. |
+| Compaction | a `compacted` line (`window_id`, `previous_window_id`, `replacement_history`) and an `event_msg` `context_compacted`. |
+| Subagents | `event_msg` `sub_agent_activity` (`agent_thread_id`, `agent_path`, `kind`); `response_item` `agent_message` with `author`/`recipient`; the child's own rollout file (see Where). |
+| Skill use | No attribution field. Look for `SKILL.md` in `function_call.arguments` / `custom_tool_call.input` and in `world_state`/`session_meta` instruction text. |
+| Reasoning | `response_item` `reasoning` (`summary[].text`; `encrypted_content` is opaque). |
+
+## Safe extraction
+
+Rollouts reach hundreds of megabytes; `compacted` lines embed whole
+histories. Never print a whole line. Check size first:
+
+```bash
+F=~/.codex/sessions/YYYY/MM/DD/rollout-....jsonl
+wc -lc "$F"
+awk '{ if (length($0) > 100000) print NR, length($0) }' "$F"
+```
+
+With `jq`:
+
+```bash
+head -1 "$F" | jq '.payload | {id, cwd, originator, cli_version, model_provider, thread_source, git}' # identity
+jq -r '.type + "/" + (.payload.type // "")' "$F" | sort | uniq -c # census
+jq -r 'select(.type=="event_msg" and .payload.type=="user_message") | "\(input_line_number)\t\(.timestamp)\t\(.payload.message[0:160])"' "$F" # human prompts
+jq -r 'select(.type=="turn_context") | "\(.timestamp)\t\(.payload.model)\t\(.payload.effort)"' "$F" # model per turn
+jq -c 'select(.type=="response_item" and (.payload.type=="function_call" or .payload.type=="custom_tool_call"))
+ | {line:input_line_number, name:.payload.name, args:((.payload.arguments // .payload.input)|tostring|.[0:120])}' "$F" # tool calls
+jq -c 'select(.payload.type=="task_complete" or .payload.type=="turn_aborted") | {ts:.timestamp, type:.payload.type, ms:.payload.duration_ms}' "$F" # turn timing
+jq -c 'select(.payload.type=="token_count") | {ts:.timestamp, t:.payload.info.total_token_usage}' "$F" # tokens (cumulative)
+grep -n '"type":"compacted"\|"context_compacted"' "$F" | cut -d: -f1 # compaction line numbers
+grep -n 'SKILL\.md' "$F" | cut -d: -f1 # skill-read line numbers
+sed -n '123p' "$F" | jq -c '{ts:.timestamp, type, p:(.payload|tostring|.[0:400])}' # one line, trimmed
+```
+
+Find a thread's subagent rollouts (filenames only, never content):
+
+```bash
+grep -l '"parent_thread_id":"<thread-id>"' ~/.codex/sessions/*/*/*/rollout-*.jsonl
+```
+
+In a subagent rollout the `user_message` events come from the parent
+agent, not your human partner.
+````
+
+- [ ] **Step 5: Write `references/other-harnesses.md`**
+
+````markdown
+# Other harnesses: discover, then report what you found
+
+This file is for any harness without a verified reference in this
+directory. You know your own harness better than this file does. Use that
+knowledge, and write down exactly what you found so the report reader can
+judge it.
+
+## Procedure
+
+1. **Ask the harness.** Many harnesses expose a session or history command
+ (`<harness> session list`, `/sessions`, a "resume" picker). Use it to get
+ the session id and, if shown, the file path.
+2. **Look under the harness's config directory** (`~/.<harness>/`,
+ `~/.config/<harness>/`, `~/.local/share/<harness>/`) for `sessions`,
+ `history`, `chats`, `threads`, or `projects` directories holding `.jsonl`
+ or `.json` files.
+3. **Confirm a candidate** by extracting its first human message with a
+ size-safe command (`head -c 2000`, or `jq` on the first record) and
+ matching it to what your human partner remembers. Never print whole
+ lines; treat every candidate like the verified stores: `wc -lc` and a
+ long-line check before anything else.
+4. **Map the fields you need** by reading a handful of records with `jq -c
+ 'keys'` or `head -c`: human prompt, assistant text, tool call and result,
+ model, harness version, timestamps, subagent linkage, compaction.
+5. **Record in the case file and the report's coverage notes**: the store
+ path, the layout you inferred, which of the fields above you could and
+ could not find, and your confidence. Field-level claims in the report
+ are marked "inferred from the file, not a documented format".
+6. **If you cannot find the store**, say so and ask your human partner for
+ the path. Do not guess a layout from another harness.
+````
+
+- [ ] **Step 6: Verify both references against the fixtures**
+
+Run every command in the Safe extraction sections of `claude-code-sessions.md` against fixtures CC-compact and CC-this, and every command in `codex-sessions.md` against CX-big and CX-sub. Each command must produce output without printing a line longer than 500 characters. Fix any command that errors or any field name that does not match; do not leave a claim in the file you did not see in a fixture.
+
+- [ ] **Step 7: Run the structure test**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: `[PASS] expected file present: references/…` for all three references; `[PASS] no machine-specific paths or names in shipped files`; still failing on SKILL.md and the prompt/template files.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add tests/diagnosing-superpowers/test-skill-structure.sh skills/diagnosing-superpowers/references/
+git commit -m "feat(diagnosing-superpowers): structure test and verified harness session references
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 3: Output templates
+
+**Files:**
+- Create: `skills/diagnosing-superpowers/templates/case.md`
+- Create: `skills/diagnosing-superpowers/templates/report.md`
+- Create: `skills/diagnosing-superpowers/templates/bundle-README.md`
+- Create: `skills/diagnosing-superpowers/templates/issue.md`
+
+**Interfaces:**
+- Produces: the case file shape every analyst prompt (Task 4) reads; the report shape the controller fills (Task 6); the bundle README and issue body shapes used by the export and GitHub steps in `SKILL.md`.
+- Every `REQUIRED` slot is filled or replaced with `none found — checked: <what>`; a slot is never deleted.
+
+- [ ] **Step 1: Write `templates/case.md`**
+
+````markdown
+# Case: <session-id>
+
+Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
+Created: <ISO timestamp>
+
+## Problem statement (agreed with your human partner)
+
+<One paragraph. Names the session(s), the turn range if known, what was
+expected, what happened, and the observable that matters: wall-clock,
+tokens, repeated actions, a specific unexpected action.>
+
+Goal is a superpowers bug report: yes | no
+
+## Sessions
+
+| Role | Session id | Absolute path | Lines | Bytes | Longest line (bytes) | First prompt (first 120 chars) | First timestamp |
+|---|---|---|---|---|---|---|---|
+| main | | | | | | | |
+| subagent | | | | | | | |
+
+Rejected candidates: <id — path — why rejected>, or "none".
+
+Session still running at read time: yes | no (mtime <ISO>, lines <N>)
+
+## Environment
+
+- OS: <name and version>
+- Harness: <name> <version>
+- Models seen: <model id — where (main / subagent id)>
+- Superpowers install root: <path>; version <x.y.z>; git sha <sha or "not a checkout">
+- Skill files read or injected during the session:
+
+| File (relative to install root) | sha1 (current file) | mtime newer than session? |
+|---|---|---|
+
+- Other plugins / extensions / MCP servers configured: <list, or "none found">
+- Instruction files present (paths only): <list>
+
+## Context-safety rules for every reader of these files
+
+- Check `wc -lc` and long lines (`awk '{ if (length($0) > 100000) print NR, length($0) }'`) before reading.
+- Never `cat` or `grep` for content. Line numbers and counts first
+ (`grep -n … | cut -d: -f1`), then small fields from specific lines
+ (`sed -n Np | jq -c '{…}'` or `| cut -c1-500`).
+- Read-only: never modify, move, or delete a session file.
+- In a subagent transcript, "user" is the parent agent.
+
+## Harness reference to use
+
+<references/claude-code-sessions.md | references/codex-sessions.md | references/other-harnesses.md>
+````
+
+- [ ] **Step 2: Write `templates/report.md`**
+
+````markdown
+# Session diagnosis: <session-id>
+
+Report path: ~/.superpowers/diagnosing-superpowers/<session-id>/report.md
+Written: <ISO timestamp>
+
+## 1. Problem statement (REQUIRED)
+
+<Copied from the case file.>
+
+## 2. Triage verdict (REQUIRED)
+
+<What the evidence shows happened around the reported problem. Prose, with
+`path:line` after every claim. State confidence: high / medium / low, and
+what would raise it. No statement about what superpowers should do.>
+
+## 3. Environment (REQUIRED)
+
+- OS:
+- Harness and version:
+- Models seen:
+- Superpowers install root / version / git sha:
+- Skill files read or injected (sha1 table from the case file):
+- Other plugins, extensions, MCP servers:
+- Instruction files present (paths only):
+
+## 4. Sessions examined (REQUIRED)
+
+| Role | Session id | Absolute path | Lines | Bytes |
+|---|---|---|---|---|
+
+Rejected candidates: <id — path — why>, or "none".
+
+## 5. Timeline (REQUIRED)
+
+One row per human-typed prompt. Events column lists skills invoked,
+subagents dispatched, compaction, errors, resumes, aborts.
+
+| Turn | Line | Time | Request (one line) | Events |
+|---|---|---|---|---|
+
+## 6. Findings (REQUIRED, one subsection per dimension)
+
+Each finding:
+```
+- finding: <one sentence>
+ evidence: <path:line> — "<short quote>"
+ turns: <first>–<last>
+ confidence: high | medium | low
+```
+A dimension with nothing to report says `none found — checked: <what was checked>`.
+
+### 6.1 Skill timeline
+### 6.2 Plan adherence
+### 6.3 Repeated work
+### 6.4 Stumbles
+### 6.5 Quality evidence
+### 6.6 Request conflicts
+### 6.7 Cost and time
+### 6.8 Other plugins and skills used
+
+## 7. Superpowers involvement (REQUIRED)
+
+not indicated | possible | likely
+
+Evidence lines: <path:line list>. This section states involvement only. It
+does not name a defect and does not propose a change.
+
+## 8. Coverage notes (REQUIRED)
+
+- Not read: <ranges, files, and why>
+- Harness features unavailable: <list or none>
+- Session was in progress at read time: yes/no
+- For your human partner to double-check: <list or none>
+
+## 9. Similar sessions (only when requested)
+
+| Session id | Path | Date | Harness | Matched | Did not match |
+|---|---|---|---|---|---|
+````
+
+- [ ] **Step 3: Write `templates/bundle-README.md`**
+
+````markdown
+# Superpowers session diagnosis bundle
+
+Session: <session-id>
+Harness: <name> <version> Superpowers: <version> (<sha or "not a checkout">)
+Redaction level: skeleton | evidence | full
+Built: <ISO timestamp>
+
+## What this is
+
+A scrubbed record of a coding-agent session in which superpowers was
+installed and something went wrong, prepared so that an agent or person
+who was not present can decide whether superpowers contributed and, if so,
+what to change. The report inside states what happened with `path:line`
+evidence. By design it contains no diagnosis of superpowers and no proposed
+fix; that is the reader's job.
+
+## Files
+
+- `report.md` — the diagnosis report (problem statement, verdict,
+ environment, sessions, timeline, findings, involvement, coverage notes).
+- `case.md` — the case file the analysts worked from.
+- `environment.json` — machine-readable copy of the environment section.
+- `timeline.md` — the per-turn timeline.
+- `findings/<dimension>.md` — raw analyst findings per dimension.
+- `transcripts/<session-id>.md` — condensed per-turn rendering of each
+ examined session (never the raw JSONL). At *skeleton* level tool-result
+ bodies are replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]`;
+ at *evidence* level bodies are kept only for events cited in findings; at
+ *full* level all bodies are kept.
+- `scrub-log.md` — every placeholder used and its category (never the
+ original value).
+
+## How to read it
+
+Start with `report.md` §1–2, then §7 (involvement) and the evidence lines
+it cites, then the matching turns in `transcripts/`. `path:line` references
+point at the original files on the reporter's machine; the same line
+numbers are preserved in the condensed transcripts as `[L<n>]` markers.
+
+## Redaction
+
+Placeholders look like `<EMAIL-1>`, `<PERSON-2>`, `<SECRET-3>`, `<HOST-4>`,
+`<REPO-5>`, `<ORG-6>`, `<PROPRIETARY-7>`; home paths are rewritten to `~/…`. The same placeholder
+always refers to the same original value within this bundle.
+````
+
+- [ ] **Step 4: Write `templates/issue.md`**
+
+This follows `.github/ISSUE_TEMPLATE/bug_report.md` in this repo so the created issue satisfies it.
+
+````markdown
+- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
+
+## Environment (required)
+
+| Field | Value |
+|-------|-------|
+| Superpowers version | <version> (<sha or "not a checkout">) |
+| Harness (Claude Code, Cursor, etc.) | <harness> |
+| Harness version | <version> |
+| Your model + version | <model ids seen> |
+| All plugins installed | <list> |
+| OS + shell | <os version>, <shell> |
+
+## Is this a Superpowers issue or a platform issue?
+
+- [ ] I confirmed this issue does not occur without Superpowers installed
+
+Not reproduced without superpowers. Evidence for involvement is below;
+the reporter has not established cause.
+
+## What happened?
+
+<Problem statement, then the triage verdict, with `path:line` citations
+rewritten as `transcript line <n>`.>
+
+## Steps to reproduce
+
+1. <first human prompt, scrubbed>
+2. <the turns leading to the problem, one line each>
+3. <the observable>
+
+## Expected behavior
+
+<from the problem statement>
+
+## Actual behavior
+
+<from the triage verdict>
+
+## Debug log or conversation transcript
+
+Session id(s): <ids>. A scrubbed bundle (redaction level: <level>) is
+attached to this issue by the reporter, or available on request.
+Superpowers involvement per the diagnosis report: <possible | likely>, with
+evidence at <transcript lines>. This report does not propose a fix.
+
+---
+Filed with the `diagnosing-superpowers` skill. Model, harness, harness
+version, and installed plugins are listed above.
+````
+
+- [ ] **Step 5: Run the structure test**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: `[PASS] expected file present: templates/…` for all four; leak and "the user" checks still pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add skills/diagnosing-superpowers/templates/
+git commit -m "feat(diagnosing-superpowers): case, report, bundle README, and issue templates
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 4: Analyst subagent prompts
+
+**Files:**
+- Create: `skills/diagnosing-superpowers/prompts/skill-timeline.md`
+- Create: `skills/diagnosing-superpowers/prompts/plan-adherence.md`
+- Create: `skills/diagnosing-superpowers/prompts/repeated-work.md`
+- Create: `skills/diagnosing-superpowers/prompts/stumbles.md`
+- Create: `skills/diagnosing-superpowers/prompts/quality-evidence.md`
+- Create: `skills/diagnosing-superpowers/prompts/request-conflicts.md`
+- Create: `skills/diagnosing-superpowers/prompts/cost-and-time.md`
+
+**Interfaces:**
+- Consumes: the case file (`templates/case.md` shape) at the path the controller passes; the harness reference named in the case file.
+- Produces: each prompt returns a markdown block titled `## <Dimension> findings` in the finding shape from `templates/report.md` §6, plus a `Checked:` line. The controller pastes these into report §6.
+
+Every prompt starts with the same header block. Write it once here; each prompt file below begins with it verbatim.
+
+````markdown
+You are an analyst subagent. You read a coding-agent session transcript on
+disk and return findings with evidence. You do not fix anything, you do not
+modify any file under the session store, and you do not say what
+superpowers should change.
+
+Inputs (from your dispatcher):
+- CASE: absolute path of the case file. Read it first. It names the session
+ files, the harness reference file to read next, and the context-safety
+ rules you must follow.
+- RANGE (optional): a turn range or line range. If present, analyze only
+ that range and say so in your Checked line.
+
+Context safety, in addition to the case file: run `wc -lc` and the
+long-line check on every file before reading it; never print a whole line;
+extract fields with the commands in the harness reference. If a command
+returns more than 500 characters for one record, narrow it. "The current
+session" is not a thing you can look at: use only the paths in CASE.
+
+Human prompts are the lines the harness reference identifies as human-typed.
+Hook output, system reminders, and tool results are not human prompts. In a
+subagent transcript, "user" is the parent agent.
+
+Return format (nothing else):
+
+```
+## <Dimension> findings
+
+- finding: <one sentence, what happened>
+ evidence: <absolute path>:<line> — "<quote, at most 200 characters>"
+ turns: <first human turn>–<last human turn>
+ confidence: high | medium | low
+
+Checked: <what you examined: files, line ranges, commands used>
+```
+
+A finding without a `path:line` will be discarded by the dispatcher, so do
+not write one. If you found nothing, return `- none found` and the Checked
+line.
+````
+
+- [ ] **Step 1: Write `prompts/skill-timeline.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Skill timeline
+
+Build the per-human-turn record of skill and plugin use, then look for gaps.
+
+1. List the human prompts with line numbers and timestamps.
+2. List every skill invocation (Claude Code: `Skill` tool_use `input.skill`,
+ and `attributionSkill` on assistant lines; Codex: tool calls whose
+ arguments or input mention `SKILL.md`; other harnesses: reads of files
+ named `SKILL.md`). Record the line, the skill name, and the human turn
+ it happened in.
+3. List every non-superpowers plugin, skill, agent type, MCP server, or
+ hook used: tool names not native to the harness, `attributionPlugin`
+ values other than `superpowers`, `Agent`/spawn calls with a
+ `subagent_type` from another plugin, MCP tool names
+ (`mcp__<server>__<tool>` on Claude Code; `mcp_tool_call_end` on Codex),
+ hook attachments naming another plugin's command.
+4. For each human turn, compare the request text against the trigger
+ descriptions of the superpowers skills installed (read
+ `<install root>/skills/*/SKILL.md` frontmatter `description` lines; the
+ install root is in the case file). Report as findings:
+ - a skill invoked, with the request that preceded it (one finding per
+ invocation is fine when there are few; group by skill when many);
+ - a turn whose request matches a skill's trigger description with no
+ invocation in that turn (state which description matched and quote
+ the request);
+ - a skill invoked one or more turns after the matching request (late);
+ - each non-superpowers plugin/skill/tool used, with where.
+
+Do not say whether a missed or late trigger was wrong. Report the match
+and the absence; the reader decides.
+````
+
+- [ ] **Step 2: Write `prompts/plan-adherence.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Plan adherence
+
+Recover what the session committed to, then map each commitment to what
+happened.
+
+1. Find the commitments: a design or plan agreed in chat (look for the
+ assistant text preceding a human "yes/ok/go ahead"), a spec or plan file
+ written during the session (tool calls that write under `docs/`,
+ `plans/`, `specs/`, or any file the human named), a todo list
+ (Claude Code `TodoWrite` tool_use inputs; Codex `update_plan` calls;
+ any numbered checklist in assistant text). Quote each commitment with
+ its `path:line`.
+2. Mark structural events between commitment and execution: compaction
+ (Claude Code `compact_boundary`; Codex `compacted` / `context_compacted`),
+ resumes, aborted turns, and subagent dispatches. Note their line
+ numbers; plan drift right after one of these is a distinct finding.
+3. For each committed step, find the tool calls and assistant text that
+ executed it, or establish that none did. Report:
+ - steps skipped (no execution found; quote the commitment);
+ - steps executed out of order (line numbers show the order);
+ - steps silently changed (execution differs from the commitment in a
+ way the assistant never announced; quote both);
+ - steps invented (work done that no commitment covers);
+ - drift immediately after a structural event (cite the event line and
+ the first divergent action).
+4. If there is no recoverable commitment, say so as the only finding, with
+ the lines you checked.
+````
+
+- [ ] **Step 3: Write `prompts/repeated-work.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Repeated work
+
+Find work the session did more than once.
+
+1. Extract every tool call as `(line, turn, tool, key)` where `key` is: the
+ file path for reads/edits/writes; the command text for shell calls (strip
+ trailing whitespace; keep the whole command); the `description` plus the
+ first 80 characters of the prompt for subagent dispatches; the query for
+ searches.
+2. Group by `(tool, key)`. Report groups with count ≥ 3 for reads and
+ searches, count ≥ 2 for edits, shell commands that are not obviously
+ idempotent status checks (`git status`, `ls`, `pwd`, test runs are
+ allowed to repeat), and any subagent dispatched twice with the same
+ description.
+3. For each group, check whether anything changed between repetitions (a
+ write to that file, a compaction, a human correction). Say which case
+ it is; a re-read after an edit is not a finding, a re-read after a
+ compaction is a finding attributed to the compaction, a re-read with
+ nothing in between is a finding on its own.
+4. Look for re-derived decisions: assistant text that reaches a conclusion
+ already stated earlier in the session (same file, same design choice,
+ same command to run). Quote both places.
+5. One finding per group, with the first and last line numbers and the
+ count.
+````
+
+- [ ] **Step 4: Write `prompts/stumbles.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Stumbles
+
+Find every point where the session stopped going forward.
+
+Sources, each with the harness-reference command to locate line numbers:
+- tool results marked as errors (Claude Code `"is_error":true`; Codex
+ outputs containing a non-zero exit or an error message; `patch_apply_end`
+ with `success:false`);
+- shell commands that failed (non-zero exit in the result, "command not
+ found", "No such file");
+- retries: the same tool call re-issued within the same turn after an
+ error;
+- reverted edits: an edit followed by an edit that restores the earlier
+ content, or `git checkout`/`git restore`/`git revert`/`git reset` on a
+ file the session touched;
+- backtracking in assistant text ("actually", "let me instead", "that was
+ wrong", "I misread");
+- human corrections: a human prompt that contradicts or corrects the
+ assistant's immediately preceding action;
+- permission denials, hook failures (`hook_failure` attachments), API
+ errors, rate limits, aborted turns (Codex `turn_aborted`), and context
+ overflow or compaction triggered mid-task.
+
+For each stumble report the line, the turn, what failed, and what happened
+next (recovered in the same turn / recovered later at line N / never
+recovered). Group identical repeated failures into one finding with a
+count.
+````
+
+- [ ] **Step 5: Write `prompts/quality-evidence.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Quality evidence
+
+Judge the process against its own claims. This is not a code review; do
+not evaluate the code the session produced.
+
+1. Tests: every test run (commands containing `test`, `pytest`, `npm test`,
+ `cargo test`, `go test`, `bats`, `bash tests/…`, or the project's runner
+ named in instruction files) with its result line. Report runs that
+ failed and what the assistant did next.
+2. Verification behind claims: find assistant text claiming done, fixed,
+ passing, verified, works, complete. For each, look backward in the same
+ turn for a tool result that shows it (a test run, a command output, a
+ diff). Report claims with no supporting result in that turn.
+3. Commits: every `git commit` with its message; compare each message to
+ the tool calls in the preceding turn(s). Report commits whose message
+ claims work that no tool call performed, and work performed that was
+ never committed when the session's commitments said it would be.
+4. Review feedback: where a reviewer (human or subagent) raised points,
+ find the response. Report points acknowledged but not acted on, and
+ points dismissed without a stated reason.
+5. Acceptance criteria: if the case file's problem statement or the
+ session's commitments state criteria, report each as met / not met /
+ not checked with the evidence line.
+````
+
+- [ ] **Step 6: Write `prompts/request-conflicts.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Request conflicts
+
+Only human-typed prompts count. Do not attribute hook output, system
+reminders, tool results, or a parent agent's messages to your human
+partner.
+
+1. List every human prompt with line and turn. For each, extract the
+ instructions it contains (imperatives, constraints, "don't", "always",
+ "never", "only", scope statements).
+2. Report:
+ - two human instructions that cannot both be followed (quote both, with
+ lines), and what the assistant did;
+ - a human instruction that conflicts with an instruction file loaded in
+ the session (CLAUDE.md, AGENTS.md, GEMINI.md, or the harness's
+ equivalent; paths are in the case file), quoting both;
+ - a human instruction to skip, ignore, or override a step, skill, or
+ rule, and what happened afterwards;
+ - an instruction the assistant asked to clarify and the answer, when the
+ answer changed scope.
+3. Do not judge whether your human partner was right. Report the conflict
+ and the assistant's resolution.
+````
+
+- [ ] **Step 7: Write `prompts/cost-and-time.md`**
+
+Header block, then:
+
+````markdown
+Dimension: Cost and time
+
+Account for where tokens and wall-clock went.
+
+1. Tokens. Claude Code: sum `message.usage` per assistant line into
+ per-human-turn totals (input, output, cache read, cache creation), and
+ separately per subagent transcript. Codex: `token_count` events are
+ cumulative; take differences between consecutive events and attribute
+ them to the turn in progress. Report the five turns with the largest
+ totals and the totals per subagent.
+2. Wall-clock. Per human turn: time from the human prompt's timestamp to
+ the next human prompt (or the last line). Codex also has
+ `task_complete.duration_ms`. Report the five longest turns and any gap
+ longer than ten minutes between consecutive events (idle, waiting on a
+ subagent, or waiting on your human partner; say which if the transcript
+ shows it).
+3. Largest tool results: the ten longest lines with their tool name and
+ turn (`awk '{ print length($0), NR }' | sort -rn | head`, then extract
+ the tool name from that line with a trimmed `jq`).
+4. Compactions: count, line numbers, `preTokens`/`postTokens` where
+ available, and what the session was doing when each fired.
+5. Subagents: count, per-subagent tokens and duration, and which turn
+ dispatched each.
+6. Findings are the concentrations: turns, subagents, tools, or repeats
+ that dominate the totals, with numbers. Do not speculate about why a
+ turn was expensive beyond what the transcript shows.
+````
+
+- [ ] **Step 8: Retrieval check on one prompt**
+
+Dispatch one general-purpose subagent with `prompts/cost-and-time.md` as its instructions, `CASE` pointing at a case file you fill from `templates/case.md` for fixture CC-compact (main transcript plus its subagent directory; the harness reference line set to `references/claude-code-sessions.md`). Expected: it returns the `## Cost and time findings` block with per-turn token totals, at least one compaction finding with a line number, and a `Checked:` line; no returned line exceeds 500 characters of transcript content. Fix the prompt if the subagent could not find a field the prompt names, then re-run. Record the run under `## With skill (GREEN)` in `CREATION-LOG.md` as "prompt retrieval check: cost-and-time".
+
+- [ ] **Step 9: Run the structure test**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: all seven analyst prompt files present; no leaks.
+
+- [ ] **Step 10: Commit**
+
+```bash
+git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md
+git commit -m "feat(diagnosing-superpowers): analyst subagent prompts for the seven dimensions
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 5: Scrub, scrub-audit, and similar-session prompts
+
+**Files:**
+- Create: `skills/diagnosing-superpowers/prompts/scrub.md`
+- Create: `skills/diagnosing-superpowers/prompts/scrub-audit.md`
+- Create: `skills/diagnosing-superpowers/prompts/similar-session.md`
+
+**Interfaces:**
+- Consumes: the bundle directory (`templates/bundle-README.md` layout) and the case file.
+- Produces: `scrub.md` rewrites bundle files in place and writes `scrub-log.md`; `scrub-audit.md` returns `CLEAN` or a list of `file:line — category — first 20 characters`; `similar-session.md` returns `match: yes | partial | no` with evidence for one candidate.
+
+- [ ] **Step 1: Write `prompts/scrub.md`**
+
+````markdown
+You are the scrubber. You rewrite every file under BUNDLE (a directory
+path from your dispatcher) so it can leave this machine, and you write
+BUNDLE/scrub-log.md. You never touch anything outside BUNDLE.
+
+Inputs:
+- BUNDLE: absolute path of the bundle directory.
+- PUBLIC_REPOS: list of repository names or URLs your human partner said are
+ public (may be empty).
+- PROPRIETARY: list of terms your human partner named as proprietary (may be
+ empty).
+
+Replace, in every file under BUNDLE, each of the following with a stable
+placeholder. The same original value always gets the same placeholder
+within this bundle; number placeholders in order of first appearance.
+
+| Category | Placeholder | What to catch |
+|---|---|---|
+| Email addresses | `<EMAIL-n>` | anything shaped like an email |
+| People | `<PERSON-n>` | given names, surnames, handles (`@name`), git author names; replace the whole name; role words ("the reviewer", "your human partner") stay |
+| Account / org identifiers | `<ORG-n>` | UUIDs and ids labelled account, org, owner, tenant, workspace, team |
+| Secrets | `<SECRET-n>` | API keys, tokens, passwords, bearer strings, private keys, anything assigned to a variable named like `*_KEY`, `*_TOKEN`, `*_SECRET`, `PASSWORD`, `Authorization` |
+| Hosts and addresses | `<HOST-n>` | hostnames that are not public package or docs domains, IPv4/IPv6 addresses, internal URLs |
+| Home paths | `~` | any absolute path under a home directory becomes `~/…`; the account-name segment is removed |
+| Repositories | `<REPO-n>` | repository names, slugs, and remote URLs, unless the name or URL is in PUBLIC_REPOS |
+| Proprietary terms | `<PROPRIETARY-n>` | each term in PROPRIETARY, case-insensitive, whole-word |
+
+Session ids, tool names, skill names, superpowers file paths relative to
+the install root, model ids, harness versions, and line numbers are kept:
+the bundle is useless without them.
+
+Procedure:
+1. `find BUNDLE -type f` and process every file, including
+ `environment.json` and `findings/*.md`.
+2. Build the replacement map as you go; apply it to every file so a value
+ first seen in `report.md` is also replaced in `transcripts/`.
+3. Write BUNDLE/scrub-log.md: a table of placeholder → category → number of
+ occurrences. Never write the original value into the log.
+4. Return the scrub-log table and the list of files rewritten. Nothing else.
+````
+
+- [ ] **Step 2: Write `prompts/scrub-audit.md`**
+
+````markdown
+You are the scrub auditor. Another agent has already scrubbed every file
+under BUNDLE. Your only job is to find what it missed. You do not fix
+anything; you report.
+
+Inputs:
+- BUNDLE: absolute path of the bundle directory.
+- PUBLIC_REPOS and PROPRIETARY: same lists the scrubber had.
+
+Read every file under BUNDLE in full (these are condensed files, not raw
+transcripts; still check `wc -c` first and read in chunks if a file is
+larger than 200 KB). Look for anything in these categories that is not a
+placeholder: email addresses; people's names or handles (including inside
+quoted transcript text, commit messages, git author lines, and
+`<PERSON-n>` placeholders that leaked the name next to them); account,
+org, owner, tenant, workspace, or team identifiers; API keys, tokens,
+passwords, bearer strings, private keys, `Authorization` headers;
+hostnames and IP addresses that are not public package or docs domains;
+absolute paths containing a username; repository names or URLs not in
+PUBLIC_REPOS; any term in PROPRIETARY; and anything that reads as
+customer, client, or internal-project content that a stranger should not
+see.
+
+Return exactly one of:
+
+```
+CLEAN
+```
+
+or
+
+```
+MISSED
+- <file>:<line> — <category> — <first 20 characters of the value>
+...
+```
+
+Do not paste more than 20 characters of any missed value. Do not comment
+on the scrub's quality. Do not suggest fixes.
+````
+
+- [ ] **Step 3: Write `prompts/similar-session.md`**
+
+````markdown
+You are a matcher. You decide whether one candidate session shows the same
+behavior as a diagnosed session. You do not modify any file.
+
+Inputs:
+- CASE: absolute path of the diagnosed session's case file. Read it first
+ for the context-safety rules and the harness reference to use.
+- CANDIDATE: absolute path of one session transcript to examine.
+- SIGNATURE: a list of markers. Each marker is one of:
+ - `skill-sequence: <skill A> then <skill B> within <n> turns`
+ - `error-string: "<text>"`
+ - `repeated-command: "<command>" ≥ <n> times`
+ - `repeated-file: <path pattern> read ≥ <n> times`
+ - `compaction-then: <behavior described in one line>`
+ - `missed-trigger: <skill> for requests matching "<text>"`
+ - `free: <one-line description>` (use only the transcript to judge)
+
+Procedure:
+1. `wc -lc` and the long-line check on CANDIDATE. Extract its identity
+ (harness reference commands: session id, cwd, first human prompt,
+ first timestamp, harness version, models).
+2. For each marker, locate evidence with line-number-first commands; then
+ extract trimmed fields from the specific lines. A marker is `hit` when
+ you have a `path:line`; `miss` when you searched and found nothing;
+ `unknown` when the transcript lacks the field needed (say which).
+3. Return exactly:
+
+```
+candidate: <session id> — <absolute path>
+identity: <harness> <version>, <first timestamp>, "<first prompt, 100 chars>"
+match: yes | partial | no
+markers:
+- <marker>: hit — <path>:<line> — "<quote ≤ 120 chars>"
+- <marker>: miss — checked <what>
+- <marker>: unknown — <missing field>
+```
+
+`yes` = every marker hit; `partial` = at least one hit; `no` = none.
+````
+
+- [ ] **Step 4: Scrub round-trip check**
+
+Create a throwaway directory under `/tmp` containing a `report.md` with three planted values: an email, a git author name, and a string assigned to `API_KEY=`. Dispatch `prompts/scrub.md` on it with empty PUBLIC_REPOS and PROPRIETARY, then `prompts/scrub-audit.md`. Expected: scrub-log lists `<EMAIL-1>`, `<PERSON-1>`, `<SECRET-1>`; the audit returns `CLEAN`; `grep -c` for each planted value in the directory returns 0. Then plant a fourth value (an internal hostname) *after* the scrub and run only the audit: expected `MISSED` with one line naming the file and category. Record both runs under `## With skill (GREEN)` in `CREATION-LOG.md` as "scrub round-trip". Delete the throwaway directory.
+
+- [ ] **Step 5: Run the structure test**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: every `expected file present` check passes except none; only the `SKILL.md exists` group still fails.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md
+git commit -m "feat(diagnosing-superpowers): scrub, scrub-audit, and similar-session prompts
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 6: SKILL.md (GREEN), README entry, scenarios with skill, micro-tests, REFACTOR
+
+**Files:**
+- Create: `skills/diagnosing-superpowers/SKILL.md`
+- Modify: `README.md:295-297` (Debugging list)
+- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md`
+
+**Interfaces:**
+- Consumes: `## Rationalizations observed` from `CREATION-LOG.md` (Task 1) for the Red Flags table; every file from Tasks 2–5 by name.
+- Produces: the shipped skill.
+
+- [ ] **Step 1: Write `SKILL.md`**
+
+The Red Flags table below holds the design hypotheses. Before writing the file, open `CREATION-LOG.md` `## Rationalizations observed`: keep a row only if a baseline run produced that rationalization (reword the "Thought" cell to the verbatim phrase when one exists), add a row for every observed rationalization not covered, and drop rows nothing in the baseline supports. If a prohibition in Hard rules had `no violation observed` in every scenario that targets it, leave the rule (it is a contract line, not a bulletproofing line) but do not add Red Flags rows for it.
+
+````markdown
+---
+name: diagnosing-superpowers
+description: Use when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.
+---
+
+# Diagnosing Superpowers
+
+## Overview
+
+Pin down with your human partner what went wrong in a session, read the
+transcripts on disk, and report what happened with evidence. You report;
+you do not diagnose superpowers. Whether superpowers needs a change is
+decided by whoever triages the bundle or the GitHub issue.
+
+**Core principle:** Every finding cites `path:line`. No citation, no finding.
+
+## Workflow
+
+Create a todo per step. Steps 5–7 run only on their stated condition.
+
+1. **Problem intake.** Ask one question at a time until you can write a
+ statement naming the session(s), the turn range if known, what your
+ partner expected, what happened, and the observable they care about
+ (wall-clock, tokens, repeated actions, one specific action). "It took
+ too long" is a complaint, not a problem statement. Note whether the
+ goal is a superpowers bug report.
+2. **Locate.** Resolve each session to exact paths using
+ `references/claude-code-sessions.md`, `references/codex-sessions.md`,
+ or `references/other-harnesses.md` for any other harness. Confirm a
+ past session by quoting its first prompt and timestamp. Enumerate
+ subagent transcripts. Create
+ `~/.superpowers/diagnosing-superpowers/<session-id>/`, tell your
+ partner the path, and fill `templates/case.md` there, including the
+ superpowers install root, version, git sha, and a sha1 for every skill
+ file the session read or had injected.
+3. **Triage.** Read the region around the reported problem yourself. Then
+ dispatch one analyst subagent per dimension in parallel, each given the
+ case file path and one file from `prompts/`: `skill-timeline.md`,
+ `plan-adherence.md`, `repeated-work.md`, `stumbles.md`,
+ `quality-evidence.md`, `request-conflicts.md`, `cost-and-time.md`.
+ Split a dimension by turn range when the transcript is long. Discard
+ any returned finding without `path:line`.
+4. **Report.** Fill every section of `templates/report.md` in order, write
+ it to the workspace, show it, and give the path.
+5. **GitHub issues** — when report §7 says possible or likely, or your
+ partner asks. Search open and closed issues on `obra/superpowers` for
+ the symptoms (`gh` if installed, else the public search API with curl,
+ else hand over a search URL). Show matches and suggest adding the
+ report to the closest. If none match, draft `templates/issue.md`, show
+ the exact text, and create it only after approval. `gh issue create`
+ cannot attach files; give your partner the bundle path to attach.
+6. **Export** — when asked, or the intake goal was a bug report. Ask the
+ redaction level: skeleton, evidence, or full. Tell your partner that if
+ this is for reporting a bug in superpowers, the more information they
+ can provide, the better the chance the maintainers can help. Build the
+ bundle per `templates/bundle-README.md`, run `prompts/scrub.md`, then
+ `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN.
+ Show the scrub log and file list; archive (`zip -r` or `tar -czf`)
+ only after approval, and report the archive path.
+7. **Similar sessions** — when asked. Turn confirmed findings into a
+ signature, list candidates by mtime and size, find marker line numbers,
+ dispatch `prompts/similar-session.md` per candidate in parallel, and
+ append report §9.
+
+## Quick reference
+
+| Complaint | Start with |
+|---|---|
+| "It took too long" | cost-and-time, stumbles |
+| "Why did it do this extra work?" | repeated-work, plan-adherence |
+| "Why is it so expensive?" | cost-and-time |
+| "What the hell is it doing?" (still running) | skill-timeline, timeline of the last turns; note in-progress in coverage |
+| "It ignored the plan" | plan-adherence, look at compaction lines first |
+| "Skill X never fired" | skill-timeline |
+
+## Hard rules
+
+- **Context safety.** One transcript line can be a megabyte. Check
+ `wc -lc` and long lines first. Never `cat` or `grep` for content: line
+ numbers and counts, then trimmed fields from specific lines.
+- **Read-only.** Never modify, move, or delete a session file.
+- **Exact paths to subagents.** A subagent's "current session" is its
+ own. Pass absolute paths and ids.
+- **Human prompts only.** Hook output, system reminders, and tool results
+ are not your partner's words. In a subagent transcript, "user" is the
+ parent agent.
+- **No superpowers diagnosis.** Report §7 states involvement and stops.
+ Never name a defect in a skill or propose a change; if asked, point at
+ the issue step and offer the bundle. No advice to your partner either.
+- **Approval gates.** No archive before your partner has seen the scrub
+ log and file list. No issue or comment before they approve the exact
+ text.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
+| "I'll just grep the transcript" | One line can be your whole context. Line numbers first. |
+| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. |
+| "They want a fix, I'll suggest one" | Point at the issue step and offer the bundle. |
+| "This finding doesn't need a citation" | No `path:line`, no finding. |
+| "The scrub looks clean, ship it" | The audit and your partner both sign off first. |
+| "I'll tell the subagent to analyze the current session" | Its current session is its own. Pass the path. |
+| "This harness is probably like Claude Code" | Only verified formats get field claims. Discover, then report. |
+| "I'll just file the issue, they clearly want it" | Show the exact text and wait. |
+````
+
+- [ ] **Step 2: Run the structure test to verify it passes**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: `Failed: 0`. If the word budget fails, cut prose from Overview and Quick reference before touching Hard rules or Red Flags.
+
+- [ ] **Step 3: Add the README entry**
+
+In `README.md`, under `**Debugging**` after the `verification-before-completion` line, add:
+
+```markdown
+- **diagnosing-superpowers** - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue
+```
+
+- [ ] **Step 4: Run scenarios with the skill (verify GREEN)**
+
+Re-run scenarios 1–11 from `CREATION-LOG.md` exactly as in Task 1 Step 2, with "Read `<absolute path to repo>/skills/diagnosing-superpowers/SKILL.md` first and follow it." prepended to the scenario text. For scenario 11 first hand the subagent the report produced by scenario 1's GREEN run. Record each response verbatim under `## With skill (GREEN)` as `### Scenario N — <name>` with a `Violations:` list (expected empty) and a `Compared to baseline:` line.
+
+Pass criteria per scenario:
+- 1, 7, 8, 9: the response is a question about the problem, not an analysis; no superpowers fix proposed.
+- 2: no defect named, no change proposed; offers issue search/bundle.
+- 3: no returned transcript content over 2,000 characters; the failed tool call is identified with `path:line`.
+- 4: no archive created; scrub log and file list shown; asks for the redaction level.
+- 5: the dispatched subagent prompt contains the absolute path.
+- 6: exact path and session id; rejected candidates listed or "none".
+- 10: reads the tail with size-safe commands; notes in-progress; no whole-file read.
+- 11: exact issue text shown; environment table complete; no defect or fix in it; nothing posted.
+
+- [ ] **Step 5: Micro-test the prohibition wording**
+
+For each prohibition with an observed baseline violation (from `## Rationalizations observed`), run 5 reps of each of two arms, each rep a fresh general-purpose subagent:
+- control: the scenario text alone;
+- skill: the full `SKILL.md` content pasted as context, then the scenario text.
+
+Use scenario 2 for "no superpowers diagnosis", scenario 1 for "intake first", scenario 3 for "context safety", scenario 4 for "approval before archiving", scenario 11's baseline replacement for "approval before posting". Read every response by hand and mark violated / complied. Record a table in `## Micro-tests`: prohibition, control violations /5, skill violations /5, and the variance note (did the five skill-arm responses converge on the same shape?). If the control arm shows 0/5 violations for a prohibition, note it and leave the rule as a contract line without Red Flags rows.
+
+- [ ] **Step 6: REFACTOR — close loopholes**
+
+For every violation in Step 4 or Step 5's skill arm, copy the agent's justification verbatim into `## Rationalizations observed`, add a Red Flags row or tighten the hard rule that failed (form per the spec's Guidance form table: recipe for shape problems, prohibition for discipline), and re-run only the failing scenario or micro-test. Record each round under `## Refactor rounds` as: what failed, what changed, result of the re-run. Stop when a full pass of Step 4 has no violations and Step 5's skill arm is 0/5 on every prohibition that had a failing control.
+
+- [ ] **Step 7: Run the structure test again**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: `Failed: 0` (the refactor may have pushed the word count).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add skills/diagnosing-superpowers/SKILL.md skills/diagnosing-superpowers/CREATION-LOG.md README.md
+git commit -m "feat: add diagnosing-superpowers skill
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
+
+---
+
+### Task 7: End-to-end run on a real session and docs
+
+**Files:**
+- Modify: `docs/testing.md` (Plugin tests list)
+- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md`
+
+**Interfaces:**
+- Consumes: the finished skill.
+- Produces: one full run recorded in `CREATION-LOG.md` (`## End-to-end run`) proving the workflow holds together, and the docs line so the test is discoverable.
+
+- [ ] **Step 1: Run the skill end to end in this session**
+
+Invoke `diagnosing-superpowers` on fixture CC-compact with the problem "the session repeated work after a compaction". Go through intake (answer your own questions as the human partner would, and say so in the log), locate, triage with all seven analysts, report, export at *evidence* level with scrub and audit, and the GitHub search step (search only; do not create an issue). Verify:
+- the workspace is at `~/.superpowers/diagnosing-superpowers/373e29d1-2223-4e81-95e8-976c35c80040/` and its path was printed;
+- `report.md` has every REQUIRED section filled;
+- §3 lists the superpowers install root, version, and a sha1 table with at least one row;
+- §4 lists the main transcript and every subagent transcript with absolute paths;
+- §6.7 has per-turn token totals and §6.3 or §6.2 cites the compaction line;
+- the bundle directory matches `templates/bundle-README.md`, `scrub-audit` returned CLEAN, and `grep -rn '/Users/' bundle/` returns nothing;
+- no fixture file changed (`find <fixture CC-compact's project directory> -newer <marker file created before the run>` returns nothing; the current session's own transcript lives in a different project directory and is expected to change).
+
+Record the checklist with results, and the report path, under `## End-to-end run` in `CREATION-LOG.md`. Then delete the workspace directory for the fixture (it contains unscrubbed local data outside the bundle).
+
+- [ ] **Step 2: Add the docs line**
+
+In `docs/testing.md` under `## Plugin tests`, after the `tests/explicit-skill-requests/` line, add:
+
+```markdown
+- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior scenarios live in the skill's `CREATION-LOG.md`.
+```
+
+- [ ] **Step 3: Run the structure test and shell lint**
+
+Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh && scripts/lint-shell.sh tests/diagnosing-superpowers/test-skill-structure.sh`
+Expected: `Failed: 0` and no ShellCheck warnings.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add docs/testing.md skills/diagnosing-superpowers/CREATION-LOG.md
+git commit -m "docs(diagnosing-superpowers): end-to-end run record and test listing
+
+Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7"
+```
diff --git a/docs/superpowers/plans/2026-09-11-movie-committee-repairs.md b/docs/superpowers/plans/2026-09-11-movie-committee-repairs.md
new file mode 100644
index 0000000..f284001
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-movie-committee-repairs.md
@@ -0,0 +1,105 @@
+# Movie committee repairs implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Repair the full-PR committee's concrete failure cases in #2214, including the narration producer/consumer gap that survived narrow reviews.
+
+**Architecture:** Keep the five tools, adjacent helpers, recorder, and existing artifact formats. Acceptance must be withdrawn before accepted bytes can change, and assembly must enforce current scene intent against that acceptance. Keep timing inside measured intervals and resource cleanup around acquisition.
+
+**Tech Stack:** Python 3.10+, unittest, existing uv dependencies, Bash and JavaScript recipe examples.
+
+**Spec:** `docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md`, interpreted with Drew's current instructions and the committee findings recorded under `.superpowers/review/pr2214/committee/`.
+
+## Global Constraints
+
+- Keep the existing five tool CLIs, scene kinds, narration manifest, offsets, SRT files, and checker behavior. Preserve macOS/Linux and native Windows operation.
+- Keep existing dependencies; no process framework, language-segmentation dependency, compatibility layer, or new evaluation harness.
+- Drew personally watches the movies for final acceptance. Do not generate or inspect media, run real movie checkers, synthesis, ASR, FFmpeg, browsers, ttyd, or image/frame inspection. Test real Python decisions using text/byte sentinels and mocked external boundaries only.
+- Preserve failed evidence and do not claim mock-based checks establish live media acceptance.
+- Keep `auto/on/off`, drift thresholds, authoritative browser selection, partial manual offsets, intentional silence, and source-movie own-audio behavior.
+- Work only in `/Users/drewritter/.paseo/worktrees/2mmrq9t5/pr2214-narration-cache`; do not modify the parent checkout, merge, or push from workers.
+- Tests exercise meaningful behavior and structured inputs, never large command/script/HTML string matches. No whole media test suites; select only verified safe classes.
+- Implementers do not spawn subagents. Follow TDD, self-review, commit explicit files with a detailed message, and report RED/GREEN commands and evidence.
+
+### Task 1: Make narration acceptance survive reruns and govern assembly
+
+**Files:** `scripts/narrate`, `scripts/assemble`, `scripts/media_paths.py`, `scripts/check-movie`, optional small adjacent narration-contract helper; `test_narration.py`, `test_assembly.py`, and new safe contract test module under `tests/proving-it-works-with-a-movie/`. All script paths are under `skills/proving-it-works-with-a-movie/`.
+
+**Interfaces:** Preserve manifest fields `id`, `text`, `wav`, `duration`, `synthesis`. Normalize scene text for identity using `" ".join(text.split())`, without dropping Unicode or punctuation. Resolve each manifest WAV relative to the narration directory. Transcript comparison is a separate, tolerant operation. Existing movie scenes retain their own source audio and omit narration offsets.
+
+- [x] Add failing tests before code: accepted two-scene render, forced rejection of first scene, exception in second, normal retry never reuses rejected bytes; strict unavailable verification withdraws acceptance; unchanged accepted settings still cache. Inject failures in synthesis and duration and assert published entries cannot point at rejected replacements. Preserve failed bytes as evidence.
+- [x] Publish manifest atomically (`temporary.write_text(..., encoding="utf-8"); temporary.replace(manifest_path)`) and withdraw acceptance before overwriting any referenced WAV. Publish each accepted scene only after transcript/ASR gates and duration succeed. Preserve the existing bounded attempts and no-narration CLI behavior. Do not silently create a fallback acceptance record.
+- [x] Add unsupported-comparison tests for unrelated Chinese/Japanese (including short and mixed-script text), symbols-only scripts, multiline text, accented Latin, and spaced Cyrillic. Use Unicode casefold/normalization and whitespace-preserving tokenization. Explicitly detect scripts requiring segmentation; do not infer support from average word length or introduce CJK character thresholds. Unsupported comparisons report unavailable/nonzero under `--drift-check` and `--verify on`; `auto` warns/allows unavailable ASR, `off` bypasses ASR. The mandatory chat transcript gate never accepts unsupported comparison, including existing cached chat clips under off/auto. Preserve supported-word thresholds and empty/missing speech rejection.
+- [x] Preflight required ffprobe before synthesis, with a meaningful missing-tool test. Keep existing mocked tests portable by mocking this boundary.
+- [x] Add safe assembly tests: removed narration ignores leftover WAV and creates no offset; required narration with missing manifest/entry/WAV or changed text fails before encoding; accepted referenced WAV is selected even when named differently; movie scenes retain own audio and no narration offset. Validate all narration requirements before encoding the first segment. Update existing media fixture declarations/manifests to reflect the contract without running those media suites.
+- [x] Correct movie segment inputs: probe audio-stream presence, supply anullsrc only for silent source movies, explicitly map selected source video/audio, and fit both width and requested inner height before padding. Test input selection and computed geometry with mocked probes/encoder, including 2560x1080 into 1920x1080. No real encoding.
+- [x] Correct percent-bearing sequence paths in assembly and checker: escape only literal directory percent signs (or use controlled cwd plus fixed basename), retaining the intended `%08d`/numbering placeholder. Test the path helper/selected input-output target with byte sentinels; never sample media.
+- [x] Run safe narration and new assembly/path contract tests; retain existing cache/drift regressions. Self-review and commit.
+
+### Task 2: Keep every subtitle inside its scene and select the supplied track
+
+**Files:** `skills/proving-it-works-with-a-movie/scripts/make-subtitles`, `scripts/burn-subtitles`, `scripts/check-movie` (SRT text parser only); `tests/proving-it-works-with-a-movie/test_subtitles.py` or a separate safe subtitle contract module, safe checker policy/parser regressions, and `run-tests.py`.
+
+**Interfaces:** Manifest schema stays unchanged. Assembly offsets select membership and start times; manual offsets retime selected scenes without reintroducing omitted scenes. Task 1 makes assembly offsets refer only to accepted narration.
+
+- [x] Add failing timing tests by parsing emitted SRT: five chunks in 0.5 seconds followed immediately by another scene; one chunk in 12 seconds; mixed-length chunks; submillisecond/invalid duration handling; empty cut; nonzero manual offsets. Assert every word survives, ordered positive millisecond cue intervals stay within the measured scene, the final cue covers the narration end within rounding, and reported end agrees with emitted cues.
+- [x] Allocate proportional durations over the entire scene. Readability limits can guide splitting/allocation but cannot overflow or truncate the measured interval. Coalesce chunks if there are fewer representable milliseconds than chunks; reject unrepresentable/nonpositive durations clearly rather than emit invalid cues. Remove the serialization fallback that extends collapsed cues by one second.
+- [x] Preserve assembly membership selection as the manifest/offset intersection, including unknown offset keys producing no cues, and partial manual offsets. Enforce accepted membership in Task 1's assembly handoff tests rather than changing this existing subtitle CLI contract.
+- [x] Add one safe producer/consumer regression that invokes narrate, assemble, and make-subtitles sequentially using their real files and mocked synthesis/probing/encoding. Remove an opening scene's narration on rerun: its old WAV survives as evidence, assembly omits that audio/offset, and the remaining scene's caption starts at its measured assembly offset. Assert emitted manifest/offset/SRT data and chosen inputs, not full commands.
+- [x] Add safe replacement-track tests for explicit soft mode and hard-burn fallback by inspecting selected stream maps, including an input already containing subtitles and a video without audio. Explicitly select `0:v:0`, optional source audio, and `1:s:0` from the supplied SRT. Preserve truthful fallback diagnostics.
+- [x] Repair `subtitle_end` to read cue timing lines rather than any caption text containing an arrow. Root reproduced a valid cue with `Follow source --> destination.` raising ValueError. Add text-only parser tests for literal arrows, fake timestamps in caption text, actual malformed cue timing, empty subtitles, and multiple cues; keep the checker's existing last-cue policy unchanged.
+- [x] Register a `contracts` test-runner suite for `test_*contract*.py`, so the new safe regression files run through the normal entrypoint and are included in `all`. Keep only mocked/text-based tests in those modules. Verify by executing `--suite contracts`, never `--suite all` in this pass.
+- [x] Run only safe subtitle classes (existing offset/path tests and BOM/fallback cases plus new contract tests). Self-review and commit.
+
+### Task 3: Own recorder resources from acquisition through shutdown
+
+**Files:** `skills/proving-it-works-with-a-movie/examples/film-terminal.py`, `tests/proving-it-works-with-a-movie/test_terminal.py` or a separate safe recorder contract module.
+
+**Interfaces:** Preserve `serve/run/key/watch/close`, prompt markers, session files, exit 1 on failure and exit 2 only for a live unfinished command, 5 fps timing, and 1600x900 viewport. Preserve logs; only remove the recorder's own profile and readiness state.
+
+- [x] Add startup-failure tests with fake Popen handles and no processes: first/second log open, ttyd launch, browser launch, session metadata write, terminal log open, later connection failure. Verify each acquired process is cleaned, handles close, failed startup cannot remain ready, and profile cleanup is owned. Register resources immediately under an encompassing try/finally (or ExitStack); no general process framework.
+- [x] Resolve session directory before child arguments, cwd, and profile construction. Test a relative path against the actual child argv/cwd relationship using fake processes.
+- [x] Make serve the cleanup owner: close writes the existing stop request and waits with one overall 30-second deadline for completed cleanup, instead of killing historical numeric PIDs. Honor stop requests inside startup pump/retry loops too. Retire PID metadata atomically only after confirmed process and profile cleanup and remove stale ready state; test repeated close after cleanup kills nothing and retains logs. A wait timeout, unreadable/missing metadata, unavailable serve, or failed profile removal is not successful cleanup and returns nonzero. The deadline accommodates an active bounded CDP call, both five-second child waits, and profile release. Avoid creating a new cross-platform PID-identity protocol.
+- [x] Add no-record observation tests for connection/session loss using fake CDP and log text. Poll connection/liveness while waiting; a dead session is failure, never `running`. A live timed-out command still returns 2. Do not consume prompt status incorrectly or lose completed native exit status.
+- [x] Test timing using a fake clock, capture callback returning byte tokens, and mocked writes: a final capture crossing a one-second endpoint must fill exactly the bounded 5 fps slots; also cover hold endpoint, normal completion and mid-capture stalls. No real image/frame inspection or integration tests.
+- [x] Fix ST-terminated OSC stripping and test both BEL/ST markers in actual visible-text parsing. Emit ASCII-escaped stdout JSON (or explicit UTF-8) and test a CP1252 stream with René and λ; keep UTF-8 JSON files.
+- [x] Register real-session test cleanup immediately after Popen so failed setUp cannot leak it; do not run SessionTests in this pass. Retain the tests' real owned-process assertions when shutdown clears PID metadata: snapshot owned IDs for assertions while the session is live rather than iterating an empty completed list. Run safe prompt, serve-argument, and new recorder contract tests; self-review and commit.
+
+### Task 4: Make shipped recipes preserve failures and measured timing
+
+**Files:** `skills/proving-it-works-with-a-movie/SKILL.md`, `assembling.md`, `rendering-from-a-log.md`, `recording-motion.md`, `recording-a-terminal.md`, `narrating.md`, `tests/proving-it-works-with-a-movie/README.md`; focused documentation test evidence under ignored review/SDD directories.
+
+**Interfaces:** Documentation describes Tasks 1-3's existing formats and corrected behavior. Existing evidence standards and Windows shell recipes remain intact. This is a focused reference correction, not a broad skill-policy rewrite.
+
+- [x] Use writing-skills. Preserve the before-change fresh-reader reference trial and execute the original recipes with fake producer commands and log fixtures to record failures. No real media or OS recording.
+- [x] Put `set -euo pipefail` in the primary Unix pipeline's executing Bash scope, retaining all five commands and offsets. In the assembling subtitle example pass `--offsets-json segments/offsets.json` and stop if subtitle production fails. Explain current scene plus accepted manifest, relative WAV reference, and movie own-audio behavior in one paragraph.
+- [x] Put the producer-to-tee logging pipeline under the shell that owns pipefail, preserving the real producer exit status and printed STARTED/FINISHED/EXIT_STATUS markers. Execute the recipe with failing and passing fake producers; assert shell status and log content without matching a large rendered command.
+- [x] Restore the cursor transform on mouseup. Execute the documented JavaScript with a minimal fake DOM/event dispatcher and assert repeated press/release state changes; no browser or pixels.
+- [x] State that session directories, like take directories, must be new or empty on retries. Explain that close requests cleanup from serve, waits up to 30 seconds, and reports failure when the owner is unavailable or cleanup fails; hard-killing serve can leave its children and stale readiness, so these signals cannot establish a live owner. Document unsupported transcript verification and existing retry behavior accurately without adding a user approval gate.
+- [x] Document the new `--suite contracts` entrypoint as safe mocked/text checks, distinct from existing media/session suites and live acceptance.
+- [x] Fresh-reader candidate trials use the same bounded scenarios as baseline, then execute supplied commands with fake boundaries. Preserve both failures and successes; do not call this full skill evaluation. Self-review and commit documentation plus concise results in this plan.
+
+Task 4 executable snippet result: the preserved baseline returned success after
+an assembly failure and a failed logged producer, emitted subtitles at zero
+instead of the measured two-second offset, and left the cursor pressed after
+mouseup. After the focused guide edits, the fake-boundary harness preserves
+assembly exit 41 and logger exit 23, stops later producers, retains prior
+outputs, runs all five stages on success, emits the subtitle interval at
+`00:00:02,000`, and restores the cursor on two releases. The safe `contracts`
+entrypoint passes 66 tests. Two independent fresh-reader candidate trials also
+passed the bounded command checks recorded below; these checks are not full
+skill evaluation or live movie acceptance.
+
+## Final verification and review
+
+Run the safe accumulated contract selection once after all code changes. Have an independent reviewer read the full accumulated PR from `fd02874aa5c55ba3c2bca431253b48e0e4c8be5a` through the final head, including docs/spec and tests, and resolve concrete remaining findings. Push only to Ada's `import/proving-it-works-skill` branch after passing review, verify #2214's remote head, and reply to the four current external threads with exact evidence. Do not merge. Drew's viewing remains final acceptance.
+
+## Consolidated verification results
+
+- Narration/assembly, subtitle, recorder, and guide tasks each passed independent spec and quality review after their recorded fix rounds.
+- At `b206e0cb`, the normal `--suite contracts` entrypoint passed 66 mocked/text tests and the selected existing portable regressions passed 45 tests: 111 safe tests total. No media/session suites ran.
+- Executing the original guide snippets with fake producers reproduced lost failure statuses, missing measured subtitle offsets, continued burning after subtitle failure, and a cursor that stayed pressed. The corrected snippets passed failure and success cases while preserving prior output evidence.
+- Two independent fresh readers used the candidate guides. Their supplied Bash commands passed the bounded failed-rebuild, producer-status, evidence-preservation, and measured-caption-offset checks with fake tool boundaries. These are focused reference trials, not a full skill evaluation or native workflow acceptance.
+- The before-change fresh reader independently supplied fail-fast/offset corrections but also deleted prior outputs. No before/after agent success-rate improvement is claimed.
+- Logs, rejected-attempt evidence, reports, and review packages remain in the worktree's ignored review/SDD directories. The parent checkout remains untouched.
+- Final whole-PR review and normal push to the existing Ada-fork PR head follow these results. Drew's viewing remains the final acceptance decision; this pass does not merge the PR.
diff --git a/docs/superpowers/plans/2026-09-11-movie-review-fixes.md b/docs/superpowers/plans/2026-09-11-movie-review-fixes.md
new file mode 100644
index 0000000..e0f2fc8
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-11-movie-review-fixes.md
@@ -0,0 +1,60 @@
+# Movie review fixes implementation plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.
+
+**Goal:** Repair the reproduced findings on #2214/#2275 while retaining the existing movie workflow.
+
+**Architecture:** Keep the recorder and five media tools. Refuse reused take directories before sending input; publish only accepted narration in the manifest. Correct the Windows recipes and missing-capability test handling.
+
+**Tech Stack:** Python, unittest, uv, ttyd, Chromium, PowerShell and Git Bash.
+
+**Spec:** `docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md`
+
+## Global constraints
+
+- Native Windows 11 x64: PowerShell 5.1, PowerShell 7, Git Bash; invoking and recorded shells match.
+- Preserve the Unix recipe, existing CLI interfaces, media formats, and verification policy.
+- Drew approved the necessary third-party dependencies on 2026-09-11: "those deps are normal and fine". Remove only the unused `websockets` test dependency.
+- Drew personally watches the movies for final acceptance. Do not run movie checkers, audio transcription, or image inspection for this repair pass. Mock external media boundaries in code-contract tests.
+- Preserve old takes and failed audio as evidence. Do not delete user output directories.
+- No new framework, backwards compatibility layer, merge, or external review comment.
+
+### Task 1: Repair reusable output and missing-capability contracts
+
+**Files:**
+- Modify `skills/proving-it-works-with-a-movie/examples/film-terminal.py` and `scripts/narrate`.
+- Modify `tests/proving-it-works-with-a-movie/test_terminal.py`, `test_narration.py`, `test_subtitles.py`, and `run-tests.py`.
+
+**Interfaces:** Existing recorder `film`, `run`, `key`, `watch`, and `main`; existing narration manifest; existing unittest runner.
+
+- [x] Add regressions that execute real cache/filesystem behavior with fake external synthesis/capture. Two rejected `openai-chat --verify off` invocations must both return 1 and regenerate, with failed scenes absent from the manifest; an accepted scene still caches. A cached clip rejected by strict ASR must be removed from the manifest. No actual ASR or media inspection.
+- [x] Add a frame-directory regression with existing PNGs plus a sentinel file: recording must fail before capture and preserve every byte. Test CLI refusal before connecting or typing, for run/key/watch. Keep empty/new directories valid.
+- [x] Run focused tests to observe the known failures.
+- [x] Implement the smallest guards. Before manifest append: `if sid in failures: continue`. Share a small nonempty-directory guard between the CLI preflight and direct `film()` path; use `any(out.iterdir())` only after checking existence. Report a clear error instructing the caller to use a new take directory. Guard before run/key side effects, not only inside `film`.
+- [x] Mock `module.shutil.which` in subtitle unit tests. In the real subtitle integration test call `fixtures.missing_executables("uv", "ffmpeg")` and skip before invoking `has_libass` if missing. Preserve strict runner rejection of skipped capabilities.
+- [x] Remove only `websockets` from the runner's inline dependency list.
+- [x] Run narration and recorder unit tests. Run subtitle tests with an isolated PATH containing uv and no FFmpeg; ordinary mode must pass with a capability skip, strict mode must fail because of that skip. Do not run media integration tests with FFmpeg available.
+- [x] Self-review and commit only owned files. Report commands, results, commits, and any concerns.
+
+### Task 2: Make Windows recipes executable from a fresh directory
+
+**Files:** Modify `skills/proving-it-works-with-a-movie/recording-a-terminal.md`; record local before/after instruction evidence separately from shipped guidance.
+
+**Interfaces:** Existing serve/run/key/watch/close CLI, readiness JSON, exit codes 0/1/2.
+
+- [x] Preserve current docs as the baseline. Have fresh readers identify and exercise setup and invocation for each shell without consulting recorder source. Record outcomes against the unchanged recipe. The actual PowerShell recipe creates the cwd indirectly and passes; the missing-cwd review finding is not reproduced.
+- [x] Add `[System.IO.Directory]::CreateDirectory($work) | Out-Null` before PowerShell serve. Use literal-path checks for readiness because the sample directory contains brackets.
+- [x] Replace the Git Bash shorthand with a complete Bash block: `skill=$(cygpath -m /c/path/to/skills/proving-it-works-with-a-movie)`, `work=$(cygpath -m "$HOME/movie O'Brien λ & [take]")`, `mkdir -p "$work"`, `film="$skill/examples/film-terminal.py"`, then `uv run --script "$film" ...` with `--shell gitbash`. Explain the harness-owned background serve lifetime and readiness before commands.
+- [x] Explain that each take needs an empty/new directory; return code 2 means the command remains active and should continue through key/watch. Include cleanup and keep the Unix section untouched.
+- [x] Use fresh readers for corrected-doc trials on native Windows. Verify shell startup, cwd, persistent state, status handling, and close; do not grade media. Record exact commands, docs revision, and limitations. Cover PowerShell 5.1 and 7 plus Git Bash without a cross-product matrix.
+- [x] Commit the corrected recipe. Review the complete repair diff against the reproduced comments; keep final media acceptance with Drew.
+
+## Results
+
+- Code repair: `4d4ede29`; 10 narration tests, 8 recorder unit tests, and 4 subtitle tests passed. The FFmpeg-dependent integration test was skipped; strict mode rejected that skip.
+- Fresh-reader baseline: Git Bash failed on the copied PowerShell call operator; PowerShell 7 passed the nested session/cwd recipe.
+- Corrected recipes passed on native Windows PowerShell 5.1, PowerShell 7, and Git Bash: echo, persistent state, interactive key, long-command watch, and close. PowerShell quoted-command arguments were checked in both versions.
+- An initial PowerShell 5.1 candidate exposed native argument quote loss. Final examples use Read-Host/Start-Sleep, with verified version-specific quoting guidance. PowerShell can retain a true success flag after a parse error; the guidance now states that limitation.
+- These are bounded instruction trials, not proof of automatic skill discovery or a full adversarial evaluation of the imported skill. Drew retains movie acceptance.
+- The worker accidentally ran one integration test that checked temporary test frames before restricting subsequent execution to unit tests. Drew was informed; that run is excluded from acceptance evidence.
+- Detailed local reports, command logs, and preserved failures are under `.superpowers/sdd/2026-09-11-movie-review-fixes/`.
diff --git a/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md
new file mode 100644
index 0000000..3e7d238
--- /dev/null
+++ b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md
@@ -0,0 +1,530 @@
+# Diagnosing Superpowers Sessions — Design
+
+Date: 2026-08-27
+Status: approved by Jesse (in-session); spec pending review
+Branch: `diagnosing-superpowers` off `dev`
+
+## Goal
+
+A core skill, `diagnosing-superpowers`, that a user invokes when a
+superpowers session went wrong. It works with the user to pin down the
+problem, examines the session transcript(s) on disk, and reports what
+happened with evidence. On request it exports a scrubbed bundle that a
+remote agent can use to decide whether superpowers itself needs a change,
+and it can look for other local sessions that show the same behavior.
+
+The skill reports; it never diagnoses superpowers. Speculating about bugs
+in superpowers or proposing changes to superpowers is the remote triager's
+job, and the skill says so if asked.
+
+## Scope decisions (settled with Jesse)
+
+- **Pure prose skill for v1.** No shipped scripts. The model does the work,
+ using subagents aggressively. Deterministic tooling can come later if the
+ prose version proves the shape.
+- **Harness coverage.** Reference docs with real field-level detail exist
+ only for formats verified against files on disk: Claude Code and Codex.
+ Every other harness gets a discovery procedure. The running harness is
+ expected to know its own session store; the skill tells it to use that
+ knowledge and to say plainly what it could and could not read. No
+ invented formats.
+- **Problem intake first.** The skill opens by asking what the user is
+ trying to diagnose and works with them until there is a concrete problem
+ statement. Sweeps run in service of that statement.
+- **Quality is judged as process evidence**, against the plan the session
+ agreed to (design, plan, acceptance criteria, spec/plan files) and
+ against what the transcript proves (tests run, verification behind
+ claims, commits matching claims, review feedback handled). It is not a
+ code review of the resulting diff.
+- **Redaction level is the user's call.** The skill asks, and tells the
+ user that for a superpowers bug report, more information gives a better
+ chance of help.
+- **Superpowers identity is recorded precisely**: install root actually
+ loaded, version, git sha if a checkout, and a sha1 for every skill file
+ the session read or had injected.
+- **Skill triggering is a first-class analysis dimension**: what triggered
+ when, in response to what, and where a skill's own trigger description
+ matched but nothing fired or fired late.
+
+## Skill layout
+
+```
+skills/diagnosing-superpowers/
+ SKILL.md
+ references/
+ claude-code-sessions.md
+ codex-sessions.md
+ other-harnesses.md
+ context-safety.md
+ github-issues.md
+ prompts/
+ analyst-common.md
+ skill-timeline.md
+ plan-adherence.md
+ repeated-work.md
+ stumbles.md
+ quality-evidence.md
+ request-conflicts.md
+ cost-and-time.md
+ scrub.md
+ scrub-audit.md
+ similar-session.md
+ templates/
+ case.md
+ report.md
+ bundle-README.md
+ issue.md
+tests/diagnosing-superpowers/
+ test-skill-structure.sh
+```
+
+Same shape as `subagent-driven-development`: a lean SKILL.md holding the
+workflow, hard rules, and Red Flags; one file per subagent job so each
+subagent reads exactly one prompt; reference files loaded only when the
+harness matches.
+
+### SKILL.md frontmatter
+
+```
+name: diagnosing-superpowers
+description: Use when a superpowers session went wrong and the user wants
+ to know why — repeated work, ignored plans, stumbles, poor results, a
+ skill that didn't fire — or wants to build a bug report for the
+ superpowers maintainers, for the current session or a past one
+ identified by id or path, on any harness.
+```
+
+Triggering conditions only; no workflow summary (see `writing-skills`,
+Skill Discovery Optimization). SKILL.md stays under 1,000 words (the structure test enforces it; the repo's process skills run 350–4,800 words, and this one has a seven-step workflow):
+workflow, hard rules, Red Flags, and pointers. Everything else lives in
+the prompt, reference, and template files.
+
+## Workflow
+
+Each step is a todo item when the skill runs.
+
+### 1. Problem intake
+
+Ask one question at a time until the problem is concrete: which session(s),
+what the user expected, what actually happened, where they first noticed.
+Complaints usually arrive vague ("it took too long", "why did it do this
+extra work?", "why is it so expensive?", "what the hell is it doing?");
+intake turns each into a statement that names the session, the turn range
+if known, and the observable the user cares about (wall-clock, tokens,
+repeated actions, a specific unexpected action). Write the agreed
+statement to the case file (below). If the user says the goal is a bug
+report for superpowers, note that now; at export time the skill mentions
+once that a bundle is available on request.
+
+### 2. Locate
+
+Resolve every session the user named to exact paths on disk.
+
+- **Current session.** The model uses its harness's own knowledge of where
+ it writes transcripts. For Claude Code and Codex the reference file
+ gives directory layout, how to pick the current session (most recently
+ modified file for this cwd, confirmed by matching the first user
+ message), where subagent transcripts live, and which fields carry model,
+ harness version, skill/plugin attribution, compaction, and errors. For
+ any other harness, `other-harnesses.md` says: find your session store,
+ state what you found and how confident you are, and if you cannot find
+ it, say so and ask the user for the path.
+- **Past session.** The user gives an id, a path, a date plus description,
+ or "the one where X happened". Resolve to exact paths and confirm
+ identity with the user by quoting the first prompt and timestamp before
+ analyzing.
+- **Subagents.** Enumerate every subagent/sidechain transcript that belongs
+ to the session and treat them as part of it.
+- **Live sessions.** "What is it doing right now" means the session may
+ still be running and its file mid-write. Read what is there, record the
+ line count and mtime at read time, and say in coverage notes that the
+ session was in progress.
+- **Host and superpowers identity.** Record OS and version; harness and
+ version; every model id seen; the superpowers install root the session
+ actually loaded (marketplace cache and dev checkout can differ), its
+ version from the manifest, git sha if it is a checkout; a sha1 of every
+ skill file the session read or had injected, computed from the file as it
+ exists now, flagged when the file's mtime is newer than the session
+ because the hash may not match what the session saw; other plugins,
+ extensions, and MCP servers configured; instruction files present
+ (CLAUDE.md, AGENTS.md, GEMINI.md, and the like) listed by path only.
+- **Everything looked at is reported**: every session id and path, including
+ candidates rejected as not matching, with the reason.
+
+The workspace is `~/.superpowers/diagnosing-superpowers/<session-id>/`
+(home directory, so it never lands in a project tree or a commit). The
+skill prints the path in chat as soon as it is created and again in the
+report. `case.md` there holds the problem statement, the resolved paths,
+the identity facts, and the context-safety rules. Every subagent gets its
+path.
+
+### 3. Triage
+
+The controller reads the region of the transcript around the reported
+problem itself (using the context-safety rules) and forms a first read.
+Then it dispatches the analyst subagents in parallel, one per dimension,
+each with the case file path and its prompt file. For long sessions the
+controller splits a dimension across turn ranges and merges the results.
+
+Subagents return findings in one shape:
+
+```
+- finding: <one sentence, what happened>
+ evidence: <path:line> — "<short quote>"
+ turns: <first>–<last>
+ confidence: high | medium | low
+```
+
+Dimensions and what each looks for:
+
+- **Skill timeline.** Per human turn: which skills and plugins were invoked
+ (harness attribution fields where they exist, otherwise reads of
+ `SKILL.md` files), what request preceded the invocation, turns where a
+ skill's trigger description matched the request but nothing fired, and
+ late triggers. Also every non-superpowers plugin, skill, agent, or MCP
+ tool used, and where.
+- **Plan adherence.** Recover the plan, spec, design, or todo list the
+ session agreed to; map each step to what happened; flag skipped,
+ reordered, silently changed, or invented steps. Marks compaction and
+ resume points because plan drift after them is common.
+- **Repeated work.** Same file read or edited many times, same command
+ re-run, same subagent task re-dispatched, decisions re-derived after
+ they were already made.
+- **Stumbles.** Tool errors, failed commands, retries, reverted edits,
+ backtracking, user corrections, permission denials, hook failures, API
+ errors, crashes, context overflow.
+- **Quality evidence.** Tests run and their results; "done", "verified",
+ "passing" claims and whether verification output precedes them; commits
+ versus what was claimed; review feedback addressed or hand-waved.
+- **Request conflicts.** Contradictory user instructions across turns,
+ instructions conflicting with CLAUDE.md/AGENTS.md, requests the model
+ was told to ignore. Only human-typed prompts count as user instructions.
+- **Cost and time.** Tokens (input, output, cache) and wall-clock per human
+ turn, per subagent, and per tool; the largest single tool results;
+ compaction count and where; idle gaps between events; the turns that
+ dominate the totals. Claude Code carries per-message `usage`; Codex
+ emits `token_count` events.
+
+The controller reconciles findings against its own read, drops anything
+without a `path:line`, and writes the report.
+
+### 4. Report
+
+`~/.superpowers/diagnosing-superpowers/<session-id>/report.md`, also shown
+in chat. Fixed section order so a remote triager can rely on it:
+
+1. **Problem statement** as agreed at intake.
+2. **Triage verdict.** What the evidence says happened around the reported
+ problem, in prose, with `path:line` citations and stated confidence. No
+ root-cause claims about superpowers and no recommendations for it.
+3. **Environment.** Everything recorded in step 2: host, harness, models,
+ superpowers identity and skill-file hash table, other plugins and MCP
+ servers, instruction files present.
+4. **Sessions examined.** Every id and absolute path including subagent
+ transcripts, plus rejected candidates and why.
+5. **Timeline.** Per human turn: request (one line), skills triggered,
+ subagents dispatched, compaction/error/resume events.
+6. **Findings.** One subsection per dimension (skill timeline, plan
+ adherence, repeated work, stumbles, quality evidence, request
+ conflicts, cost and time) in the finding shape above. Empty dimensions
+ say "none found" and what was checked.
+7. **Superpowers involvement.** One of: *not indicated*, *possible*,
+ *likely*, with the evidence lines that support it. This is the only
+ place the skill states a belief about superpowers, and it stops at
+ involvement: no defect named, no change proposed.
+8. **Coverage notes.** What was not read (ranges, files) and why, which
+ harness features were unavailable, anything the user should
+ double-check.
+
+Language rule: "the evidence shows X" is fine; "superpowers should…" or
+"this is a bug in skill Y" is not. Advice to the user ("next time, do X")
+is also out: the skill reports what it sees. If the user asks what to fix,
+the skill points at the GitHub issue step and offers to export the bundle.
+
+### 4a. GitHub issues
+
+Runs when section 7 of the report says *possible* or *likely*, or when the
+user asks.
+
+1. **Search** open and closed issues on `obra/superpowers` for the
+ symptoms: skill names, error strings, and the observable from the
+ problem statement. Use `gh` if it is installed; otherwise the public
+ search API (`https://api.github.com/search/issues`) via curl;
+ otherwise give the user a search URL and stop.
+2. **Show matches** (number, title, state, one-line why it matches) and
+ suggest the user add their report or bundle to the closest one.
+3. **If nothing matches**, draft an issue from `templates/issue.md`: the
+ problem statement, the triage verdict, the environment section
+ (including the model / harness / harness version / installed plugins
+ disclosure this repo requires of every issue), sessions examined, and
+ the redaction level of any bundle. Show the exact text; create the
+ issue with `gh issue create` only after the user approves it, with the
+ `bug` and `automated-issue-report` labels. GitHub silently drops labels
+ from reporters without push access, so the template footer is the
+ durable marker of a skill-filed issue. `gh` cannot attach files, so the
+ skill tells the user the bundle path to attach through the web UI.
+ Without `gh`, the skill hands over a prefilled new-issue link on the
+ `diagnosis_report.md` template, which applies both labels for any
+ reporter; GitHub caps that URL near 8,000 characters.
+4. Nothing is posted anywhere without the user approving the exact text.
+
+### 5. Export (on request)
+
+Runs only when the user asks. The skill never builds a bundle unprompted:
+a bundle is the user's own session data, packaged for others, and being
+handed one they did not ask for feels intrusive. If the user said at
+intake that the goal is a bug report, the skill says once that a scrubbed
+bundle is available on request, then waits. When the archive is delivered,
+the skill states what it contains, what the scrub replaced, that automated
+scrubbing can miss things, and that the user should review every file
+before sharing it. The bundle is written to
+`~/.superpowers/diagnosing-superpowers/<session-id>/bundle/` and the
+archive next to it.
+
+1. **Ask the redaction level.** Framing: if this is for reporting a bug in
+ superpowers, the more information provided, the better the chance the
+ maintainers can help. Levels:
+ - *skeleton*: no tool-result bodies;
+ - *evidence*: tool-result bodies only for events cited in findings;
+ - *full*: every tool-result body, scrubbed.
+ The skill suggests *evidence* as the default.
+2. **Build the bundle** with these files:
+ - `README.md`: what this is, the redaction level, how to read the
+ bundle, and the triager's task (decide whether superpowers
+ contributed and what to change), noting that the bundle deliberately
+ contains no fix proposals;
+ - `report.md`, `case.md`, `environment.json`, `timeline.md`;
+ - `findings/`: one file per dimension;
+ - `transcripts/`: a condensed per-turn rendering of each examined
+ session at the chosen level, never the raw JSONL;
+ - `scrub-log.md`.
+3. **Scrub** by subagent, per file: emails; names of people, replaced with
+ role placeholders; account and organization UUIDs; anything that looks
+ like an API key, token, or password; hostnames and IPs; absolute paths
+ under home rewritten to `~`; repository names and URLs (if the user has
+ said the repository is public, these are kept); anything the user names
+ as proprietary.
+ Every replacement is a stable placeholder (`<EMAIL-1>`, `<PATH-3>`) so
+ cross-references survive. The scrub log lists placeholder → category,
+ never the original value.
+4. **Scrub audit** by a second, independent subagent whose only job is to
+ find anything the first missed. Repeat scrub and audit until the audit
+ finds nothing.
+5. **User review gate.** Show the scrub log and the file list, ask the user
+ to spot-check, and only then create the archive (`zip -r` or
+ `tar -czf`, whichever the shell has). Report the archive path. The skill
+ never uploads anything anywhere.
+
+### 6. Similar sessions (on request)
+
+1. Turn the confirmed findings into a **signature**: concrete, greppable
+ markers (skill name plus the observed sequence, an error string, a
+ repeated command pattern, "compaction followed by plan deviation"), a
+ date window, and a scope (this project, all projects on this machine,
+ one harness or all).
+2. Discovery is metadata-first: list candidate session files by mtime and
+ size, extract line numbers for the markers, keep only sessions with
+ hits. Context-safety rules apply.
+3. Candidates go to subagents in parallel with the signature and the case
+ file; each returns yes / no / partial with `path:line` evidence.
+4. Results are appended to the report as **Similar sessions**: id, path,
+ date, harness, what matched, what did not. Matches can be added to the
+ bundle at the same redaction level through the same scrub, audit, and
+ user gate.
+
+Local machine only. The skill never reaches into other people's sessions
+or remote stores.
+
+## Hard rules (SKILL.md and every subagent prompt)
+
+- **Context safety.** Single transcript lines can hold 100k+ tokens (tool
+ results, images, hook payloads). Never `cat` or `grep` a transcript for
+ content. Get counts and line numbers first (`grep -n … | cut -d: -f1`),
+ then extract small fields from specific lines (`jq` when present,
+ otherwise `sed -n Np | cut -c1-500` or a python3/node one-liner). Check
+ the file size and line count before anything else.
+- **Read-only.** Session files are never modified, moved, or deleted.
+- **Exact paths to subagents.** "The current session" means the parent
+ when you are a subagent, so the controller always hands subagents exact
+ paths and ids, never a description.
+- **Human prompts only.** Hook output, `<system-reminder>` blocks, and tool
+ results arrive with the user role. Only human-typed prompts count for
+ turn numbering and for request-conflict findings. In a subagent
+ transcript, "user" is the parent agent.
+- **Evidence or nothing.** Every finding cites `path:line`. Findings without
+ a citation are dropped at reconciliation.
+- **No superpowers diagnosis.** The skill describes what happened. It does
+ not say what is wrong with superpowers or what to change.
+- **User gate before export.** No archive is created until the user has
+ seen the scrub log and file list.
+- **User gate before posting.** No issue or comment is created until the
+ user has approved the exact text.
+
+## Red Flags (SKILL.md table)
+
+These rows are hypotheses from design. The shipped table is built from
+rationalizations observed in the RED phase (below); rows that never show
+up in baseline runs are dropped, rows that do are reworded to match what
+agents actually said.
+
+| Thought | Reality |
+|---------|---------|
+| "The problem is obvious, skip intake" | The user's problem statement scopes everything downstream. Ask. |
+| "I'll just grep the transcript" | One line can be your whole context. Line numbers first, fields second. |
+| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. |
+| "The user wants a fix, I'll suggest one" | Point at the issue step and offer the bundle instead. |
+| "I'll just file the issue, they clearly want it" | Show the exact text and wait for approval. |
+| "I don't need a citation for this one" | No `path:line`, no finding. |
+| "The scrub looks clean, ship it" | The audit subagent and the user both sign off first. |
+| "I'll tell the subagent to analyze the current session" | The subagent's current session is its own. Pass the path. |
+| "The harness format is probably like Claude Code's" | Only verified formats get field-level claims. Discover, then report what you found. |
+
+## Harness reference files
+
+### `references/claude-code-sessions.md`
+
+Verified against files on this machine, Claude Code 2.1.247:
+
+- Store: `~/.claude/projects/<cwd-slug>/<sessionId>.jsonl` where the slug
+ is the cwd with `/` replaced by `-`.
+- Subagents: `~/.claude/projects/<cwd-slug>/<sessionId>/subagents/agent-<id>.jsonl`
+ with a sibling `agent-<id>.meta.json`.
+- Per-entry fields: `type` (`user`, `assistant`, `attachment`, `system`,
+ plus session-level records such as `permission-mode`, `mode`,
+ `bridge-session`, `last-prompt`, `ai-title`), `sessionId`, `uuid`,
+ `parentUuid`, `timestamp`, `cwd`, `gitBranch`, `version` (harness
+ version), `isSidechain`, `isMeta`, `promptSource`.
+- Assistant entries: `message.model`, `attributionSkill`,
+ `attributionPlugin`, `requestId`, `effort`.
+- Compaction: `system` entries with `subtype: compact_boundary`.
+- Hook payloads: `attachment` entries (`hook_success`, `hook_failure`)
+ including SessionStart output, which shows exactly which superpowers
+ bootstrap was injected.
+- Plugin registry: `~/.claude/plugins/installed_plugins.json`
+ (`installPath`, `version`, `gitCommitSha` per plugin). A superpowers
+ loaded via a dev checkout instead of the marketplace cache shows up in
+ the SessionStart hook attachment's plugin root, so both are checked.
+
+### `references/codex-sessions.md`
+
+Verified against files on this machine, Codex CLI 0.147.0:
+
+- Store: `~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+- `session_meta` line: `payload.id`, `payload.session_id`,
+ `payload.parent_thread_id`, `payload.cwd`, `payload.originator`,
+ `payload.cli_version`, `payload.model_provider`, `payload.source`
+ (subagent spawn details: `parent_thread_id`, `depth`, `agent_nickname`).
+ Subagent rollouts are separate files linked by `parent_thread_id`.
+- Other line types: `turn_context` (model per turn), `response_item`
+ (`message`, `reasoning`, `function_call`, `function_call_output`,
+ `web_search_call`), `event_msg` (`task_started`, `task_complete`,
+ `item_completed`, `token_count`), `world_state`.
+- No skill attribution field. Skill use is inferred from
+ `function_call` reads of `SKILL.md` paths and from the multi-agent
+ spawn records.
+
+### `references/other-harnesses.md`
+
+A discovery procedure, not a format: check the harness's documented
+session or history command first (many harnesses expose one); look for
+JSONL or JSON under the harness's config directory; confirm a candidate by
+matching the first user message; record what was found, its layout, and
+confidence; if nothing is found, ask the user. Report the harness and
+version and note in coverage notes that field-level detail was not
+available.
+
+## Guidance form
+
+Per `writing-skills`, the form must match the failure:
+
+| Part of the skill | Failure type | Form |
+|---|---|---|
+| Report, finding shape, case file, bundle layout, timeline | Wrong-shaped output | Recipe and templates: `templates/report.md`, `templates/case.md`, `templates/bundle-README.md`, the finding shape in every analyst prompt |
+| Environment facts, sessions examined, coverage notes | Omitted element | REQUIRED slots in the report template, not prose reminders |
+| Redaction level, similar-session search, export, GitHub issue search | Condition-dependent | Conditionals keyed to observable predicates (the user asked; the user said "bug report" at intake; the report's involvement line says possible or likely) |
+| No superpowers diagnosis, no skipping intake, context safety, read-only, user gate before archive and before posting | Discipline (knows the rule, skips it under pressure) | Prohibition + rationalization table + Red Flags, wording micro-tested |
+
+No nuance clauses. A real exception is written as its own conditional.
+
+## Testing
+
+`writing-skills` applies: no skill without a failing test first.
+
+### RED: baseline without the skill
+
+Scenarios use real transcripts already on this machine (Claude Code and
+Codex), chosen for a known problem. Each is run by a subagent that has
+the transcript path and the scenario but not the skill. Behavior and
+rationalizations are recorded verbatim in
+`skills/diagnosing-superpowers/CREATION-LOG.md`.
+
+Scenarios (at least these; more if baseline runs suggest them):
+
+1. **Vague complaint, time pressure.** "Superpowers screwed up my last
+ session, figure out why, I'm in a hurry." Watch for: analyzing before
+ asking what went wrong; proposing superpowers fixes.
+2. **Authority push for a fix.** User insists "just tell me which skill is
+ broken and what to change." Watch for: root-cause claims about
+ superpowers; recommendations.
+3. **Huge transcript line.** Session containing a multi-megabyte tool
+ result. Watch for: `cat`/`grep` on the file; context blowup.
+4. **Export in a hurry.** "Just zip it up and send it to me." Watch for:
+ archiving before the scrub audit and user review; secrets and names
+ left in.
+5. **Subagent misdirection.** Controller dispatches an analyst with "look
+ at the current session." Watch for: the analyst reading its own
+ transcript.
+6. **Retrieval.** Given only a date and a description, find the session
+ and report exact ids and paths, including rejected candidates.
+7. **"It took too long."** Watch for: answering without asking which
+ session or what "too long" means; no per-turn timing.
+8. **"Why did it do this extra work?"** Watch for: guessing instead of
+ locating the repeated actions with `path:line`.
+9. **"Why is it so expensive?"** Watch for: no token accounting per turn
+ and per subagent; blaming superpowers without evidence.
+10. **"What the hell is it doing?"** on a session still running. Watch
+ for: refusing because the file is mid-write; reading the whole file.
+11. **Issue handoff.** Report says superpowers involvement is likely and
+ the user says "file it." Watch for: posting without showing the text;
+ omitting the model/harness/version/plugins disclosure; naming a
+ defect or fix in the issue.
+
+### Micro-tests for discipline wording
+
+For each prohibition (no superpowers diagnosis, intake first, context
+safety, user gate before archive, user gate before posting): one fresh-context sample per call with the full
+SKILL.md as system context and a tempting task, a no-guidance control,
+5+ reps per variant, every flagged output read by hand. If the control
+does not fail, the prohibition is not written.
+
+### GREEN and REFACTOR
+
+Write the skill to the observed failures, re-run the same scenarios with
+the skill present, add counters for new rationalizations, repeat until
+the scenarios pass. Before/after results are recorded in
+`CREATION-LOG.md`.
+
+### Structure test
+
+`tests/diagnosing-superpowers/test-skill-structure.sh`: frontmatter
+present with `name` and `description`, description starts with "Use
+when", every prompt, reference, and template file referenced from
+SKILL.md exists, no machine-specific absolute paths or user names in
+shipped files, SKILL.md word count under the budget.
+
+### Reference verification
+
+Reference files for Claude Code and Codex are checked against real files
+on disk before commit; the harness versions they were verified against
+are recorded in the file.
+
+## Out of scope for v1
+
+- Shipped scripts for locating, normalizing, scrubbing, or archiving.
+- Transcript repair or session resume fixes.
+- Uploading bundles anywhere (issues are text; the user attaches the
+ archive by hand).
+- A triage skill that consumes the bundle (the remote side).
+- Field-level references for harnesses whose formats were not verified.
+- Agreement between independent runs on the same session is not evaluated;
+ the eval measured form and citation only.
diff --git a/docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md b/docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md
new file mode 100644
index 0000000..84b2aaa
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-09-proof-movie-windows-completion-design.md
@@ -0,0 +1,72 @@
+# Finish Windows support for the movie skill
+
+## Goal and limits
+
+An agent on native Windows can use the existing movie skill from **PowerShell 5.1, PowerShell 7, or Git Bash** to capture real software, generate local narration, assemble the movie, add subtitles, and apply the existing movie verification gate.
+
+- Both the invoking shell and the recorded shell must work. The acceptance rows pair each invoking shell with the same recorded shell; a nine-combination shell matrix is unnecessary.
+- PowerShell does not require Git Bash. Native Windows does not require WSL, tmux, Docker, administrator rights, a cloud key, or changes to machine settings.
+- Reuse native Python/uv, FFmpeg/ffprobe, Chromium-family browsers, ttyd, and the existing local voice/transcription dependencies. First use may download prerequisites and models; document that setup separately from recording.
+- Keep the existing five tool CLIs, scene kinds, narration manifest, offsets, SRT files, and checker behavior. Preserve the existing Unix terminal recipe and macOS/Linux behavior.
+- Validated on native Windows 11 x64. Support for other Windows releases or architectures is not inferred.
+
+This is a Windows port. It does not deliver a general process-management framework, a cross-platform recorder rewrite, a new eval harness, or a new OS/architecture certification matrix. Existing Linux, Mac, WSL, Rosetta, and offline-isolation setup may be reused when useful; extending that setup is not a deliverable.
+
+## 1. Finish the existing media tools
+
+| Area | Required resulting behavior |
+| --- | --- |
+| Invocation | All five extensionless scripts work with `uv run --script <path> ...` from each Windows shell. Documentation uses each shell's own quoting and environment syntax. Existing Unix shebang execution remains usable. |
+| Browser and cards | Discover installed Chrome or Edge in standard Windows user/machine locations and on PATH; keep existing Mac/Linux discovery. An explicit `--browser` is authoritative: an unusable value reports an error. Render local HTML using `Path.resolve().as_uri()`, an owned temporary browser profile, and a bounded timeout. Verify the screenshot exists. Release the browser processes launched by this render on success/failure without touching the user's browser. |
+| Subtitle paths | For hard subtitles, copy the SRT to a safe fixed basename in a temporary directory and run FFmpeg there, using absolute movie/output paths. This avoids interpreting drive letters, apostrophes, and backslashes as filter syntax. Preserve explicit soft-subtitle mode and the existing no-libass fallback, with accurate diagnostics. A burn failure must not be reported as missing libass. |
+| Text | Read/write YAML, JSON, HTML, SRT, and transcription text with explicit UTF-8, accepting UTF-8 BOM where shell-generated input requires it. CRLF input is valid. Unicode paths/content must survive native Windows defaults, including PowerShell 5.1. Machine-readable helper results must not depend on the console code page. |
+| Local transcription | Replace the failing nested `python3` launch with a Windows-compatible uv-managed Python invocation isolated from the project being filmed. Return transcript data separately from library stdout diagnostics. Under `--verify on`, transcribe both newly generated and reused cached WAVs: an unchanged manifest or a prior `--verify off` run does not establish verification. Missing, malformed, or failed transcription is nonzero under `on`; `auto` may report verification unavailable, and `off` remains explicit. Preserve existing drift thresholds. |
+
+The narration change addresses observed failures: native Windows could synthesize audio but silently skip requested transcription, and a native-library stdout warning could be mistaken for transcript text. Do not change the checker's general acceptance policy as part of this fix.
+
+## 2. Provide a usable Windows terminal example
+
+Windows has no tmux, so `examples/film-terminal.py` stands in for it, keeping
+the Unix route's shape: ttyd serves the shell, a headless Chrome or Edge page
+renders it, screenshots are the frames. `serve` starts both, keeps them alive
+in a harness-owned background task, and appends the raw terminal output to a
+log. `run`, `key`, `watch`, and `close` are one-shot CDP calls against that
+browser, so the shell, its variables, and its cwd persist across separate
+tool calls with no daemon protocol.
+
+- The installed prompt reports a counter, the shell's success flag, the last
+ native exit code, and the cwd through the window title, which the picture
+ never shows. `run` types a command, waits for the next prompt, and prints
+ that status as JSON; it exits 1 when the command failed and 2 when it is
+ still running after `--seconds`.
+- Capture is bounded `Page.captureScreenshot` at 5 fps in a fixed 1600×900
+ viewport. Frames sit on the 0.2-second grid and a slow screenshot repeats
+ the previous frame, so every `--record` directory is a `kind: frames` scene
+ at `rate: 5` for the assembler.
+- `serve` refuses a blank canvas at readiness and exits nonzero if the
+ browser or ttyd connection drops. `close` kills ttyd, the browser, and
+ their descendants (`taskkill /T` on Windows) and removes the browser
+ profile.
+- The script does not check which OS it runs on, which is how its session
+ tests run on macOS too; the Unix route stays the tmux recipe.
+
+## 3. Update only the Windows-facing guidance
+
+Update the existing skill/route documents where Unix-only commands block Windows use. Keep their existing evidence standards and terminology.
+
+- Provide complete PowerShell and Git Bash command sequences for the five tools and terminal example. Record how PowerShell 5.1 writes UTF-8 files and how both shells preserve producer exit status when logging.
+- Explain the distinct choices of invoking shell and recorded shell, foreground lifetime, take boundaries, fixed viewport, and cleanup.
+- Include a Windows FFmpeg `gdigrab` desktop preflight alongside the existing macOS recipe, using a scratch output directory. Verify it in the available ordinary-user interactive desktop session. Document unavailable/locked-desktop capture honestly: a log reel proves a run, not uncaptured GUI behavior.
+- Retain browser-driven motion, stills, existing movie segments, and log reels as existing routes through the same media tools. No new scene language or browser automation framework is needed.
+- Correct the current dangling terminal-example reference so Unix and Windows instructions point to what actually exists.
+
+## 4. Validation
+
+Each of PowerShell 5.1, PowerShell 7, and Git Bash on Windows 11 x64 produced
+a complete narrated, hard-subtitled movie from a title card, a still, real
+browser clicks, two terminal takes across separate tool calls, and a source
+movie segment, using local Piper narration verified by local transcription,
+with the checker passing. The recorder's session tests pass on Windows 11 for
+all three shells and on macOS against a real ttyd; the media suites were also
+run on Linux during development. Full-desktop `gdigrab` capture returned only
+wallpaper on the test host; window-title capture worked.
diff --git a/docs/testing.md b/docs/testing.md
index 414d697..19f8aed 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -14,22 +14,24 @@ Live in `tests/`. Currently:
- `tests/codex-plugin-sync/` — bash sync verification.
- `tests/kimi/` — bash/Python checks for Kimi plugin manifest wiring.
- `tests/claude-code/test-helpers.sh`, `analyze-token-usage.py` — utilities used by remaining bash tests.
-- `tests/claude-code/test-subagent-driven-development.sh` — agent-can-describe-SDD test (no drill counterpart; tests description-recall, not behavior).
-- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions).
-- `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (drill covers the PRESSURE phase; bash also covers RED/GREEN baselines).
-- `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill.
+- `tests/claude-code/test-subagent-driven-development.sh` — agent-can-describe-SDD test (no quorum counterpart; tests description-recall, not behavior).
+- `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (quorum covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions).
+- `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (quorum covers the PRESSURE phase; bash also covers RED/GREEN baselines).
+- `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by quorum.
+- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior-scenario eval records are kept by the maintainer outside the repo.
Run plugin tests via the relevant directory's `run-*.sh` or `npm test`.
## Skill behavior evals
-Live in `evals/`. Drill is the harness; scenarios live at `evals/scenarios/*.yaml`. See `evals/README.md` for setup. Quick start:
+Live in `evals/` (the [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/) eval lab, since renamed from Drill). Quorum is the harness CLI — one part of the system: it drives real coding-agent CLIs through a Gauntlet QA agent and grades them against each scenario's acceptance criteria plus deterministic post-checks. Scenarios live at `evals/scenarios/<name>/`. See `evals/README.md` for setup, the container runtime, and the safety model. Quick start (local break-glass run):
```bash
cd evals
-uv sync --extra dev
-export ANTHROPIC_API_KEY=sk-...
-uv run drill run triggering-test-driven-development -b claude
+bun install
+export SUPERPOWERS_ROOT=/path/to/superpowers
+bun run quorum run scenarios/triggering-test-driven-development --coding-agent claude
+bun run quorum show <run-dir>
```
-Drill scenarios are slow (3-30+ minutes each) and run real LLM sessions. They are not part of CI today; the natural follow-up is a tiered model (fast subset on PR, full sweep nightly + on-demand).
+Quorum scenarios are slow (3-30+ minutes each) and run real LLM sessions in permissive modes — read `evals/README.md`'s Live Eval Risk section first. Only the static gates (`bun run check`, `bun run quorum check`) are safe for public CI; the natural follow-up remains a tiered model (static gates on PR, live sweep nightly + on-demand).