mirror of
https://github.com/obra/superpowers.git
synced 2026-09-01 11:29:23 +00:00
feat: add diagnosing-superpowers skill
Evidence-based diagnosis of superpowers sessions: intake with the human partner, safe transcript reading for Claude Code and Codex (discovery procedure for other harnesses), seven analyst subagents, a report with path:line evidence and a bounded superpowers-involvement line, scrubbed export bundles, approval-gated GitHub issue search/draft, and similar-session search. Includes spec, plan, structure test, and README and docs index lines. Developed RED-GREEN-REFACTOR per writing-skills: 46 scored scenario runs across five SKILL.md versions, all twelve scenarios clean against the final version, micro-tests control 5/5 to skill 0/5 on both baseline-failing prohibitions, and one end-to-end run. Eval records are kept by the maintainer outside the repo. Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7
This commit is contained in:
Jesse Vincent
@@ -0,0 +1,112 @@
|
||||
---
|
||||
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. Whoever triages the bundle or the issue
|
||||
decides whether superpowers changes.
|
||||
|
||||
**Core principle:** Every finding cites `path:line`. No citation, no
|
||||
finding. Every number comes from the transcript or from a command you ran,
|
||||
never from memory.
|
||||
|
||||
## 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, and list every
|
||||
candidate you rejected with the reason, or "none". 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`, dispatch `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; note in-progress in coverage |
|
||||
| "It ignored the plan" | plan-adherence, 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. Pushing does not
|
||||
waive this; 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.
|
||||
- **Intake before analysis.** Nothing in steps 2–7 starts until your
|
||||
partner has answered. If they are away, write the questions and stop.
|
||||
A statement you reconstructed for them is not an answer. An
|
||||
already-scoped request — one specific event, what is running now, or
|
||||
the analysis to run — is itself the statement: answer it, then ask.
|
||||
A whole-session "why" is a complaint.
|
||||
|
||||
## Red Flags
|
||||
|
||||
| Thought | Reality |
|
||||
|---------|---------|
|
||||
| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. |
|
||||
| "They're away, so I'll reconstruct the statement" | You cannot reconstruct what they wanted. Write the questions and stop. |
|
||||
| "I'll sweep everything now and ask at the end" | An unscoped sweep spends their budget on the wrong question. Ask first. |
|
||||
| "Small, targeted edit, no restructuring needed" | Not your call, however small. Report the evidence; the triager decides. |
|
||||
| "The price per token is well known" | Numbers you did not compute from the transcript are invented. Cite or drop. |
|
||||
@@ -0,0 +1,65 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,66 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,62 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,63 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,60 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,38 @@
|
||||
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.
|
||||
@@ -0,0 +1,38 @@
|
||||
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.
|
||||
@@ -0,0 +1,37 @@
|
||||
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.
|
||||
@@ -0,0 +1,69 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,66 @@
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,105 @@
|
||||
# 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`,
|
||||
`pr-link`, `queue-operation`, `relocated`, `worktree-state`).
|
||||
|
||||
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. Text beginning with `<task-notification>`, `<command-name>`, `<local-command-stdout>`, `<system-reminder>`, or `This session is being continued from a previous conversation` is harness-injected too, even though `isMeta` is absent on those lines — exclude them or your human-turn count will be several times too high. |
|
||||
| Human-typed prompt queued mid-turn | `type=="attachment"`, `attachment.type=="queued_command"`, `attachment.origin.kind=="human"`, text in `attachment.prompt`. These are typed while a turn is running and never appear as standalone `user` lines, so they are missing from the list above. Add them to the timeline. |
|
||||
| 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"))
|
||||
| select((.message.content|if type=="string" then . else (.[0].text // "") end)
|
||||
| test("^(<task-notification>|<command-name>|<local-command-stdout>|<system-reminder>|This session is being continued)") | not)
|
||||
| "\(input_line_number)\t\(.timestamp)\t\((.message.content|if type=="string" then . else .[0].text end)[0:160])"' "$F" # human prompts
|
||||
jq -r 'select(.type=="attachment" and .attachment.type=="queued_command" and .attachment.origin.kind=="human")
|
||||
| "\(input_line_number)\t\(.timestamp)\t\(.attachment.prompt[0:160])"' "$F" # human prompts queued mid-turn; merge with the list above
|
||||
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|{trigger,preTokens,postTokens,cumulativeDroppedTokens,durationMs})}' "$F" # compactions (full compactMetadata also has UUID lists; keep this trimmed)
|
||||
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 // "") as $c
|
||||
| ($c | if type=="array" then ($c[0] // "") else $c end) | tostring | .[0:400])}' # one line, trimmed (content is sometimes a bare string, sometimes absent)
|
||||
```
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Codex session store
|
||||
|
||||
Verified against: Codex CLI 0.146.0, 0.147.0 and 0.149.0-alpha.4.1 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. Newer rollouts may carry no `user_message` event at all: when
|
||||
that command returns nothing, fall back to `response_item` messages with
|
||||
`role:"user"` (see Human-typed prompt below) and confirm against the first
|
||||
of those instead.
|
||||
|
||||
## 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`. When that returns nothing — seen on `thread_source: "user"` Codex Desktop rollouts at `cli_version 0.149.0-alpha.4.1`, and on subagent rollouts — fall back to `response_item` messages with `payload.role=="user"`, text in `payload.content[0].text`. `role:"developer"` messages are injected boilerplate, not typed, and so is any fallback text that begins with a tag such as `<subagent_notification>`, `<environment_context>`, `<skill>` or `<recommended_plugins>`. On a subagent rollout the fallback text is the parent agent's dispatch prompt, not your human partner's. |
|
||||
| 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=="response_item" and .payload.type=="message" and .payload.role=="user")
|
||||
| "\(input_line_number)\t\(.timestamp)\t\((.payload.content[0].text // "")[0:160])"' "$F" # human prompts, fallback when the line above returns nothing; skip rows whose text starts with a `<tag>`
|
||||
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
|
||||
```
|
||||
|
||||
A subagent rollout can carry no `event_msg` `user_message` at all — the
|
||||
parent agent's dispatch prompt instead shows up as a `response_item`
|
||||
`message` with `role:"user"`. If a `user_message` event is present, it is
|
||||
from the parent agent, not your human partner.
|
||||
@@ -0,0 +1,30 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,44 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,50 @@
|
||||
# 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>
|
||||
@@ -0,0 +1,49 @@
|
||||
- [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.
|
||||
@@ -0,0 +1,78 @@
|
||||
# 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 |
|
||||
|---|---|---|---|---|---|
|
||||
Reference in New Issue
Block a user