feat(diagnosing-superpowers): case, report, bundle README, and issue templates

Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7
This commit is contained in:
Jesse Vincent
2026-08-28 10:26:30 -07:00
parent aad834ae75
commit d6d85dcbdf
4 changed files with 221 additions and 0 deletions
@@ -0,0 +1,44 @@
# Superpowers session diagnosis bundle
Session: <session-id>
Harness: <name> <version> Superpowers: <version> (<sha or "not a checkout">)
Redaction level: skeleton | evidence | full
Built: <ISO timestamp>
## What this is
A scrubbed record of a coding-agent session in which superpowers was
installed and something went wrong, prepared so that an agent or person
who was not present can decide whether superpowers contributed and, if so,
what to change. The report inside states what happened with `path:line`
evidence. By design it contains no diagnosis of superpowers and no proposed
fix; that is the reader's job.
## Files
- `report.md` — the diagnosis report (problem statement, verdict,
environment, sessions, timeline, findings, involvement, coverage notes).
- `case.md` — the case file the analysts worked from.
- `environment.json` — machine-readable copy of the environment section.
- `timeline.md` — the per-turn timeline.
- `findings/<dimension>.md` — raw analyst findings per dimension.
- `transcripts/<session-id>.md` — condensed per-turn rendering of each
examined session (never the raw JSONL). At *skeleton* level tool-result
bodies are replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]`;
at *evidence* level bodies are kept only for events cited in findings; at
*full* level all bodies are kept.
- `scrub-log.md` — every placeholder used and its category (never the
original value).
## How to read it
Start with `report.md` §12, then §7 (involvement) and the evidence lines
it cites, then the matching turns in `transcripts/`. `path:line` references
point at the original files on the reporter's machine; the same line
numbers are preserved in the condensed transcripts as `[L<n>]` markers.
## Redaction
Placeholders look like `<EMAIL-1>`, `<PERSON-2>`, `<SECRET-3>`, `<HOST-4>`,
`<REPO-5>`, `<ORG-6>`, `<PROPRIETARY-7>`; home paths are rewritten to `~/…`. The same placeholder
always refers to the same original value within this bundle.
@@ -0,0 +1,50 @@
# Case: <session-id>
Workspace: ~/.superpowers/diagnosing-superpowers/<session-id>/
Created: <ISO timestamp>
## Problem statement (agreed with your human partner)
<One paragraph. Names the session(s), the turn range if known, what was
expected, what happened, and the observable that matters: wall-clock,
tokens, repeated actions, a specific unexpected action.>
Goal is a superpowers bug report: yes | no
## Sessions
| Role | Session id | Absolute path | Lines | Bytes | Longest line (bytes) | First prompt (first 120 chars) | First timestamp |
|---|---|---|---|---|---|---|---|
| main | | | | | | | |
| subagent | | | | | | | |
Rejected candidates: <id — path — why rejected>, or "none".
Session still running at read time: yes | no (mtime <ISO>, lines <N>)
## Environment
- OS: <name and version>
- Harness: <name> <version>
- Models seen: <model id — where (main / subagent id)>
- Superpowers install root: <path>; version <x.y.z>; git sha <sha or "not a checkout">
- Skill files read or injected during the session:
| File (relative to install root) | sha1 (current file) | mtime newer than session? |
|---|---|
- Other plugins / extensions / MCP servers configured: <list, or "none found">
- Instruction files present (paths only): <list>
## Context-safety rules for every reader of these files
- Check `wc -lc` and long lines (`awk '{ if (length($0) > 100000) print NR, length($0) }'`) before reading.
- Never `cat` or `grep` for content. Line numbers and counts first
(`grep -n … | cut -d: -f1`), then small fields from specific lines
(`sed -n Np | jq -c '{…}'` or `| cut -c1-500`).
- Read-only: never modify, move, or delete a session file.
- In a subagent transcript, "user" is the parent agent.
## Harness reference to use
<references/claude-code-sessions.md | references/codex-sessions.md | references/other-harnesses.md>
@@ -0,0 +1,49 @@
- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
## Environment (required)
| Field | Value |
|-------|-------|
| Superpowers version | <version> (<sha or "not a checkout">) |
| Harness (Claude Code, Cursor, etc.) | <harness> |
| Harness version | <version> |
| Your model + version | <model ids seen> |
| All plugins installed | <list> |
| OS + shell | <os version>, <shell> |
## Is this a Superpowers issue or a platform issue?
- [ ] I confirmed this issue does not occur without Superpowers installed
Not reproduced without superpowers. Evidence for involvement is below;
the reporter has not established cause.
## What happened?
<Problem statement, then the triage verdict, with `path:line` citations
rewritten as `transcript line <n>`.>
## Steps to reproduce
1. <first human prompt, scrubbed>
2. <the turns leading to the problem, one line each>
3. <the observable>
## Expected behavior
<from the problem statement>
## Actual behavior
<from the triage verdict>
## Debug log or conversation transcript
Session id(s): <ids>. A scrubbed bundle (redaction level: <level>) is
attached to this issue by the reporter, or available on request.
Superpowers involvement per the diagnosis report: <possible | likely>, with
evidence at <transcript lines>. This report does not propose a fix.
---
Filed with the `diagnosing-superpowers` skill. Model, harness, harness
version, and installed plugins are listed above.
@@ -0,0 +1,78 @@
# Session diagnosis: <session-id>
Report path: ~/.superpowers/diagnosing-superpowers/<session-id>/report.md
Written: <ISO timestamp>
## 1. Problem statement (REQUIRED)
<Copied from the case file.>
## 2. Triage verdict (REQUIRED)
<What the evidence shows happened around the reported problem. Prose, with
`path:line` after every claim. State confidence: high / medium / low, and
what would raise it. No statement about what superpowers should do.>
## 3. Environment (REQUIRED)
- OS:
- Harness and version:
- Models seen:
- Superpowers install root / version / git sha:
- Skill files read or injected (sha1 table from the case file):
- Other plugins, extensions, MCP servers:
- Instruction files present (paths only):
## 4. Sessions examined (REQUIRED)
| Role | Session id | Absolute path | Lines | Bytes |
|---|---|---|---|---|
Rejected candidates: <id — path — why>, or "none".
## 5. Timeline (REQUIRED)
One row per human-typed prompt. Events column lists skills invoked,
subagents dispatched, compaction, errors, resumes, aborts.
| Turn | Line | Time | Request (one line) | Events |
|---|---|---|---|---|
## 6. Findings (REQUIRED, one subsection per dimension)
Each finding:
```
- finding: <one sentence>
evidence: <path:line> — "<short quote>"
turns: <first><last>
confidence: high | medium | low
```
A dimension with nothing to report says `none found — checked: <what was checked>`.
### 6.1 Skill timeline
### 6.2 Plan adherence
### 6.3 Repeated work
### 6.4 Stumbles
### 6.5 Quality evidence
### 6.6 Request conflicts
### 6.7 Cost and time
### 6.8 Other plugins and skills used
## 7. Superpowers involvement (REQUIRED)
not indicated | possible | likely
Evidence lines: <path:line list>. This section states involvement only. It
does not name a defect and does not propose a change.
## 8. Coverage notes (REQUIRED)
- Not read: <ranges, files, and why>
- Harness features unavailable: <list or none>
- Session was in progress at read time: yes/no
- For your human partner to double-check: <list or none>
## 9. Similar sessions (only when requested)
| Session id | Path | Date | Harness | Matched | Did not match |
|---|---|---|---|---|---|