mirror of
https://github.com/obra/superpowers.git
synced 2026-09-01 11:29:23 +00:00
feat(diagnosing-superpowers): case, report, bundle README, and issue templates
Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7
This commit is contained in:
@@ -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.
|
||||||
@@ -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 |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
Reference in New Issue
Block a user