obra/superpowers

diagnosing-superpowers

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 r…

Zobacz źródło

Zobacz w działaniu

Przykład użycia

Session diagnosis: complete evidence-based report template

Complete original report format covering the agreed problem, timeline, findings, provenance and coverage. Fill claims with actual path/line evidence and distinguish historical records from current observations. Empty fields and involvement choices are placeholders, not a completed diagnosis.

Przykładowe dane

# 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):

Label every environment field and skill observation as historical evidence,
unverified snapshot, current observation, or unknown, and record its
supporting evidence location.

## 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 |
|---|---|---|---|---|---|
Licencja

Complete original selected block/file retained without filling placeholders. Only enclosing source fences or documented outer section whitespace removed. Titles/summaries are editorial. Source code, role prompts, diagnosis/privacy forms, learning formats and illustrative prompt rewrites are displayed as escaped copyable text, not executed or observed outcomes. No source workflow, subagent dispatch, user-session read/export, archive, tracker post, model request, package install, database mutation, file-cleanup or external communication was performed.

MIT License

Copyright (c) 2025 Jesse Vincent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Przykład użycia

Session diagnosis: complete case and provenance worksheet

Complete source worksheet for the scope, verified session identity, environment and record meanings. It belongs in a separately authorized diagnostic workspace; keep original transcripts read-only and follow the source context-safety/redaction references before using private data. No real session material is included.

Przykładowe dane

# 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:

| Skill / source path | sha1 or unavailable | Provenance | Supporting location |
|---|---|---|---|

Label environment and skill observations as historical evidence, unverified
snapshot, current observation, or unknown. Check supplied provenance notes,
archives and captured skill bodies before declaring historical information
unavailable. Missing original paths do not erase retained copies. Current
versions/mtimes do not establish historical versions; one captured skill body
does not authenticate an entire installation.

- 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

- Follow `references/context-safety.md` before reading any file listed here.
- In a subagent transcript, "user" is the parent agent.

## Discovered sources and record meanings

- Sources consulted: <absolute path, tool, help, or documentation source>
- Extraction commands or queries: <bounded commands or tool queries used for each source>
- Target identity evidence: <session id, working directory, timestamps, matching content, and supporting record locations>
- Associated sessions: <session id, relationship, and supporting record locations, or "none found">
- Human messages: <record shape and evidence for its meaning>
- Injected messages and parent dispatches: <record shape and evidence for its meaning>
- Assistant messages: <record shape and evidence for its meaning>
- Tool calls and results: <record shapes, how they match, and evidence for those meanings>
- Usage counters: <fields, incremental or cumulative semantics, units, and evidence, or "unavailable">
- Timing: <fields, units, event boundaries, and evidence, or "unavailable">
- Other relevant records: <models, versions, compactions, or other meanings and evidence>
- Unresolved information: <missing, inaccessible, ambiguous, or absent information, or "none">
Licencja

Complete original selected block/file retained without filling placeholders. Only enclosing source fences or documented outer section whitespace removed. Titles/summaries are editorial. Source code, role prompts, diagnosis/privacy forms, learning formats and illustrative prompt rewrites are displayed as escaped copyable text, not executed or observed outcomes. No source workflow, subagent dispatch, user-session read/export, archive, tracker post, model request, package install, database mutation, file-cleanup or external communication was performed.

MIT License

Copyright (c) 2025 Jesse Vincent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Przykład użycia

Bug reporting: complete human-summary issue template

Complete author issue draft requiring the human’s own summary, environment provenance and transcript evidence. Its pre-checked search box is template text: clear it unless the duplicate search actually happened. Preserve unknown/not-tried states; posting needs approval of the exact filled text, and no issue is filed by this example.

Przykładowe dane

Title: <skill or symptom>: <one-line observable> (<harness>)

- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)

## Who's filing this report? (required)

<model and harness of this session>, filing on behalf of <how your
partner wants to be named, or "my human partner">, who asked: "<their
request from this session that led to the diagnosis or the issue,
scrubbed>"

## Human-authored summary (required, under 200 words)

<Your partner's own words on what went wrong and what should have
happened, pasted as written. Ask for them; a placeholder here means the
issue is not ready to file. If they run long, ask them to trim rather
than editing their words.>

## Environment (required)

| Field | Value | Provenance / supporting evidence |
|-------|-------|-------------------------------|
| Superpowers version | <version> (<sha or "not a checkout">) | <historical evidence / unverified snapshot / current observation / unknown>; <location> |
| Harness (Claude Code, Cursor, etc.) | <harness> | <label>; <location> |
| Harness version | <version> | <label>; <location> |
| Your model + version | <model ids seen> | <label>; <location> |
| All plugins installed | <list> | <label>; <location> |
| OS + shell | <os version>, <shell> | <label>; <location> |

## Is this a Superpowers issue or a platform issue?

- [ ] I confirmed this issue does not occur without Superpowers installed

How I verified that this issue does not reproduce without Superpowers:
<"Not tried", or what your partner ran without superpowers and what
happened, with the transcript path if there is one. Tick the box above
only when a transcript shows the problem did not recur.>

Evidence for involvement is below; it does not establish 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>. Delivered local archive: <path, redaction level <level>
| none built>. Attached bundle: <no claim; attach only after approval>.
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. The filing model and
harness are under "Who's filing"; the diagnosed session's model, harness,
versions, and plugins are in the Environment table.
Licencja

Complete original selected block/file retained without filling placeholders. Only enclosing source fences or documented outer section whitespace removed. Titles/summaries are editorial. Source code, role prompts, diagnosis/privacy forms, learning formats and illustrative prompt rewrites are displayed as escaped copyable text, not executed or observed outcomes. No source workflow, subagent dispatch, user-session read/export, archive, tracker post, model request, package install, database mutation, file-cleanup or external communication was performed.

