diagnosing-superpowers

Diagnose Superpowers

Overview

Work with your human partner to pin down what went wrong in a session, read the session transcript on disk, report what happened with evidence. You report, you don't diagnose superpowers. Whether superpowers should change, is decided by whoever triages this packet or this issue.

Core principles: Every finding must cite path:line. No citation, no finding. Every number comes from the session transcript or a command you ran yourself, never from memory.

Workflow

Create a todo for each step. Steps 5–7 run only under the conditions each names.

Intake. Ask one question at a time until you can write a statement: name which session(s), the turn range if known, what your partner expected, what actually happened, and the observable they care about (elapsed time, tokens, repeated actions, one specific action). "Too slow" is a complaint, not a problem statement. Note whether the goal is a superpowers bug report.
Locate. Resolve each session by references/session-discovery.md into a verified absolute filesystem path. When confirming a past session, cite its first prompt and timestamp, and list every candidate you ruled out with the reason, or write "none". Enumerate subagent transcripts. Create ~/.superpowers/diagnosing-superpowers/<session-id>/, tell your partner the path, fill in templates/case.md, with environment and skill observations following the source-annotation rules therein.
Triage. First read the stretch near the reported problem yourself. Then dispatch one analyst subagent per dimension in parallel, give each one: the case file path,prompts/analyst-common.md, and one dimension file under prompts/ :skill-timeline.md、 plan-adherence.md、repeated-work.md、stumbles.md、 quality-evidence.md、request-conflicts.md、cost-and-time.md. When the transcript is long, split one dimension by turn range. Discard any returned finding without path:line.
Report. Fill in each section of templates/report.md in order, write it into the workspace, show it, and give the path. Check what the cited content actually proves, and keep the case that supports it; symlink aliases do not count as redundant copies.
GitHub issue — when report §7 says possible or likely, or your partner asks. Search these symptoms across open and closed issues by references/github-issues.md . Show the matches, suggest appending the report to the closest one. If none match, fill in templates/issue.md, write it into the workspace, show the exact text, and create the issue only after approval. gh cannot attach files; if there is a packet, give the path to your partner so they can attach it in the browser.
Export — only when your partner asks for a package; never package on your own initiative. If the goal at intake is a bug report, say once "sanitized packaging materials can be provided on demand," then wait. Ask about the sanitization level, and explain what each level contains: skeleton (no tool result bodies), evidence (only the bodies of referenced events), full. Follow templates/bundle-README.md to build the packaging materials, dispatch prompts/scrub.md, then dispatch prompts/scrub-audit.md, and repeat both until the audit returns CLEAN. First complete the evidence verification and reconciliation in the packaging template, then present the final sanitization log, file list, and the conclusions on both privacy and evidence. Only archive after approval (zip -r or tar -czf). When giving the archive path, explain what it contains, point to the sanitization log to see the replacements, and note that sanitization may have omissions: they must review every file one by one before sharing.
Similar sessions — do this when asked. Turn the confirmed finding into a feature signature, list candidates by modification time and size, find the line number where the marker is, dispatch prompts/similar-session.mdin parallel for each candidate, then append to report §9.

Quick reference

All seven analysts always run. This table shows which section you read first in step 3, and which findings you present first in the conclusion.

Complaint	Read first, present first
"Too slow"	cost-and-time、stumbles
"Why did it do extra work?"	repeated-work、plan-adherence
"Why is it so expensive?"	cost-and-time
"What is it actually doing?" (still running)	skill-timeline; note in the coverage description that it is still in progress
"It ignored the plan"	plan-adherence, look first at the line where compaction is
"Skill X never triggered"	skill-timeline

Hard rules

Context safety. A single line of a session record can be a megabyte. For every session file, every time, follow references/context-safety.md。
Read-only. Never modify, move, or delete session files.
Give subagents exact paths. A subagent's "current session" is its own session. Pass absolute paths and ids.
Only human prompts count. Hook output, system reminders, and tool results are not things your partner said. In a subagent's session record, "user" is the parent agent.
Do not diagnose superpowers. Report §7 only states whether it is involved, and goes no further. Never point out a defect in a skill, nor propose changes. Your partner pressing for a fix does not exempt you from this either; point to the issue step, and mention that packaging materials can be provided on demand. Also do not give your partner suggestions.
Approval gate. Do not archive before your partner has seen the sanitization log and file list. Do not send an issue or comment before they approve the exact text.
Intake first, analysis second. Until your partner replies, steps 2–7 do not start at all. If they are away, write down the question and stop. A statement you reconstructed on their behalf does not count as a reply. A request with an already clear scope—a specific event, what is running right now, or which analysis to run—is itself a statement: answer it first, then ask. A "why" about the entire session is a complaint.

Red flags

Idea	Reality
"The problem is obvious, skip intake"	The problem statement determines the scope of everything. Go ask.
"They're not around, so I'll reconstruct the statement"	You cannot reconstruct what they want. Write down the problem, then stop.
"I'll scan everything first, then ask at the end"	An unscoped scan spends their budget on the wrong problem. Ask first.
"They want a bug report, so I'll package it now"	The packaging material is the session data they packaged up. Only build it when they ask.
"It's just a small targeted fix, no need to refactor"	No matter how small, it's not yours to decide. Report the evidence; the triage people decide.
"The price of every token is well known"	Any number not calculated from the session record is fabricated. Either cite it or delete it.