superpowers-diagnosing-superpowers

Diagnosing Reasonix Superpowers Sessions

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 the port. Whoever triages the bundle or the issue decides whether a skill or Reasonix 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.

Resolve bundled assets: The skill loader's header gives the absolute path to this SKILL.md. Use its containing directory as the asset root. Resolve every prompts/, templates/, and references/ path below against that root before reading it or passing it to a native task worker. Workers run from the project directory and do not inherit this skill's path; give each worker the case path and every needed asset as an absolute path.

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 bug report for this port.
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 ~/.reasonix/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 analyst with Reasonix's native task per dimension in parallel, each given the absolute case file path, absolute prompts/analyst-common.md and references/context-safety.md paths, and one absolute 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 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 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, 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, giving each worker the absolute references/redaction-policy.md path and 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, find marker line numbers, dispatch prompts/similar-session.md per candidate in parallel with the absolute references/context-safety.md path, and append report §9.