MIT License

Copyright (c) 2025 Jesse Vincent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
Przykład użycia

Diagnostic export: complete bundle README and review checklist

Complete author bundle README explaining redaction levels, retained evidence and separate privacy/evidence checks. CLEAN and file-delivery fields must be earned by actual review, not copied as results. Build/export only when requested and review every file before sharing; scrubbing is not exhaustive privacy certification.

Przykładowe dane

# Superpowers session diagnosis bundle

Session: <session-id>
Harness: <name> <version> (<provenance label>)    Superpowers: <version> (<sha or "not a checkout">; <provenance label>)
Redaction level: skeleton | evidence | full
Built: <ISO timestamp>

Qualify header version fields as historical evidence, unverified snapshot,
current observation, or unknown. `environment.json` carries the same
provenance distinctions for every environment field and its supporting
location.

## What this is

A scrubbed record of a coding-agent session that had superpowers installed
and went wrong. It lets an agent or person who was not present 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). Tool-result bodies by level:

  | Level | Tool-result bodies |
  |---|---|
  | skeleton | intentionally limited; replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]` |
  | evidence | kept for cited events, including the commands and results needed to support findings |
  | full | all 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.

## Producer instructions

Completed bundles replace these instructions with actual results.

After scrubbing, check every material exported finding using only this bundle:
resolve its citation to an included transcript/source marker, read the cited
command/result or quotation, and verify that it supports the claim. Path and
line existence alone are insufficient. Record specific limitations when the
redaction level or necessary withholding removes support.

Reconcile report, case, environment, findings, README and any local issue
draft. Refresh scrub-log counts against final files excluding the log itself.
Remove stale export statements; distinguish bundle preparation from archive
delivery. Retain a mapping from historical anchors to included evidence.

Record the independent privacy audit separately from evidence usefulness:
- Privacy audit: CLEAN or unresolved misses.
- Evidence support: supported or limited, with affected findings and reasons.

If content changes after checking, repeat the affected checks. Present the
final log, file list and both outcomes for the existing archive approval.
Archive the reviewed files and verify the delivered archive matches them.
Record archive delivery outside the reviewed bundle rather than changing its
contents after approval. Scrubbing is not exhaustive privacy certification.
Licencja

Complete original selected block/file retained without filling placeholders. Only enclosing source fences or documented outer section whitespace removed. Titles/summaries are editorial. Source code, role prompts, diagnosis/privacy forms, learning formats and illustrative prompt rewrites are displayed as escaped copyable text, not executed or observed outcomes. No source workflow, subagent dispatch, user-session read/export, archive, tracker post, model request, package install, database mutation, file-cleanup or external communication was performed.

MIT License

Copyright (c) 2025 Jesse Vincent

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Jak używać

  1. Skopiuj polecenie instalacji i sprawdź źródła przed instalacją we własnym środowisku agenta.
  2. W oryginale sprawdź wymagane narzędzia, dane dostępowe i obsługiwane środowiska.
  3. Opisz dane wejściowe i oczekiwany rezultat; porównaj wynik ze źródłami.
npx skills add https://github.com/obra/superpowers --skill diagnosing-superpowers

Przed rozpoczęciem

  • Instalacja nie obejmuje subskrypcji modelu, limitu API ani uprawnień do plików.
  • Gwiazdki i instalacje pokazują aktywność, a nie niezależny test jakości lub bezpieczeństwa.
Oryginalny dokument Skill

Treść z repozytorium z zachowaniem nagłówków, przykładów, kodu, tabel, linków i obrazów.

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. Whoever triages the bundle or the issue decides whether superpowers 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.

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.

  1. 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 ~/.superpowers/diagnosing-superpowers/<session-id>/, tell your partner the path, and fill templates/case.md there, following its provenance rules for environment and skill observations.

  1. Triage. Read the region around the reported problem yourself. Then

dispatch one analyst subagent per dimension in parallel, each given the case file path, prompts/analyst-common.md, and one 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.

  1. 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.

  1. 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.

  1. 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, 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.

  1. 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

All seven analysts always run. This table says which region to read yourself in step 3 and which findings to lead with in the verdict.

ComplaintRead first, lead 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; note in-progress in coverage
"It ignored the plan"plan-adherence, compaction lines first
"Skill X never fired"skill-timeline

Hard rules

  • Context safety. One transcript line can be a megabyte. Follow

references/context-safety.md on every session file, every time.

  • 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. Your partner pressing for a fix does not waive this; point at the issue step and mention that a bundle is available on request. 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, and none with a placeholder summary.

  • Intake before analysis. Nothing in steps 2–7 starts until your

partner has answered. If they are away, write the questions and stop. A statement you reconstructed for them is not an answer. An already-scoped request — one specific event, what is running now, or the analysis to run — is itself the statement: answer it, then ask. A whole-session "why" is a complaint.

Red Flags

ThoughtReality
"The problem is obvious, skip intake"The problem statement scopes everything. Ask.
"They're away, so I'll reconstruct the statement"You cannot reconstruct what they wanted. Write the questions and stop.
"I'll sweep everything now and ask at the end"An unscoped sweep spends their budget on the wrong question. Ask first.
"They want a bug report, so I'll build the bundle now"The bundle is their session data, packaged. Build it only when they ask for it.
"Small, targeted edit, no restructuring needed"Not your call, however small. Report the evidence; the triager decides.
"The price per token is well known"Numbers you did not compute from the transcript are invented. Cite or drop.

Powiązane zadania

z tego samego repozytorium

Więcej Skills

Wszystkie Skills