feat: add diagnosing-superpowers skill

Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7

skills/diagnosing-superpowers/SKILL.md

@@ -0,0 +1,104 @@
+---
+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. 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`, 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. |
+| "Small, targeted edit, no restructuring needed" | Not your call, however small. Report the evidence; the triager decides. |
+| "One candidate obviously matches, no need to list the rest" | Every candidate you rejected goes in the report, with the reason. |
+| "The price per token is well known" | Numbers you did not compute from the transcript are invented. Cite or drop. |