diagnosing-superpowers skill
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.
Is the diagnosing-superpowers skill safe?
Clean: nothing in its files matched our rules. We read 20 files in the folder on 2026-10-25.
No findings.
Install the diagnosing-superpowers skill
A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description.
git clone --depth 1 https://github.com/obra/superpowers.git /tmp/superpowers mkdir -p ~/.claude/skills cp -r /tmp/superpowers/skills/diagnosing-superpowers ~/.claude/skills/diagnosing-superpowers
In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub
The instructions your agent would load
SKILL.md as published, without the frontmatter. Read it on GitHub
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.
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.
- Problem intake. Ask one question at a time until you can write a
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//, tell your partner the path, and fill templates/case.md there, following its provenance rules for environment and skill observations.
- Locate. Resolve each session to verified absolute filesystem paths using
dispatch one analyst subagent per dimension in parallel, 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.
- Triage. Read the region around the reported problem yourself. Then
it to the 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.
- Report. Fill every section of templates/report.md in order, write
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 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.
- GitHub issues — when report §7 says possible or likely, or your
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, 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, 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.
- Export — only when your partner asks for a bundle; never build one
signature, list candidates by mtime and size, find marker line numbers, dispatch prompts/similar-session.md per candidate in parallel, and append report §9.
- Similar sessions — when asked. Turn confirmed findings into a
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
references/context-safety.md on every session file, every time.
- Context safety. One transcript line can be a megabyte. Follow
own. Pass absolute paths and ids.
- Read-only. Never modify, move, or delete a session file.
- Exact paths to subagents. A subagent's "current session" is its
are not your partner's words. In a subagent transcript, "user" is the parent agent.
- Human prompts only. Hook output, system reminders, and tool results
Never name a defect in a skill or propose a change. Your partner pressing for a fix does not waive this; point at the issue step and mention that a bundle is available on request. No advice to your partner either.
- No superpowers diagnosis. Report §7 states involvement and stops.
log and file list. No issue or comment before they approve the exact text, and none with a placeholder summary.
- Approval gates. No archive before your partner has seen the scrub
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.
- Intake before analysis. Nothing in steps 2–7 starts until your
Red Flags
More skills from obra/superpowers
- AbrainstormingYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).
- Adispatching-parallel-agentsUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
- Aexecuting-plansUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available
- Afinishing-a-development-branchUse when implementation is complete, all tests pass, and you need to decide how to integrate the work
- Areceiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
- Arequesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirements
- Asubagent-driven-developmentUse when executing implementation plans with independent tasks in the current session
- Asystematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes
- Atest-driven-developmentUse when implementing any feature or bugfix, before writing implementation code
- Ausing-git-worktreesUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
- Ausing-superpowersUse when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
- Averification-before-completionUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always