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

Track each step in a task.md artifact. 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 verified absolute filesystem paths using references/session-discovery.md. 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, following its provenance rules for environment and skill observations.
3. Triage. Read the region around the reported problem yourself. Then dispatch one session-analyst per dimension in one invoke_subagent call, each given the case file path, prompts/analyst-common.md, and one dimension 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 case workspace, show it, and give the path. Check what cited content actually proves and preserve the supporting case; a symlink alias is not a redundant copy.
5. GitHub issues — when report §7 says possible or likely, or your partner asks. Search open and closed issues for the symptoms per references/github-issues.md. Show matches and suggest adding the report to the closest. If none match, fill templates/issue.md, write it to the case workspace, show the exact text, and create the issue only after approval. gh cannot attach files; if a bundle exists, give your partner its path to attach in the browser.
6. Export — only when your partner asks for a bundle; never build one unprompted. If the intake goal was a bug report, say once that a scrubbed bundle is available on request, then wait. Ask the redaction level (ask_question), stating what each includes: skeleton (no tool-result bodies), evidence (bodies only for cited events), full. Build the bundle per templates/bundle-README.md, dispatch prompts/scrub.md to bundle-scrubber, then prompts/scrub-audit.md, repeating both until the audit returns CLEAN. Complete the bundle template's evidence check and reconciliation before showing the final scrub log, file list, and privacy and evidence outcomes. Archive (zip -r or tar -czf) only after approval. With the archive path, state what it contains, point at the scrub log for replacements, and say scrubbing can miss things: they must review every file before sharing.
7. Similar sessions — when asked. Turn confirmed findings into a signature, list candidates by mtime and size per references/session-discovery.md, find marker line numbers, dispatch prompts/similar-session.md per candidate in parallel, and append report §9.

Quick reference

All seven analysts always run. This table says which region to read yourself in step 3 and which findings to lead with in the verdict.

Hard rules

• Context safety. One transcript line can be a megabyte. Follow references/context-safety.md on every session file, every time.
• 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 skill defect or propose a change. Your partner pressing for a fix does not waive this; point at the issue step and mention a bundle is available on request. No advice to your partner.
• Approval gates (ask_question). No archive before your partner has seen the scrub log and file list. No issue or comment before they approve the exact text, and none with a placeholder summary.
• 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