From d6d85dcbdff9c13fe19874196c67a8fa7fc58695 Mon Sep 17 00:00:00 2001
From: Jesse Vincent <jesse@fsck.com>
Date: Fri, 28 Aug 2026 10:26:30 -0700
Subject: [PATCH] feat(diagnosing-superpowers): case, report, bundle README,
 and issue templates

Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7
---
 .../templates/bundle-README.md                | 44 +++++++++++
 .../diagnosing-superpowers/templates/case.md  | 50 ++++++++++++
 .../diagnosing-superpowers/templates/issue.md | 49 ++++++++++++
 .../templates/report.md                       | 78 +++++++++++++++++++
 4 files changed, 221 insertions(+)
 create mode 100644 skills/diagnosing-superpowers/templates/bundle-README.md
 create mode 100644 skills/diagnosing-superpowers/templates/case.md
 create mode 100644 skills/diagnosing-superpowers/templates/issue.md
 create mode 100644 skills/diagnosing-superpowers/templates/report.md

diff --git a/skills/diagnosing-superpowers/templates/bundle-README.md b/skills/diagnosing-superpowers/templates/bundle-README.md
new file mode 100644
index 000000000..cf8628bf0
--- /dev/null
+++ b/skills/diagnosing-superpowers/templates/bundle-README.md
@@ -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` §1–2, 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.
diff --git a/skills/diagnosing-superpowers/templates/case.md b/skills/diagnosing-superpowers/templates/case.md
new file mode 100644
index 000000000..1a0e03c43
--- /dev/null
+++ b/skills/diagnosing-superpowers/templates/case.md
@@ -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>
diff --git a/skills/diagnosing-superpowers/templates/issue.md b/skills/diagnosing-superpowers/templates/issue.md
new file mode 100644
index 000000000..74a700758
--- /dev/null
+++ b/skills/diagnosing-superpowers/templates/issue.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.
diff --git a/skills/diagnosing-superpowers/templates/report.md b/skills/diagnosing-superpowers/templates/report.md
new file mode 100644
index 000000000..fa4f58e43
--- /dev/null
+++ b/skills/diagnosing-superpowers/templates/report.md
@@ -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 |
+|---|---|---|---|---|---|