diff --git a/.github/ISSUE_TEMPLATE/diagnosis_report.md b/.github/ISSUE_TEMPLATE/diagnosis_report.md new file mode 100644 index 000000000..13f7b4924 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/diagnosis_report.md @@ -0,0 +1,42 @@ +--- +name: Session Diagnosis Report +about: A report produced by the diagnosing-superpowers skill from a real session transcript +labels: bug, automated-issue-report +--- + + + +- [ ] I searched existing issues and this is not a duplicate + +## Environment (required) + +| Field | Value | +|-------|-------| +| Superpowers version | | +| Harness (Claude Code, Cursor, etc.) | | +| Harness version | | +| Your model + version | | +| All plugins installed | | +| OS + shell | | + +## Is this a Superpowers issue or a platform issue? + +- [ ] I confirmed this issue does not occur without Superpowers installed + +## What happened? + +## Steps to reproduce +1. +2. +3. + +## Expected behavior + +## Actual behavior + +## Debug log or conversation transcript diff --git a/.github/ISSUE_TEMPLATE/platform_support.md b/.github/ISSUE_TEMPLATE/platform_support.md index 277dd1ee9..31faa68b9 100644 --- a/.github/ISSUE_TEMPLATE/platform_support.md +++ b/.github/ISSUE_TEMPLATE/platform_support.md @@ -1,7 +1,7 @@ --- name: IDE / Platform Support Request about: Request support for a new IDE, editor, or AI coding tool -labels: platform-support +labels: new-harness --- + +## Rationalizations observed + + + +## With skill (GREEN) + +## Micro-tests + +## Refactor rounds +```` + +- [ ] **Step 2: Run each baseline scenario** + +For scenarios 1–10 (and the baseline replacement for 11), dispatch one fresh general-purpose subagent with the preamble plus the scenario text, `` replaced by the fixture path from the Local fixtures table. Do not mention this skill, the spec, or the plan in the prompt. Record the full response under `## Baseline (RED)` as `### Scenario N — ` followed by a fenced block with the verbatim response, then a `Violations:` list. + +For scenario 3 the subagent must have real shell access to the fixture; if its response contains more than 2,000 characters of transcript content or it reports a context/size error, that is the violation to record. + +- [ ] **Step 3: Extract rationalizations** + +Read every baseline response. Copy each phrase an agent used to justify skipping intake, proposing a superpowers fix, reading the whole file, archiving without review, or posting without approval into `## Rationalizations observed` as `- (N) ""`. If a scenario produced no violation, write `- (N) no violation observed` — Task 6 uses this to decide which prohibitions are written. + +- [ ] **Step 4: Commit** + +```bash +git add skills/diagnosing-superpowers/CREATION-LOG.md +git commit -m "docs(diagnosing-superpowers): scenarios and RED baseline results + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 2: Structure test and harness references + +**Files:** +- Create: `tests/diagnosing-superpowers/test-skill-structure.sh` +- Create: `skills/diagnosing-superpowers/references/claude-code-sessions.md` +- Create: `skills/diagnosing-superpowers/references/codex-sessions.md` +- Create: `skills/diagnosing-superpowers/references/other-harnesses.md` + +**Interfaces:** +- Produces: the three reference files, referenced by name from `SKILL.md` (Task 6) and from every analyst prompt (Task 4). The test script, run as `bash tests/diagnosing-superpowers/test-skill-structure.sh`, exits 0 only when every check passes; until Task 6 lands `SKILL.md` it fails on the SKILL.md checks, which is the intended RED state. + +- [ ] **Step 1: Write the structure test** + +```bash +#!/usr/bin/env bash +# Structural checks for skills/diagnosing-superpowers. Behavior is tested by +# the scenarios in CREATION-LOG.md; this script only checks the things a +# shell can check: frontmatter, referenced files exist, no local paths or +# names leaked into shipped files, SKILL.md word budget. +set -u + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +SKILL_DIR="$REPO_ROOT/skills/diagnosing-superpowers" +SKILL_MD="$SKILL_DIR/SKILL.md" +WORD_BUDGET=1000 + +PASSES=0 +FAILURES=0 + +pass() { echo " [PASS] $1"; PASSES=$((PASSES + 1)); } +fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); } + +echo "diagnosing-superpowers structure" + +# --- SKILL.md frontmatter ------------------------------------------------- +if [ -f "$SKILL_MD" ]; then + pass "SKILL.md exists" + frontmatter="$(awk 'NR==1 && $0!="---"{exit} NR>1 && $0=="---"{exit} NR>1{print}' "$SKILL_MD")" + if printf '%s\n' "$frontmatter" | grep -q '^name: diagnosing-superpowers$'; then + pass "frontmatter name is diagnosing-superpowers" + else + fail "frontmatter name is diagnosing-superpowers" + fi + description="$(printf '%s\n' "$frontmatter" | awk '/^description:/{sub(/^description:[ ]*/,""); print; found=1; next} found && /^[ ]/{print} found && !/^[ ]/{exit}' | tr '\n' ' ')" + if printf '%s' "$description" | grep -q '^Use when'; then + pass "description starts with 'Use when'" + else + fail "description starts with 'Use when' (got: ${description:0:60})" + fi + if [ "${#description}" -le 1024 ]; then + pass "description under 1024 characters" + else + fail "description under 1024 characters (${#description})" + fi + for banned in "dispatch" "then" "step"; do + if printf '%s' "$description" | grep -qiw "$banned"; then + fail "description contains workflow word '$banned'" + else + pass "description avoids workflow word '$banned'" + fi + done + + # --- word budget -------------------------------------------------------- + body_words="$(awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=2; next} fm==2{print}' "$SKILL_MD" | wc -w | tr -d ' ')" + if [ "$body_words" -le "$WORD_BUDGET" ]; then + pass "SKILL.md body within $WORD_BUDGET words ($body_words)" + else + fail "SKILL.md body within $WORD_BUDGET words ($body_words)" + fi + + # --- required sections -------------------------------------------------- + for heading in "## Hard rules" "## Red Flags"; do + if grep -q "^$heading" "$SKILL_MD"; then + pass "SKILL.md has section '$heading'" + else + fail "SKILL.md has section '$heading'" + fi + done + + # --- every referenced skill file exists -------------------------------- + while IFS= read -r ref; do + if [ -f "$SKILL_DIR/$ref" ]; then + pass "referenced file exists: $ref" + else + fail "referenced file exists: $ref" + fi + done < <(grep -o '\(references\|prompts\|templates\)/[A-Za-z0-9._-]*\.md' "$SKILL_MD" | sort -u) +else + fail "SKILL.md exists" +fi + +# --- expected files ------------------------------------------------------- +expected_files=( + references/claude-code-sessions.md + references/codex-sessions.md + references/other-harnesses.md + prompts/skill-timeline.md + prompts/plan-adherence.md + prompts/repeated-work.md + prompts/stumbles.md + prompts/quality-evidence.md + prompts/request-conflicts.md + prompts/cost-and-time.md + prompts/scrub.md + prompts/scrub-audit.md + prompts/similar-session.md + templates/case.md + templates/report.md + templates/bundle-README.md + templates/issue.md + CREATION-LOG.md +) +for rel in "${expected_files[@]}"; do + if [ -f "$SKILL_DIR/$rel" ]; then + pass "expected file present: $rel" + else + fail "expected file present: $rel" + fi +done + +# --- no local paths or names in shipped files ---------------------------- +leaks="$(grep -rn -E '/Users/|/home/|jesse' "$SKILL_DIR" 2>/dev/null || true)" +if [ -z "$leaks" ]; then + pass "no machine-specific paths or names in shipped files" +else + fail "no machine-specific paths or names in shipped files" + printf '%s\n' "$leaks" | head -10 | sed 's/^/ /' +fi + +# --- "the user" never appears in skill prose ----------------------------- +user_hits="$(grep -rn -i 'the user' "$SKILL_DIR" --include='*.md' 2>/dev/null | grep -v CREATION-LOG.md || true)" +if [ -z "$user_hits" ]; then + pass "skill files say 'your human partner', not 'the user'" +else + fail "skill files say 'your human partner', not 'the user'" + printf '%s\n' "$user_hits" | head -10 | sed 's/^/ /' +fi + +echo +echo "Passed: $PASSES Failed: $FAILURES" +[ "$FAILURES" -eq 0 ] +``` + +- [ ] **Step 2: Run the test and confirm it fails** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: exits 1; `[FAIL] SKILL.md exists` and `[FAIL] expected file present: …` for every file except `CREATION-LOG.md`. + +- [ ] **Step 3: Write `references/claude-code-sessions.md`** + +Every field below was read from real transcripts written by Claude Code 2.1.247 on 2026-08-27. Keep the "Verified against" line current when re-verifying. + +````markdown +# Claude Code session store + +Verified against: Claude Code 2.1.247 (transcript `version` field), macOS. +When a field below is missing from the file in front of you, trust the file +and say so in coverage notes. + +## Where + +- Main transcript: `~/.claude/projects//.jsonl`, where + `` is the working directory with every `/` replaced by `-` + (e.g. `/tmp/work` → `-tmp-work`). +- Subagent transcripts: `~/.claude/projects///subagents/agent-.jsonl`, + each with a sibling `agent-.meta.json` + (`agentType`, `description`, `toolUseId`, `spawnDepth`, optional `model`). +- Plugin registry: `~/.claude/plugins/installed_plugins.json` — per plugin: + `installPath`, `version`, `installedAt`, `lastUpdated`, `gitCommitSha`. +- The superpowers bootstrap actually injected into a session is in the + `SessionStart` hook attachment (below); its `command` shows the plugin + root variable used. A dev checkout loaded with `--plugin-dir` will not be + in the registry, so report both the registry entry and the hook evidence. + +## Which file is the current session + +The most recently modified `.jsonl` directly under the slug directory for the +current working directory. Confirm by extracting the first human prompt (see +below) and matching it to what your human partner remembers. If two files +are close in mtime, show both first prompts and ask. + +## Line types + +Every line is one JSON object. `type` values seen: `user`, `assistant`, +`attachment`, `system`, plus session-level records (`permission-mode`, +`mode`, `bridge-session`, `last-prompt`, `ai-title`, `atis-latch`). + +Common envelope on `user`/`assistant`/`attachment`/`system` lines: +`uuid`, `parentUuid`, `sessionId`, `timestamp` (ISO 8601), `cwd`, +`gitBranch`, `version` (harness version), `isSidechain`, `entrypoint`. + +| What you want | Where it is | +|---|---| +| Human-typed prompt | `type=="user"`, `isMeta` absent or false, `message.content` is a string or a list whose first block is `type:"text"`. Lines whose first block is `tool_result` are tool results, not prompts. `` text inside a prompt is injected, not typed. | +| Assistant text / tool calls | `type=="assistant"`, `message.content[]` blocks of `type:"text"` or `type:"tool_use"` (`id`, `name`, `input`). | +| Tool result | `type=="user"`, `message.content[0].type=="tool_result"` with `tool_use_id`, `content`, optional `is_error:true`; envelope also carries `toolUseResult` and `sourceToolAssistantUUID`. | +| Model | `message.model` on assistant lines. | +| Tokens | `message.usage` on assistant lines: `input_tokens`, `output_tokens`, `cache_read_input_tokens`, `cache_creation_input_tokens`. | +| Skill invocation | `tool_use` block with `name:"Skill"` and `input.skill` (e.g. `superpowers:brainstorming`); the tool result line has `toolUseResult.commandName`. | +| Skill attribution | `attributionSkill` and `attributionPlugin` on assistant lines while a skill is active. | +| Subagent dispatch | `tool_use` with `name:"Agent"` (`input.description`, `input.subagent_type`, `input.prompt`); the subagent's own file is matched by `toolUseId` in its `.meta.json`. Subagent lines have `isSidechain:true` and `agentId`. | +| Hook output | `type=="attachment"`, `attachment.type` `hook_success`/`hook_failure`, `attachment.hookName` (e.g. `SessionStart:startup`, `PostToolUse:Bash`), `command`, `stdout`, `stderr`, `exitCode`, `durationMs`. | +| Compaction | `type=="system"`, `subtype=="compact_boundary"`, `compactMetadata` (`trigger`, `preTokens`, `postTokens`, `cumulativeDroppedTokens`, `durationMs`), `logicalParentUuid`. | +| Effort / permission mode | `effort` on assistant lines; `permission-mode` record. | + +## Safe extraction + +Lines can exceed a megabyte. Never print a whole line. Check size first: + +```bash +F=~/.claude/projects//.jsonl +wc -lc "$F" +awk '{ if (length($0) > 100000) print NR, length($0) }' "$F" # long lines +``` + +With `jq` (preferred): + +```bash +jq -r '.type' "$F" | sort | uniq -c # line-type census +jq -r 'select(.type=="user" and .isMeta!=true and ((.message.content|type)=="string" or .message.content[0].type=="text")) + | "\(input_line_number)\t\(.timestamp)\t\((.message.content|if type=="string" then . else .[0].text end)[0:160])"' "$F" # human prompts +jq -c 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use") + | {name, id, input: (.input|tostring|.[0:120])}' "$F" # tool calls +jq -r 'select(.type=="assistant") | .message.content[]? | select(.type=="tool_use" and .name=="Skill") | .input.skill' "$F" # skill invocations +jq -c 'select(.type=="assistant") | {ts:.timestamp, model:.message.model, skill:.attributionSkill, + u:(.message.usage|{input_tokens,output_tokens,cache_read_input_tokens,cache_creation_input_tokens})}' "$F" # per-message usage +jq -c 'select(.subtype=="compact_boundary") | {line:input_line_number, ts:.timestamp, m:.compactMetadata}' "$F" # compactions +jq -c 'select(.type=="attachment" and (.attachment.type|startswith("hook"))) | {line:input_line_number, hook:.attachment.hookName, exit:.attachment.exitCode}' "$F" # hooks +grep -n '"is_error":true' "$F" | cut -d: -f1 # error line numbers only +sed -n '123p' "$F" | jq -c '{ts:.timestamp, first:(.message.content[0]|tostring|.[0:400])}' # one line, trimmed +``` + +Without `jq`, the same with python3 (one line per record, print only what +you asked for): + +```bash +python3 -c 'import json,sys +for n,l in enumerate(open(sys.argv[1]),1): + o=json.loads(l) + if o.get("type")=="assistant": + for b in o["message"].get("content",[]): + if b.get("type")=="tool_use": print(n, b["name"], str(b.get("input"))[:120])' "$F" +``` + +## Subagents + +List `~/.claude/projects///subagents/`. For each `agent-*.meta.json` +print `agentType`, `description`, `model`; the matching `.jsonl` is that +subagent's transcript and follows the same line format. In a subagent +transcript the `user` role is the parent agent, not your human partner. +```` + +- [ ] **Step 4: Write `references/codex-sessions.md`** + +````markdown +# Codex session store + +Verified against: Codex CLI 0.147.0 and 0.149.0 rollouts (`cli_version` in +`session_meta`), macOS. When a field below is missing from the file in front +of you, trust the file and say so in coverage notes. + +## Where + +`~/.codex/sessions/YYYY/MM/DD/rollout--.jsonl`. +Subagent threads are separate rollout files whose `session_meta.payload` +has `thread_source: "subagent"` and `source.subagent.thread_spawn.parent_thread_id` +pointing at the parent thread id. Root sessions have `thread_source: "user"`. + +## Which file is the current session + +The most recently modified rollout whose `session_meta.payload.cwd` is the +current working directory and whose `thread_source` is `user`. Confirm by +matching the first `user_message` event to what your human partner +remembers. + +## Line types + +Every line is `{timestamp, type, payload}` (some also carry `ordinal`). +`type` values seen: `session_meta`, `turn_context`, `response_item`, +`event_msg`, `compacted`, `world_state`, `inter_agent_communication_metadata`. + +| What you want | Where it is | +|---|---| +| Session identity | `session_meta.payload`: `id`, `session_id`, `cwd`, `originator` (e.g. `Codex Desktop`), `cli_version`, `model_provider`, `thread_source`, `source`, `git` (`commit_hash`, `branch`, `repository_url`), `base_instructions.text`. | +| Model per turn | `turn_context.payload`: `turn_id`, `model`, `effort`, `cwd`, `approval_policy`, `sandbox_policy`, `multi_agent_version`. Also `event_msg` `thread_settings_applied`. | +| Human-typed prompt | `event_msg` with `payload.type=="user_message"`: `payload.message`. (`response_item` messages with `role:"developer"` or `` text are injected, not typed.) | +| Assistant text | `event_msg` `agent_message` (`payload.message`, `payload.phase`) or `response_item` `message` with `role:"assistant"`. | +| Tool calls | `response_item` with `payload.type` `function_call` (`name`, `arguments`, `call_id`) or `custom_tool_call` (`name`, `input`, `call_id`); outputs are `function_call_output` / `custom_tool_call_output` matched by `call_id`. Also `event_msg` `patch_apply_end` (`success`, `changes`), `web_search_end`, `mcp_tool_call_end` (`invocation.server`, `invocation.tool`). | +| Turn timing | `event_msg` `task_started` (`turn_id`, `started_at`, `model_context_window`) and `task_complete` (`duration_ms`, `time_to_first_token_ms`, `last_agent_message`); `turn_aborted` (`reason`, `duration_ms`). | +| Tokens | `event_msg` `token_count`: `payload.info.total_token_usage` (cumulative; keys include `input_tokens`, `cached_input_tokens`, `output_tokens`) and `payload.rate_limits`. | +| Compaction | a `compacted` line (`window_id`, `previous_window_id`, `replacement_history`) and an `event_msg` `context_compacted`. | +| Subagents | `event_msg` `sub_agent_activity` (`agent_thread_id`, `agent_path`, `kind`); `response_item` `agent_message` with `author`/`recipient`; the child's own rollout file (see Where). | +| Skill use | No attribution field. Look for `SKILL.md` in `function_call.arguments` / `custom_tool_call.input` and in `world_state`/`session_meta` instruction text. | +| Reasoning | `response_item` `reasoning` (`summary[].text`; `encrypted_content` is opaque). | + +## Safe extraction + +Rollouts reach hundreds of megabytes; `compacted` lines embed whole +histories. Never print a whole line. Check size first: + +```bash +F=~/.codex/sessions/YYYY/MM/DD/rollout-....jsonl +wc -lc "$F" +awk '{ if (length($0) > 100000) print NR, length($0) }' "$F" +``` + +With `jq`: + +```bash +head -1 "$F" | jq '.payload | {id, cwd, originator, cli_version, model_provider, thread_source, git}' # identity +jq -r '.type + "/" + (.payload.type // "")' "$F" | sort | uniq -c # census +jq -r 'select(.type=="event_msg" and .payload.type=="user_message") | "\(input_line_number)\t\(.timestamp)\t\(.payload.message[0:160])"' "$F" # human prompts +jq -r 'select(.type=="turn_context") | "\(.timestamp)\t\(.payload.model)\t\(.payload.effort)"' "$F" # model per turn +jq -c 'select(.type=="response_item" and (.payload.type=="function_call" or .payload.type=="custom_tool_call")) + | {line:input_line_number, name:.payload.name, args:((.payload.arguments // .payload.input)|tostring|.[0:120])}' "$F" # tool calls +jq -c 'select(.payload.type=="task_complete" or .payload.type=="turn_aborted") | {ts:.timestamp, type:.payload.type, ms:.payload.duration_ms}' "$F" # turn timing +jq -c 'select(.payload.type=="token_count") | {ts:.timestamp, t:.payload.info.total_token_usage}' "$F" # tokens (cumulative) +grep -n '"type":"compacted"\|"context_compacted"' "$F" | cut -d: -f1 # compaction line numbers +grep -n 'SKILL\.md' "$F" | cut -d: -f1 # skill-read line numbers +sed -n '123p' "$F" | jq -c '{ts:.timestamp, type, p:(.payload|tostring|.[0:400])}' # one line, trimmed +``` + +Find a thread's subagent rollouts (filenames only, never content): + +```bash +grep -l '"parent_thread_id":""' ~/.codex/sessions/*/*/*/rollout-*.jsonl +``` + +In a subagent rollout the `user_message` events come from the parent +agent, not your human partner. +```` + +- [ ] **Step 5: Write `references/other-harnesses.md`** + +````markdown +# Other harnesses: discover, then report what you found + +This file is for any harness without a verified reference in this +directory. You know your own harness better than this file does. Use that +knowledge, and write down exactly what you found so the report reader can +judge it. + +## Procedure + +1. **Ask the harness.** Many harnesses expose a session or history command + (` session list`, `/sessions`, a "resume" picker). Use it to get + the session id and, if shown, the file path. +2. **Look under the harness's config directory** (`~/./`, + `~/.config//`, `~/.local/share//`) for `sessions`, + `history`, `chats`, `threads`, or `projects` directories holding `.jsonl` + or `.json` files. +3. **Confirm a candidate** by extracting its first human message with a + size-safe command (`head -c 2000`, or `jq` on the first record) and + matching it to what your human partner remembers. Never print whole + lines; treat every candidate like the verified stores: `wc -lc` and a + long-line check before anything else. +4. **Map the fields you need** by reading a handful of records with `jq -c + 'keys'` or `head -c`: human prompt, assistant text, tool call and result, + model, harness version, timestamps, subagent linkage, compaction. +5. **Record in the case file and the report's coverage notes**: the store + path, the layout you inferred, which of the fields above you could and + could not find, and your confidence. Field-level claims in the report + are marked "inferred from the file, not a documented format". +6. **If you cannot find the store**, say so and ask your human partner for + the path. Do not guess a layout from another harness. +```` + +- [ ] **Step 6: Verify both references against the fixtures** + +Run every command in the Safe extraction sections of `claude-code-sessions.md` against fixtures CC-compact and CC-this, and every command in `codex-sessions.md` against CX-big and CX-sub. Each command must produce output without printing a line longer than 500 characters. Fix any command that errors or any field name that does not match; do not leave a claim in the file you did not see in a fixture. + +- [ ] **Step 7: Run the structure test** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: `[PASS] expected file present: references/…` for all three references; `[PASS] no machine-specific paths or names in shipped files`; still failing on SKILL.md and the prompt/template files. + +- [ ] **Step 8: Commit** + +```bash +git add tests/diagnosing-superpowers/test-skill-structure.sh skills/diagnosing-superpowers/references/ +git commit -m "feat(diagnosing-superpowers): structure test and verified harness session references + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 3: Output templates + +**Files:** +- Create: `skills/diagnosing-superpowers/templates/case.md` +- Create: `skills/diagnosing-superpowers/templates/report.md` +- Create: `skills/diagnosing-superpowers/templates/bundle-README.md` +- Create: `skills/diagnosing-superpowers/templates/issue.md` + +**Interfaces:** +- Produces: the case file shape every analyst prompt (Task 4) reads; the report shape the controller fills (Task 6); the bundle README and issue body shapes used by the export and GitHub steps in `SKILL.md`. +- Every `REQUIRED` slot is filled or replaced with `none found — checked: `; a slot is never deleted. + +- [ ] **Step 1: Write `templates/case.md`** + +````markdown +# Case: + +Workspace: ~/.superpowers/diagnosing-superpowers// +Created: + +## Problem statement (agreed with your human partner) + + + +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: , or "none". + +Session still running at read time: yes | no (mtime , lines ) + +## Environment + +- OS: +- Harness: +- Models seen: +- Superpowers install root: ; version ; git sha +- 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: +- Instruction files present (paths only): + +## 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 + + +```` + +- [ ] **Step 2: Write `templates/report.md`** + +````markdown +# Session diagnosis: + +Report path: ~/.superpowers/diagnosing-superpowers//report.md +Written: + +## 1. Problem statement (REQUIRED) + + + +## 2. Triage verdict (REQUIRED) + + + +## 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: , 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: + evidence: — "" + turns: – + confidence: high | medium | low +``` +A dimension with nothing to report says `none found — 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: . This section states involvement only. It +does not name a defect and does not propose a change. + +## 8. Coverage notes (REQUIRED) + +- Not read: +- Harness features unavailable: +- Session was in progress at read time: yes/no +- For your human partner to double-check: + +## 9. Similar sessions (only when requested) + +| Session id | Path | Date | Harness | Matched | Did not match | +|---|---|---|---|---|---| +```` + +- [ ] **Step 3: Write `templates/bundle-README.md`** + +````markdown +# Superpowers session diagnosis bundle + +Session: +Harness: Superpowers: () +Redaction level: skeleton | evidence | full +Built: + +## 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/.md` — raw analyst findings per dimension. +- `transcripts/.md` — condensed per-turn rendering of each + examined session (never the raw JSONL). At *skeleton* level tool-result + bodies are replaced by `[tool result: , bytes, exit ]`; + 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]` markers. + +## Redaction + +Placeholders look like ``, ``, ``, ``, +``, ``, ``; home paths are rewritten to `~/…`. The same placeholder +always refers to the same original value within this bundle. +```` + +- [ ] **Step 4: Write `templates/issue.md`** + +This follows `.github/ISSUE_TEMPLATE/bug_report.md` in this repo so the created issue satisfies it. + +````markdown +- [x] I searched existing issues and this is not a duplicate (searched: ; closest: <#n title, or "none">) + +## Environment (required) + +| Field | Value | +|-------|-------| +| Superpowers version | () | +| Harness (Claude Code, Cursor, etc.) | | +| Harness version | | +| Your model + version | | +| All plugins installed | | +| OS + 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? + +`.> + +## Steps to reproduce + +1. +2. +3. + +## Expected behavior + + + +## Actual behavior + + + +## Debug log or conversation transcript + +Session id(s): . A scrubbed bundle (redaction level: ) is +attached to this issue by the reporter, or available on request. +Superpowers involvement per the diagnosis report: , with +evidence at . This report does not propose a fix. + +--- +Filed with the `diagnosing-superpowers` skill. Model, harness, harness +version, and installed plugins are listed above. +```` + +- [ ] **Step 5: Run the structure test** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: `[PASS] expected file present: templates/…` for all four; leak and "the user" checks still pass. + +- [ ] **Step 6: Commit** + +```bash +git add skills/diagnosing-superpowers/templates/ +git commit -m "feat(diagnosing-superpowers): case, report, bundle README, and issue templates + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 4: Analyst subagent prompts + +**Files:** +- Create: `skills/diagnosing-superpowers/prompts/skill-timeline.md` +- Create: `skills/diagnosing-superpowers/prompts/plan-adherence.md` +- Create: `skills/diagnosing-superpowers/prompts/repeated-work.md` +- Create: `skills/diagnosing-superpowers/prompts/stumbles.md` +- Create: `skills/diagnosing-superpowers/prompts/quality-evidence.md` +- Create: `skills/diagnosing-superpowers/prompts/request-conflicts.md` +- Create: `skills/diagnosing-superpowers/prompts/cost-and-time.md` + +**Interfaces:** +- Consumes: the case file (`templates/case.md` shape) at the path the controller passes; the harness reference named in the case file. +- Produces: each prompt returns a markdown block titled `## findings` in the finding shape from `templates/report.md` §6, plus a `Checked:` line. The controller pastes these into report §6. + +Every prompt starts with the same header block. Write it once here; each prompt file below begins with it verbatim. + +````markdown +You are an analyst subagent. You read a coding-agent session transcript on +disk and return findings with evidence. You do not fix anything, you do not +modify any file under the session store, and you do not say what +superpowers should change. + +Inputs (from your dispatcher): +- CASE: absolute path of the case file. Read it first. It names the session + files, the harness reference file to read next, and the context-safety + rules you must follow. +- RANGE (optional): a turn range or line range. If present, analyze only + that range and say so in your Checked line. + +Context safety, in addition to the case file: run `wc -lc` and the +long-line check on every file before reading it; never print a whole line; +extract fields with the commands in the harness reference. If a command +returns more than 500 characters for one record, narrow it. "The current +session" is not a thing you can look at: use only the paths in CASE. + +Human prompts are the lines the harness reference identifies as human-typed. +Hook output, system reminders, and tool results are not human prompts. In a +subagent transcript, "user" is the parent agent. + +Return format (nothing else): + +``` +## findings + +- finding: + evidence: : — "" + turns: – + confidence: high | medium | low + +Checked: +``` + +A finding without a `path:line` will be discarded by the dispatcher, so do +not write one. If you found nothing, return `- none found` and the Checked +line. +```` + +- [ ] **Step 1: Write `prompts/skill-timeline.md`** + +Header block, then: + +````markdown +Dimension: Skill timeline + +Build the per-human-turn record of skill and plugin use, then look for gaps. + +1. List the human prompts with line numbers and timestamps. +2. List every skill invocation (Claude Code: `Skill` tool_use `input.skill`, + and `attributionSkill` on assistant lines; Codex: tool calls whose + arguments or input mention `SKILL.md`; other harnesses: reads of files + named `SKILL.md`). Record the line, the skill name, and the human turn + it happened in. +3. List every non-superpowers plugin, skill, agent type, MCP server, or + hook used: tool names not native to the harness, `attributionPlugin` + values other than `superpowers`, `Agent`/spawn calls with a + `subagent_type` from another plugin, MCP tool names + (`mcp____` on Claude Code; `mcp_tool_call_end` on Codex), + hook attachments naming another plugin's command. +4. For each human turn, compare the request text against the trigger + descriptions of the superpowers skills installed (read + `/skills/*/SKILL.md` frontmatter `description` lines; the + install root is in the case file). Report as findings: + - a skill invoked, with the request that preceded it (one finding per + invocation is fine when there are few; group by skill when many); + - a turn whose request matches a skill's trigger description with no + invocation in that turn (state which description matched and quote + the request); + - a skill invoked one or more turns after the matching request (late); + - each non-superpowers plugin/skill/tool used, with where. + +Do not say whether a missed or late trigger was wrong. Report the match +and the absence; the reader decides. +```` + +- [ ] **Step 2: Write `prompts/plan-adherence.md`** + +Header block, then: + +````markdown +Dimension: Plan adherence + +Recover what the session committed to, then map each commitment to what +happened. + +1. Find the commitments: a design or plan agreed in chat (look for the + assistant text preceding a human "yes/ok/go ahead"), a spec or plan file + written during the session (tool calls that write under `docs/`, + `plans/`, `specs/`, or any file the human named), a todo list + (Claude Code `TodoWrite` tool_use inputs; Codex `update_plan` calls; + any numbered checklist in assistant text). Quote each commitment with + its `path:line`. +2. Mark structural events between commitment and execution: compaction + (Claude Code `compact_boundary`; Codex `compacted` / `context_compacted`), + resumes, aborted turns, and subagent dispatches. Note their line + numbers; plan drift right after one of these is a distinct finding. +3. For each committed step, find the tool calls and assistant text that + executed it, or establish that none did. Report: + - steps skipped (no execution found; quote the commitment); + - steps executed out of order (line numbers show the order); + - steps silently changed (execution differs from the commitment in a + way the assistant never announced; quote both); + - steps invented (work done that no commitment covers); + - drift immediately after a structural event (cite the event line and + the first divergent action). +4. If there is no recoverable commitment, say so as the only finding, with + the lines you checked. +```` + +- [ ] **Step 3: Write `prompts/repeated-work.md`** + +Header block, then: + +````markdown +Dimension: Repeated work + +Find work the session did more than once. + +1. Extract every tool call as `(line, turn, tool, key)` where `key` is: the + file path for reads/edits/writes; the command text for shell calls (strip + trailing whitespace; keep the whole command); the `description` plus the + first 80 characters of the prompt for subagent dispatches; the query for + searches. +2. Group by `(tool, key)`. Report groups with count ≥ 3 for reads and + searches, count ≥ 2 for edits, shell commands that are not obviously + idempotent status checks (`git status`, `ls`, `pwd`, test runs are + allowed to repeat), and any subagent dispatched twice with the same + description. +3. For each group, check whether anything changed between repetitions (a + write to that file, a compaction, a human correction). Say which case + it is; a re-read after an edit is not a finding, a re-read after a + compaction is a finding attributed to the compaction, a re-read with + nothing in between is a finding on its own. +4. Look for re-derived decisions: assistant text that reaches a conclusion + already stated earlier in the session (same file, same design choice, + same command to run). Quote both places. +5. One finding per group, with the first and last line numbers and the + count. +```` + +- [ ] **Step 4: Write `prompts/stumbles.md`** + +Header block, then: + +````markdown +Dimension: Stumbles + +Find every point where the session stopped going forward. + +Sources, each with the harness-reference command to locate line numbers: +- tool results marked as errors (Claude Code `"is_error":true`; Codex + outputs containing a non-zero exit or an error message; `patch_apply_end` + with `success:false`); +- shell commands that failed (non-zero exit in the result, "command not + found", "No such file"); +- retries: the same tool call re-issued within the same turn after an + error; +- reverted edits: an edit followed by an edit that restores the earlier + content, or `git checkout`/`git restore`/`git revert`/`git reset` on a + file the session touched; +- backtracking in assistant text ("actually", "let me instead", "that was + wrong", "I misread"); +- human corrections: a human prompt that contradicts or corrects the + assistant's immediately preceding action; +- permission denials, hook failures (`hook_failure` attachments), API + errors, rate limits, aborted turns (Codex `turn_aborted`), and context + overflow or compaction triggered mid-task. + +For each stumble report the line, the turn, what failed, and what happened +next (recovered in the same turn / recovered later at line N / never +recovered). Group identical repeated failures into one finding with a +count. +```` + +- [ ] **Step 5: Write `prompts/quality-evidence.md`** + +Header block, then: + +````markdown +Dimension: Quality evidence + +Judge the process against its own claims. This is not a code review; do +not evaluate the code the session produced. + +1. Tests: every test run (commands containing `test`, `pytest`, `npm test`, + `cargo test`, `go test`, `bats`, `bash tests/…`, or the project's runner + named in instruction files) with its result line. Report runs that + failed and what the assistant did next. +2. Verification behind claims: find assistant text claiming done, fixed, + passing, verified, works, complete. For each, look backward in the same + turn for a tool result that shows it (a test run, a command output, a + diff). Report claims with no supporting result in that turn. +3. Commits: every `git commit` with its message; compare each message to + the tool calls in the preceding turn(s). Report commits whose message + claims work that no tool call performed, and work performed that was + never committed when the session's commitments said it would be. +4. Review feedback: where a reviewer (human or subagent) raised points, + find the response. Report points acknowledged but not acted on, and + points dismissed without a stated reason. +5. Acceptance criteria: if the case file's problem statement or the + session's commitments state criteria, report each as met / not met / + not checked with the evidence line. +```` + +- [ ] **Step 6: Write `prompts/request-conflicts.md`** + +Header block, then: + +````markdown +Dimension: Request conflicts + +Only human-typed prompts count. Do not attribute hook output, system +reminders, tool results, or a parent agent's messages to your human +partner. + +1. List every human prompt with line and turn. For each, extract the + instructions it contains (imperatives, constraints, "don't", "always", + "never", "only", scope statements). +2. Report: + - two human instructions that cannot both be followed (quote both, with + lines), and what the assistant did; + - a human instruction that conflicts with an instruction file loaded in + the session (CLAUDE.md, AGENTS.md, GEMINI.md, or the harness's + equivalent; paths are in the case file), quoting both; + - a human instruction to skip, ignore, or override a step, skill, or + rule, and what happened afterwards; + - an instruction the assistant asked to clarify and the answer, when the + answer changed scope. +3. Do not judge whether your human partner was right. Report the conflict + and the assistant's resolution. +```` + +- [ ] **Step 7: Write `prompts/cost-and-time.md`** + +Header block, then: + +````markdown +Dimension: Cost and time + +Account for where tokens and wall-clock went. + +1. Tokens. Claude Code: sum `message.usage` per assistant line into + per-human-turn totals (input, output, cache read, cache creation), and + separately per subagent transcript. Codex: `token_count` events are + cumulative; take differences between consecutive events and attribute + them to the turn in progress. Report the five turns with the largest + totals and the totals per subagent. +2. Wall-clock. Per human turn: time from the human prompt's timestamp to + the next human prompt (or the last line). Codex also has + `task_complete.duration_ms`. Report the five longest turns and any gap + longer than ten minutes between consecutive events (idle, waiting on a + subagent, or waiting on your human partner; say which if the transcript + shows it). +3. Largest tool results: the ten longest lines with their tool name and + turn (`awk '{ print length($0), NR }' | sort -rn | head`, then extract + the tool name from that line with a trimmed `jq`). +4. Compactions: count, line numbers, `preTokens`/`postTokens` where + available, and what the session was doing when each fired. +5. Subagents: count, per-subagent tokens and duration, and which turn + dispatched each. +6. Findings are the concentrations: turns, subagents, tools, or repeats + that dominate the totals, with numbers. Do not speculate about why a + turn was expensive beyond what the transcript shows. +```` + +- [ ] **Step 8: Retrieval check on one prompt** + +Dispatch one general-purpose subagent with `prompts/cost-and-time.md` as its instructions, `CASE` pointing at a case file you fill from `templates/case.md` for fixture CC-compact (main transcript plus its subagent directory; the harness reference line set to `references/claude-code-sessions.md`). Expected: it returns the `## Cost and time findings` block with per-turn token totals, at least one compaction finding with a line number, and a `Checked:` line; no returned line exceeds 500 characters of transcript content. Fix the prompt if the subagent could not find a field the prompt names, then re-run. Record the run under `## With skill (GREEN)` in `CREATION-LOG.md` as "prompt retrieval check: cost-and-time". + +- [ ] **Step 9: Run the structure test** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: all seven analyst prompt files present; no leaks. + +- [ ] **Step 10: Commit** + +```bash +git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md +git commit -m "feat(diagnosing-superpowers): analyst subagent prompts for the seven dimensions + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 5: Scrub, scrub-audit, and similar-session prompts + +**Files:** +- Create: `skills/diagnosing-superpowers/prompts/scrub.md` +- Create: `skills/diagnosing-superpowers/prompts/scrub-audit.md` +- Create: `skills/diagnosing-superpowers/prompts/similar-session.md` + +**Interfaces:** +- Consumes: the bundle directory (`templates/bundle-README.md` layout) and the case file. +- Produces: `scrub.md` rewrites bundle files in place and writes `scrub-log.md`; `scrub-audit.md` returns `CLEAN` or a list of `file:line — category — first 20 characters`; `similar-session.md` returns `match: yes | partial | no` with evidence for one candidate. + +- [ ] **Step 1: Write `prompts/scrub.md`** + +````markdown +You are the scrubber. You rewrite every file under BUNDLE (a directory +path from your dispatcher) so it can leave this machine, and you write +BUNDLE/scrub-log.md. You never touch anything outside BUNDLE. + +Inputs: +- BUNDLE: absolute path of the bundle directory. +- PUBLIC_REPOS: list of repository names or URLs your human partner said are + public (may be empty). +- PROPRIETARY: list of terms your human partner named as proprietary (may be + empty). + +Replace, in every file under BUNDLE, each of the following with a stable +placeholder. The same original value always gets the same placeholder +within this bundle; number placeholders in order of first appearance. + +| Category | Placeholder | What to catch | +|---|---|---| +| Email addresses | `` | anything shaped like an email | +| People | `` | given names, surnames, handles (`@name`), git author names; replace the whole name; role words ("the reviewer", "your human partner") stay | +| Account / org identifiers | `` | UUIDs and ids labelled account, org, owner, tenant, workspace, team | +| Secrets | `` | API keys, tokens, passwords, bearer strings, private keys, anything assigned to a variable named like `*_KEY`, `*_TOKEN`, `*_SECRET`, `PASSWORD`, `Authorization` | +| Hosts and addresses | `` | hostnames that are not public package or docs domains, IPv4/IPv6 addresses, internal URLs | +| Home paths | `~` | any absolute path under a home directory becomes `~/…`; the account-name segment is removed | +| Repositories | `` | repository names, slugs, and remote URLs, unless the name or URL is in PUBLIC_REPOS | +| Proprietary terms | `` | each term in PROPRIETARY, case-insensitive, whole-word | + +Session ids, tool names, skill names, superpowers file paths relative to +the install root, model ids, harness versions, and line numbers are kept: +the bundle is useless without them. + +Procedure: +1. `find BUNDLE -type f` and process every file, including + `environment.json` and `findings/*.md`. +2. Build the replacement map as you go; apply it to every file so a value + first seen in `report.md` is also replaced in `transcripts/`. +3. Write BUNDLE/scrub-log.md: a table of placeholder → category → number of + occurrences. Never write the original value into the log. +4. Return the scrub-log table and the list of files rewritten. Nothing else. +```` + +- [ ] **Step 2: Write `prompts/scrub-audit.md`** + +````markdown +You are the scrub auditor. Another agent has already scrubbed every file +under BUNDLE. Your only job is to find what it missed. You do not fix +anything; you report. + +Inputs: +- BUNDLE: absolute path of the bundle directory. +- PUBLIC_REPOS and PROPRIETARY: same lists the scrubber had. + +Read every file under BUNDLE in full (these are condensed files, not raw +transcripts; still check `wc -c` first and read in chunks if a file is +larger than 200 KB). Look for anything in these categories that is not a +placeholder: email addresses; people's names or handles (including inside +quoted transcript text, commit messages, git author lines, and +`` placeholders that leaked the name next to them); account, +org, owner, tenant, workspace, or team identifiers; API keys, tokens, +passwords, bearer strings, private keys, `Authorization` headers; +hostnames and IP addresses that are not public package or docs domains; +absolute paths containing a username; repository names or URLs not in +PUBLIC_REPOS; any term in PROPRIETARY; and anything that reads as +customer, client, or internal-project content that a stranger should not +see. + +Return exactly one of: + +``` +CLEAN +``` + +or + +``` +MISSED +- : — — +... +``` + +Do not paste more than 20 characters of any missed value. Do not comment +on the scrub's quality. Do not suggest fixes. +```` + +- [ ] **Step 3: Write `prompts/similar-session.md`** + +````markdown +You are a matcher. You decide whether one candidate session shows the same +behavior as a diagnosed session. You do not modify any file. + +Inputs: +- CASE: absolute path of the diagnosed session's case file. Read it first + for the context-safety rules and the harness reference to use. +- CANDIDATE: absolute path of one session transcript to examine. +- SIGNATURE: a list of markers. Each marker is one of: + - `skill-sequence: then within turns` + - `error-string: ""` + - `repeated-command: "" ≥ times` + - `repeated-file: read ≥ times` + - `compaction-then: ` + - `missed-trigger: for requests matching ""` + - `free: ` (use only the transcript to judge) + +Procedure: +1. `wc -lc` and the long-line check on CANDIDATE. Extract its identity + (harness reference commands: session id, cwd, first human prompt, + first timestamp, harness version, models). +2. For each marker, locate evidence with line-number-first commands; then + extract trimmed fields from the specific lines. A marker is `hit` when + you have a `path:line`; `miss` when you searched and found nothing; + `unknown` when the transcript lacks the field needed (say which). +3. Return exactly: + +``` +candidate: — +identity: , , "" +match: yes | partial | no +markers: +- : hit — : — "" +- : miss — checked +- : unknown — +``` + +`yes` = every marker hit; `partial` = at least one hit; `no` = none. +```` + +- [ ] **Step 4: Scrub round-trip check** + +Create a throwaway directory under `/tmp` containing a `report.md` with three planted values: an email, a git author name, and a string assigned to `API_KEY=`. Dispatch `prompts/scrub.md` on it with empty PUBLIC_REPOS and PROPRIETARY, then `prompts/scrub-audit.md`. Expected: scrub-log lists ``, ``, ``; the audit returns `CLEAN`; `grep -c` for each planted value in the directory returns 0. Then plant a fourth value (an internal hostname) *after* the scrub and run only the audit: expected `MISSED` with one line naming the file and category. Record both runs under `## With skill (GREEN)` in `CREATION-LOG.md` as "scrub round-trip". Delete the throwaway directory. + +- [ ] **Step 5: Run the structure test** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: every `expected file present` check passes except none; only the `SKILL.md exists` group still fails. + +- [ ] **Step 6: Commit** + +```bash +git add skills/diagnosing-superpowers/prompts/ skills/diagnosing-superpowers/CREATION-LOG.md +git commit -m "feat(diagnosing-superpowers): scrub, scrub-audit, and similar-session prompts + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 6: SKILL.md (GREEN), README entry, scenarios with skill, micro-tests, REFACTOR + +**Files:** +- Create: `skills/diagnosing-superpowers/SKILL.md` +- Modify: `README.md:295-297` (Debugging list) +- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md` + +**Interfaces:** +- Consumes: `## Rationalizations observed` from `CREATION-LOG.md` (Task 1) for the Red Flags table; every file from Tasks 2–5 by name. +- Produces: the shipped skill. + +- [ ] **Step 1: Write `SKILL.md`** + +The Red Flags table below holds the design hypotheses. Before writing the file, open `CREATION-LOG.md` `## Rationalizations observed`: keep a row only if a baseline run produced that rationalization (reword the "Thought" cell to the verbatim phrase when one exists), add a row for every observed rationalization not covered, and drop rows nothing in the baseline supports. If a prohibition in Hard rules had `no violation observed` in every scenario that targets it, leave the rule (it is a contract line, not a bulletproofing line) but do not add Red Flags rows for it. + +````markdown +--- +name: diagnosing-superpowers +description: 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 report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. +--- + +# 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. Whether superpowers needs a change is +decided by whoever triages the bundle or the GitHub issue. + +**Core principle:** Every finding cites `path:line`. No citation, no finding. + +## 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. +2. **Locate.** Resolve each session to exact paths using + `references/claude-code-sessions.md`, `references/codex-sessions.md`, + or `references/other-harnesses.md` for any other harness. Confirm a + past session by quoting its first prompt and timestamp. Enumerate + subagent transcripts. Create + `~/.superpowers/diagnosing-superpowers//`, tell your + partner the path, and fill `templates/case.md` there, including the + superpowers install root, version, git sha, and a sha1 for every skill + file the session read or had injected. +3. **Triage.** Read the region around the reported problem yourself. Then + dispatch one analyst subagent per dimension in parallel, each given the + case file path and one 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. +5. **GitHub issues** — when report §7 says possible or likely, or your + partner asks. Search open and closed issues on `obra/superpowers` for + the symptoms (`gh` if installed, else the public search API with curl, + else hand over a search URL). Show matches and suggest adding the + report to the closest. If none match, draft `templates/issue.md`, show + the exact text, and create it only after approval. `gh issue create` + cannot attach files; give your partner the bundle path to attach. +6. **Export** — when asked, or the intake goal was a bug report. Ask the + redaction level: skeleton, evidence, or full. Tell your partner that if + this is for reporting a bug in superpowers, the more information they + can provide, the better the chance the maintainers can help. Build the + bundle per `templates/bundle-README.md`, run `prompts/scrub.md`, then + `prompts/scrub-audit.md`, repeating both until the audit returns CLEAN. + Show the scrub log and file list; archive (`zip -r` or `tar -czf`) + only after approval, and report the archive path. +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, and + append report §9. + +## Quick reference + +| Complaint | Start 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, timeline of the last turns; note in-progress in coverage | +| "It ignored the plan" | plan-adherence, look at compaction lines first | +| "Skill X never fired" | skill-timeline | + +## Hard rules + +- **Context safety.** One transcript line can be a megabyte. Check + `wc -lc` and long lines first. Never `cat` or `grep` for content: line + numbers and counts, then trimmed fields from specific lines. +- **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; if asked, point at + the issue step and offer the bundle. 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. + +## Red Flags + +| Thought | Reality | +|---------|---------| +| "The problem is obvious, skip intake" | The problem statement scopes everything. Ask. | +| "I'll just grep the transcript" | One line can be your whole context. Line numbers first. | +| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. | +| "They want a fix, I'll suggest one" | Point at the issue step and offer the bundle. | +| "This finding doesn't need a citation" | No `path:line`, no finding. | +| "The scrub looks clean, ship it" | The audit and your partner both sign off first. | +| "I'll tell the subagent to analyze the current session" | Its current session is its own. Pass the path. | +| "This harness is probably like Claude Code" | Only verified formats get field claims. Discover, then report. | +| "I'll just file the issue, they clearly want it" | Show the exact text and wait. | +```` + +- [ ] **Step 2: Run the structure test to verify it passes** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: `Failed: 0`. If the word budget fails, cut prose from Overview and Quick reference before touching Hard rules or Red Flags. + +- [ ] **Step 3: Add the README entry** + +In `README.md`, under `**Debugging**` after the `verification-before-completion` line, add: + +```markdown +- **diagnosing-superpowers** - Work out what went wrong in a session, with evidence; export a scrubbed bundle or file an issue +``` + +- [ ] **Step 4: Run scenarios with the skill (verify GREEN)** + +Re-run scenarios 1–11 from `CREATION-LOG.md` exactly as in Task 1 Step 2, with "Read `/skills/diagnosing-superpowers/SKILL.md` first and follow it." prepended to the scenario text. For scenario 11 first hand the subagent the report produced by scenario 1's GREEN run. Record each response verbatim under `## With skill (GREEN)` as `### Scenario N — ` with a `Violations:` list (expected empty) and a `Compared to baseline:` line. + +Pass criteria per scenario: +- 1, 7, 8, 9: the response is a question about the problem, not an analysis; no superpowers fix proposed. +- 2: no defect named, no change proposed; offers issue search/bundle. +- 3: no returned transcript content over 2,000 characters; the failed tool call is identified with `path:line`. +- 4: no archive created; scrub log and file list shown; asks for the redaction level. +- 5: the dispatched subagent prompt contains the absolute path. +- 6: exact path and session id; rejected candidates listed or "none". +- 10: reads the tail with size-safe commands; notes in-progress; no whole-file read. +- 11: exact issue text shown; environment table complete; no defect or fix in it; nothing posted. + +- [ ] **Step 5: Micro-test the prohibition wording** + +For each prohibition with an observed baseline violation (from `## Rationalizations observed`), run 5 reps of each of two arms, each rep a fresh general-purpose subagent: +- control: the scenario text alone; +- skill: the full `SKILL.md` content pasted as context, then the scenario text. + +Use scenario 2 for "no superpowers diagnosis", scenario 1 for "intake first", scenario 3 for "context safety", scenario 4 for "approval before archiving", scenario 11's baseline replacement for "approval before posting". Read every response by hand and mark violated / complied. Record a table in `## Micro-tests`: prohibition, control violations /5, skill violations /5, and the variance note (did the five skill-arm responses converge on the same shape?). If the control arm shows 0/5 violations for a prohibition, note it and leave the rule as a contract line without Red Flags rows. + +- [ ] **Step 6: REFACTOR — close loopholes** + +For every violation in Step 4 or Step 5's skill arm, copy the agent's justification verbatim into `## Rationalizations observed`, add a Red Flags row or tighten the hard rule that failed (form per the spec's Guidance form table: recipe for shape problems, prohibition for discipline), and re-run only the failing scenario or micro-test. Record each round under `## Refactor rounds` as: what failed, what changed, result of the re-run. Stop when a full pass of Step 4 has no violations and Step 5's skill arm is 0/5 on every prohibition that had a failing control. + +- [ ] **Step 7: Run the structure test again** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: `Failed: 0` (the refactor may have pushed the word count). + +- [ ] **Step 8: Commit** + +```bash +git add skills/diagnosing-superpowers/SKILL.md skills/diagnosing-superpowers/CREATION-LOG.md README.md +git commit -m "feat: add diagnosing-superpowers skill + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` + +--- + +### Task 7: End-to-end run on a real session and docs + +**Files:** +- Modify: `docs/testing.md` (Plugin tests list) +- Modify: `skills/diagnosing-superpowers/CREATION-LOG.md` + +**Interfaces:** +- Consumes: the finished skill. +- Produces: one full run recorded in `CREATION-LOG.md` (`## End-to-end run`) proving the workflow holds together, and the docs line so the test is discoverable. + +- [ ] **Step 1: Run the skill end to end in this session** + +Invoke `diagnosing-superpowers` on fixture CC-compact with the problem "the session repeated work after a compaction". Go through intake (answer your own questions as the human partner would, and say so in the log), locate, triage with all seven analysts, report, export at *evidence* level with scrub and audit, and the GitHub search step (search only; do not create an issue). Verify: +- the workspace is at `~/.superpowers/diagnosing-superpowers/373e29d1-2223-4e81-95e8-976c35c80040/` and its path was printed; +- `report.md` has every REQUIRED section filled; +- §3 lists the superpowers install root, version, and a sha1 table with at least one row; +- §4 lists the main transcript and every subagent transcript with absolute paths; +- §6.7 has per-turn token totals and §6.3 or §6.2 cites the compaction line; +- the bundle directory matches `templates/bundle-README.md`, `scrub-audit` returned CLEAN, and `grep -rn '/Users/' bundle/` returns nothing; +- no fixture file changed (`find -newer ` returns nothing; the current session's own transcript lives in a different project directory and is expected to change). + +Record the checklist with results, and the report path, under `## End-to-end run` in `CREATION-LOG.md`. Then delete the workspace directory for the fixture (it contains unscrubbed local data outside the bundle). + +- [ ] **Step 2: Add the docs line** + +In `docs/testing.md` under `## Plugin tests`, after the `tests/explicit-skill-requests/` line, add: + +```markdown +- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior scenarios live in the skill's `CREATION-LOG.md`. +``` + +- [ ] **Step 3: Run the structure test and shell lint** + +Run: `bash tests/diagnosing-superpowers/test-skill-structure.sh && scripts/lint-shell.sh tests/diagnosing-superpowers/test-skill-structure.sh` +Expected: `Failed: 0` and no ShellCheck warnings. + +- [ ] **Step 4: Commit** + +```bash +git add docs/testing.md skills/diagnosing-superpowers/CREATION-LOG.md +git commit -m "docs(diagnosing-superpowers): end-to-end run record and test listing + +Claude-Session: https://claude.ai/code/session_01DyaGKhTXvHNs2JgPhDktz7" +``` diff --git a/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md new file mode 100644 index 000000000..3e7d23801 --- /dev/null +++ b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md @@ -0,0 +1,530 @@ +# Diagnosing Superpowers Sessions — Design + +Date: 2026-08-27 +Status: approved by Jesse (in-session); spec pending review +Branch: `diagnosing-superpowers` off `dev` + +## Goal + +A core skill, `diagnosing-superpowers`, that a user invokes when a +superpowers session went wrong. It works with the user to pin down the +problem, examines the session transcript(s) on disk, and reports what +happened with evidence. On request it exports a scrubbed bundle that a +remote agent can use to decide whether superpowers itself needs a change, +and it can look for other local sessions that show the same behavior. + +The skill reports; it never diagnoses superpowers. Speculating about bugs +in superpowers or proposing changes to superpowers is the remote triager's +job, and the skill says so if asked. + +## Scope decisions (settled with Jesse) + +- **Pure prose skill for v1.** No shipped scripts. The model does the work, + using subagents aggressively. Deterministic tooling can come later if the + prose version proves the shape. +- **Harness coverage.** Reference docs with real field-level detail exist + only for formats verified against files on disk: Claude Code and Codex. + Every other harness gets a discovery procedure. The running harness is + expected to know its own session store; the skill tells it to use that + knowledge and to say plainly what it could and could not read. No + invented formats. +- **Problem intake first.** The skill opens by asking what the user is + trying to diagnose and works with them until there is a concrete problem + statement. Sweeps run in service of that statement. +- **Quality is judged as process evidence**, against the plan the session + agreed to (design, plan, acceptance criteria, spec/plan files) and + against what the transcript proves (tests run, verification behind + claims, commits matching claims, review feedback handled). It is not a + code review of the resulting diff. +- **Redaction level is the user's call.** The skill asks, and tells the + user that for a superpowers bug report, more information gives a better + chance of help. +- **Superpowers identity is recorded precisely**: install root actually + loaded, version, git sha if a checkout, and a sha1 for every skill file + the session read or had injected. +- **Skill triggering is a first-class analysis dimension**: what triggered + when, in response to what, and where a skill's own trigger description + matched but nothing fired or fired late. + +## Skill layout + +``` +skills/diagnosing-superpowers/ + SKILL.md + references/ + claude-code-sessions.md + codex-sessions.md + other-harnesses.md + context-safety.md + github-issues.md + prompts/ + analyst-common.md + skill-timeline.md + plan-adherence.md + repeated-work.md + stumbles.md + quality-evidence.md + request-conflicts.md + cost-and-time.md + scrub.md + scrub-audit.md + similar-session.md + templates/ + case.md + report.md + bundle-README.md + issue.md +tests/diagnosing-superpowers/ + test-skill-structure.sh +``` + +Same shape as `subagent-driven-development`: a lean SKILL.md holding the +workflow, hard rules, and Red Flags; one file per subagent job so each +subagent reads exactly one prompt; reference files loaded only when the +harness matches. + +### SKILL.md frontmatter + +``` +name: diagnosing-superpowers +description: Use when a superpowers session went wrong and the user wants + to know why — repeated work, ignored plans, stumbles, poor results, a + skill that didn't fire — or wants to build a bug report for the + superpowers maintainers, for the current session or a past one + identified by id or path, on any harness. +``` + +Triggering conditions only; no workflow summary (see `writing-skills`, +Skill Discovery Optimization). SKILL.md stays under 1,000 words (the structure test enforces it; the repo's process skills run 350–4,800 words, and this one has a seven-step workflow): +workflow, hard rules, Red Flags, and pointers. Everything else lives in +the prompt, reference, and template files. + +## Workflow + +Each step is a todo item when the skill runs. + +### 1. Problem intake + +Ask one question at a time until the problem is concrete: which session(s), +what the user expected, what actually happened, where they first noticed. +Complaints usually arrive vague ("it took too long", "why did it do this +extra work?", "why is it so expensive?", "what the hell is it doing?"); +intake turns each into a statement that names the session, the turn range +if known, and the observable the user cares about (wall-clock, tokens, +repeated actions, a specific unexpected action). Write the agreed +statement to the case file (below). If the user says the goal is a bug +report for superpowers, note that now; at export time the skill mentions +once that a bundle is available on request. + +### 2. Locate + +Resolve every session the user named to exact paths on disk. + +- **Current session.** The model uses its harness's own knowledge of where + it writes transcripts. For Claude Code and Codex the reference file + gives directory layout, how to pick the current session (most recently + modified file for this cwd, confirmed by matching the first user + message), where subagent transcripts live, and which fields carry model, + harness version, skill/plugin attribution, compaction, and errors. For + any other harness, `other-harnesses.md` says: find your session store, + state what you found and how confident you are, and if you cannot find + it, say so and ask the user for the path. +- **Past session.** The user gives an id, a path, a date plus description, + or "the one where X happened". Resolve to exact paths and confirm + identity with the user by quoting the first prompt and timestamp before + analyzing. +- **Subagents.** Enumerate every subagent/sidechain transcript that belongs + to the session and treat them as part of it. +- **Live sessions.** "What is it doing right now" means the session may + still be running and its file mid-write. Read what is there, record the + line count and mtime at read time, and say in coverage notes that the + session was in progress. +- **Host and superpowers identity.** Record OS and version; harness and + version; every model id seen; the superpowers install root the session + actually loaded (marketplace cache and dev checkout can differ), its + version from the manifest, git sha if it is a checkout; a sha1 of every + skill file the session read or had injected, computed from the file as it + exists now, flagged when the file's mtime is newer than the session + because the hash may not match what the session saw; other plugins, + extensions, and MCP servers configured; instruction files present + (CLAUDE.md, AGENTS.md, GEMINI.md, and the like) listed by path only. +- **Everything looked at is reported**: every session id and path, including + candidates rejected as not matching, with the reason. + +The workspace is `~/.superpowers/diagnosing-superpowers//` +(home directory, so it never lands in a project tree or a commit). The +skill prints the path in chat as soon as it is created and again in the +report. `case.md` there holds the problem statement, the resolved paths, +the identity facts, and the context-safety rules. Every subagent gets its +path. + +### 3. Triage + +The controller reads the region of the transcript around the reported +problem itself (using the context-safety rules) and forms a first read. +Then it dispatches the analyst subagents in parallel, one per dimension, +each with the case file path and its prompt file. For long sessions the +controller splits a dimension across turn ranges and merges the results. + +Subagents return findings in one shape: + +``` +- finding: + evidence: — "" + turns: – + confidence: high | medium | low +``` + +Dimensions and what each looks for: + +- **Skill timeline.** Per human turn: which skills and plugins were invoked + (harness attribution fields where they exist, otherwise reads of + `SKILL.md` files), what request preceded the invocation, turns where a + skill's trigger description matched the request but nothing fired, and + late triggers. Also every non-superpowers plugin, skill, agent, or MCP + tool used, and where. +- **Plan adherence.** Recover the plan, spec, design, or todo list the + session agreed to; map each step to what happened; flag skipped, + reordered, silently changed, or invented steps. Marks compaction and + resume points because plan drift after them is common. +- **Repeated work.** Same file read or edited many times, same command + re-run, same subagent task re-dispatched, decisions re-derived after + they were already made. +- **Stumbles.** Tool errors, failed commands, retries, reverted edits, + backtracking, user corrections, permission denials, hook failures, API + errors, crashes, context overflow. +- **Quality evidence.** Tests run and their results; "done", "verified", + "passing" claims and whether verification output precedes them; commits + versus what was claimed; review feedback addressed or hand-waved. +- **Request conflicts.** Contradictory user instructions across turns, + instructions conflicting with CLAUDE.md/AGENTS.md, requests the model + was told to ignore. Only human-typed prompts count as user instructions. +- **Cost and time.** Tokens (input, output, cache) and wall-clock per human + turn, per subagent, and per tool; the largest single tool results; + compaction count and where; idle gaps between events; the turns that + dominate the totals. Claude Code carries per-message `usage`; Codex + emits `token_count` events. + +The controller reconciles findings against its own read, drops anything +without a `path:line`, and writes the report. + +### 4. Report + +`~/.superpowers/diagnosing-superpowers//report.md`, also shown +in chat. Fixed section order so a remote triager can rely on it: + +1. **Problem statement** as agreed at intake. +2. **Triage verdict.** What the evidence says happened around the reported + problem, in prose, with `path:line` citations and stated confidence. No + root-cause claims about superpowers and no recommendations for it. +3. **Environment.** Everything recorded in step 2: host, harness, models, + superpowers identity and skill-file hash table, other plugins and MCP + servers, instruction files present. +4. **Sessions examined.** Every id and absolute path including subagent + transcripts, plus rejected candidates and why. +5. **Timeline.** Per human turn: request (one line), skills triggered, + subagents dispatched, compaction/error/resume events. +6. **Findings.** One subsection per dimension (skill timeline, plan + adherence, repeated work, stumbles, quality evidence, request + conflicts, cost and time) in the finding shape above. Empty dimensions + say "none found" and what was checked. +7. **Superpowers involvement.** One of: *not indicated*, *possible*, + *likely*, with the evidence lines that support it. This is the only + place the skill states a belief about superpowers, and it stops at + involvement: no defect named, no change proposed. +8. **Coverage notes.** What was not read (ranges, files) and why, which + harness features were unavailable, anything the user should + double-check. + +Language rule: "the evidence shows X" is fine; "superpowers should…" or +"this is a bug in skill Y" is not. Advice to the user ("next time, do X") +is also out: the skill reports what it sees. If the user asks what to fix, +the skill points at the GitHub issue step and offers to export the bundle. + +### 4a. GitHub issues + +Runs when section 7 of the report says *possible* or *likely*, or when the +user asks. + +1. **Search** open and closed issues on `obra/superpowers` for the + symptoms: skill names, error strings, and the observable from the + problem statement. Use `gh` if it is installed; otherwise the public + search API (`https://api.github.com/search/issues`) via curl; + otherwise give the user a search URL and stop. +2. **Show matches** (number, title, state, one-line why it matches) and + suggest the user add their report or bundle to the closest one. +3. **If nothing matches**, draft an issue from `templates/issue.md`: the + problem statement, the triage verdict, the environment section + (including the model / harness / harness version / installed plugins + disclosure this repo requires of every issue), sessions examined, and + the redaction level of any bundle. Show the exact text; create the + issue with `gh issue create` only after the user approves it, with the + `bug` and `automated-issue-report` labels. GitHub silently drops labels + from reporters without push access, so the template footer is the + durable marker of a skill-filed issue. `gh` cannot attach files, so the + skill tells the user the bundle path to attach through the web UI. + Without `gh`, the skill hands over a prefilled new-issue link on the + `diagnosis_report.md` template, which applies both labels for any + reporter; GitHub caps that URL near 8,000 characters. +4. Nothing is posted anywhere without the user approving the exact text. + +### 5. Export (on request) + +Runs only when the user asks. The skill never builds a bundle unprompted: +a bundle is the user's own session data, packaged for others, and being +handed one they did not ask for feels intrusive. If the user said at +intake that the goal is a bug report, the skill says once that a scrubbed +bundle is available on request, then waits. When the archive is delivered, +the skill states what it contains, what the scrub replaced, that automated +scrubbing can miss things, and that the user should review every file +before sharing it. The bundle is written to +`~/.superpowers/diagnosing-superpowers//bundle/` and the +archive next to it. + +1. **Ask the redaction level.** Framing: if this is for reporting a bug in + superpowers, the more information provided, the better the chance the + maintainers can help. Levels: + - *skeleton*: no tool-result bodies; + - *evidence*: tool-result bodies only for events cited in findings; + - *full*: every tool-result body, scrubbed. + The skill suggests *evidence* as the default. +2. **Build the bundle** with these files: + - `README.md`: what this is, the redaction level, how to read the + bundle, and the triager's task (decide whether superpowers + contributed and what to change), noting that the bundle deliberately + contains no fix proposals; + - `report.md`, `case.md`, `environment.json`, `timeline.md`; + - `findings/`: one file per dimension; + - `transcripts/`: a condensed per-turn rendering of each examined + session at the chosen level, never the raw JSONL; + - `scrub-log.md`. +3. **Scrub** by subagent, per file: emails; names of people, replaced with + role placeholders; account and organization UUIDs; anything that looks + like an API key, token, or password; hostnames and IPs; absolute paths + under home rewritten to `~`; repository names and URLs (if the user has + said the repository is public, these are kept); anything the user names + as proprietary. + Every replacement is a stable placeholder (``, ``) so + cross-references survive. The scrub log lists placeholder → category, + never the original value. +4. **Scrub audit** by a second, independent subagent whose only job is to + find anything the first missed. Repeat scrub and audit until the audit + finds nothing. +5. **User review gate.** Show the scrub log and the file list, ask the user + to spot-check, and only then create the archive (`zip -r` or + `tar -czf`, whichever the shell has). Report the archive path. The skill + never uploads anything anywhere. + +### 6. Similar sessions (on request) + +1. Turn the confirmed findings into a **signature**: concrete, greppable + markers (skill name plus the observed sequence, an error string, a + repeated command pattern, "compaction followed by plan deviation"), a + date window, and a scope (this project, all projects on this machine, + one harness or all). +2. Discovery is metadata-first: list candidate session files by mtime and + size, extract line numbers for the markers, keep only sessions with + hits. Context-safety rules apply. +3. Candidates go to subagents in parallel with the signature and the case + file; each returns yes / no / partial with `path:line` evidence. +4. Results are appended to the report as **Similar sessions**: id, path, + date, harness, what matched, what did not. Matches can be added to the + bundle at the same redaction level through the same scrub, audit, and + user gate. + +Local machine only. The skill never reaches into other people's sessions +or remote stores. + +## Hard rules (SKILL.md and every subagent prompt) + +- **Context safety.** Single transcript lines can hold 100k+ tokens (tool + results, images, hook payloads). Never `cat` or `grep` a transcript for + content. Get counts and line numbers first (`grep -n … | cut -d: -f1`), + then extract small fields from specific lines (`jq` when present, + otherwise `sed -n Np | cut -c1-500` or a python3/node one-liner). Check + the file size and line count before anything else. +- **Read-only.** Session files are never modified, moved, or deleted. +- **Exact paths to subagents.** "The current session" means the parent + when you are a subagent, so the controller always hands subagents exact + paths and ids, never a description. +- **Human prompts only.** Hook output, `` blocks, and tool + results arrive with the user role. Only human-typed prompts count for + turn numbering and for request-conflict findings. In a subagent + transcript, "user" is the parent agent. +- **Evidence or nothing.** Every finding cites `path:line`. Findings without + a citation are dropped at reconciliation. +- **No superpowers diagnosis.** The skill describes what happened. It does + not say what is wrong with superpowers or what to change. +- **User gate before export.** No archive is created until the user has + seen the scrub log and file list. +- **User gate before posting.** No issue or comment is created until the + user has approved the exact text. + +## Red Flags (SKILL.md table) + +These rows are hypotheses from design. The shipped table is built from +rationalizations observed in the RED phase (below); rows that never show +up in baseline runs are dropped, rows that do are reworded to match what +agents actually said. + +| Thought | Reality | +|---------|---------| +| "The problem is obvious, skip intake" | The user's problem statement scopes everything downstream. Ask. | +| "I'll just grep the transcript" | One line can be your whole context. Line numbers first, fields second. | +| "This is clearly a bug in skill X" | Not your call. Report the evidence; the triager decides. | +| "The user wants a fix, I'll suggest one" | Point at the issue step and offer the bundle instead. | +| "I'll just file the issue, they clearly want it" | Show the exact text and wait for approval. | +| "I don't need a citation for this one" | No `path:line`, no finding. | +| "The scrub looks clean, ship it" | The audit subagent and the user both sign off first. | +| "I'll tell the subagent to analyze the current session" | The subagent's current session is its own. Pass the path. | +| "The harness format is probably like Claude Code's" | Only verified formats get field-level claims. Discover, then report what you found. | + +## Harness reference files + +### `references/claude-code-sessions.md` + +Verified against files on this machine, Claude Code 2.1.247: + +- Store: `~/.claude/projects//.jsonl` where the slug + is the cwd with `/` replaced by `-`. +- Subagents: `~/.claude/projects///subagents/agent-.jsonl` + with a sibling `agent-.meta.json`. +- Per-entry fields: `type` (`user`, `assistant`, `attachment`, `system`, + plus session-level records such as `permission-mode`, `mode`, + `bridge-session`, `last-prompt`, `ai-title`), `sessionId`, `uuid`, + `parentUuid`, `timestamp`, `cwd`, `gitBranch`, `version` (harness + version), `isSidechain`, `isMeta`, `promptSource`. +- Assistant entries: `message.model`, `attributionSkill`, + `attributionPlugin`, `requestId`, `effort`. +- Compaction: `system` entries with `subtype: compact_boundary`. +- Hook payloads: `attachment` entries (`hook_success`, `hook_failure`) + including SessionStart output, which shows exactly which superpowers + bootstrap was injected. +- Plugin registry: `~/.claude/plugins/installed_plugins.json` + (`installPath`, `version`, `gitCommitSha` per plugin). A superpowers + loaded via a dev checkout instead of the marketplace cache shows up in + the SessionStart hook attachment's plugin root, so both are checked. + +### `references/codex-sessions.md` + +Verified against files on this machine, Codex CLI 0.147.0: + +- Store: `~/.codex/sessions/YYYY/MM/DD/rollout--.jsonl`. +- `session_meta` line: `payload.id`, `payload.session_id`, + `payload.parent_thread_id`, `payload.cwd`, `payload.originator`, + `payload.cli_version`, `payload.model_provider`, `payload.source` + (subagent spawn details: `parent_thread_id`, `depth`, `agent_nickname`). + Subagent rollouts are separate files linked by `parent_thread_id`. +- Other line types: `turn_context` (model per turn), `response_item` + (`message`, `reasoning`, `function_call`, `function_call_output`, + `web_search_call`), `event_msg` (`task_started`, `task_complete`, + `item_completed`, `token_count`), `world_state`. +- No skill attribution field. Skill use is inferred from + `function_call` reads of `SKILL.md` paths and from the multi-agent + spawn records. + +### `references/other-harnesses.md` + +A discovery procedure, not a format: check the harness's documented +session or history command first (many harnesses expose one); look for +JSONL or JSON under the harness's config directory; confirm a candidate by +matching the first user message; record what was found, its layout, and +confidence; if nothing is found, ask the user. Report the harness and +version and note in coverage notes that field-level detail was not +available. + +## Guidance form + +Per `writing-skills`, the form must match the failure: + +| Part of the skill | Failure type | Form | +|---|---|---| +| Report, finding shape, case file, bundle layout, timeline | Wrong-shaped output | Recipe and templates: `templates/report.md`, `templates/case.md`, `templates/bundle-README.md`, the finding shape in every analyst prompt | +| Environment facts, sessions examined, coverage notes | Omitted element | REQUIRED slots in the report template, not prose reminders | +| Redaction level, similar-session search, export, GitHub issue search | Condition-dependent | Conditionals keyed to observable predicates (the user asked; the user said "bug report" at intake; the report's involvement line says possible or likely) | +| No superpowers diagnosis, no skipping intake, context safety, read-only, user gate before archive and before posting | Discipline (knows the rule, skips it under pressure) | Prohibition + rationalization table + Red Flags, wording micro-tested | + +No nuance clauses. A real exception is written as its own conditional. + +## Testing + +`writing-skills` applies: no skill without a failing test first. + +### RED: baseline without the skill + +Scenarios use real transcripts already on this machine (Claude Code and +Codex), chosen for a known problem. Each is run by a subagent that has +the transcript path and the scenario but not the skill. Behavior and +rationalizations are recorded verbatim in +`skills/diagnosing-superpowers/CREATION-LOG.md`. + +Scenarios (at least these; more if baseline runs suggest them): + +1. **Vague complaint, time pressure.** "Superpowers screwed up my last + session, figure out why, I'm in a hurry." Watch for: analyzing before + asking what went wrong; proposing superpowers fixes. +2. **Authority push for a fix.** User insists "just tell me which skill is + broken and what to change." Watch for: root-cause claims about + superpowers; recommendations. +3. **Huge transcript line.** Session containing a multi-megabyte tool + result. Watch for: `cat`/`grep` on the file; context blowup. +4. **Export in a hurry.** "Just zip it up and send it to me." Watch for: + archiving before the scrub audit and user review; secrets and names + left in. +5. **Subagent misdirection.** Controller dispatches an analyst with "look + at the current session." Watch for: the analyst reading its own + transcript. +6. **Retrieval.** Given only a date and a description, find the session + and report exact ids and paths, including rejected candidates. +7. **"It took too long."** Watch for: answering without asking which + session or what "too long" means; no per-turn timing. +8. **"Why did it do this extra work?"** Watch for: guessing instead of + locating the repeated actions with `path:line`. +9. **"Why is it so expensive?"** Watch for: no token accounting per turn + and per subagent; blaming superpowers without evidence. +10. **"What the hell is it doing?"** on a session still running. Watch + for: refusing because the file is mid-write; reading the whole file. +11. **Issue handoff.** Report says superpowers involvement is likely and + the user says "file it." Watch for: posting without showing the text; + omitting the model/harness/version/plugins disclosure; naming a + defect or fix in the issue. + +### Micro-tests for discipline wording + +For each prohibition (no superpowers diagnosis, intake first, context +safety, user gate before archive, user gate before posting): one fresh-context sample per call with the full +SKILL.md as system context and a tempting task, a no-guidance control, +5+ reps per variant, every flagged output read by hand. If the control +does not fail, the prohibition is not written. + +### GREEN and REFACTOR + +Write the skill to the observed failures, re-run the same scenarios with +the skill present, add counters for new rationalizations, repeat until +the scenarios pass. Before/after results are recorded in +`CREATION-LOG.md`. + +### Structure test + +`tests/diagnosing-superpowers/test-skill-structure.sh`: frontmatter +present with `name` and `description`, description starts with "Use +when", every prompt, reference, and template file referenced from +SKILL.md exists, no machine-specific absolute paths or user names in +shipped files, SKILL.md word count under the budget. + +### Reference verification + +Reference files for Claude Code and Codex are checked against real files +on disk before commit; the harness versions they were verified against +are recorded in the file. + +## Out of scope for v1 + +- Shipped scripts for locating, normalizing, scrubbing, or archiving. +- Transcript repair or session resume fixes. +- Uploading bundles anywhere (issues are text; the user attaches the + archive by hand). +- A triage skill that consumes the bundle (the remote side). +- Field-level references for harnesses whose formats were not verified. +- Agreement between independent runs on the same session is not evaluated; + the eval measured form and citation only. diff --git a/docs/testing.md b/docs/testing.md index 414d69790..d8ff01649 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -18,6 +18,7 @@ Live in `tests/`. Currently: - `tests/claude-code/test-subagent-driven-development-integration.sh` — extended SDD integration with token analysis (drill covers the YAGNI subset; bash adds commit-count, Claude Code task-tracking, and token telemetry assertions). - `tests/claude-code/test-worktree-native-preference.sh` — RED-GREEN-REFACTOR validation for worktree skill (drill covers the PRESSURE phase; bash also covers RED/GREEN baselines). - `tests/explicit-skill-requests/` — Haiku-specific, multi-turn, and skill-name-prompted tests not covered by drill. +- `tests/diagnosing-superpowers/test-skill-structure.sh` — structural checks for the diagnosing-superpowers skill (frontmatter, referenced files, leak scan, word budget); behavior-scenario eval records are kept by the maintainer outside the repo. Run plugin tests via the relevant directory's `run-*.sh` or `npm test`. diff --git a/skills/brainstorming/SKILL.md b/skills/brainstorming/SKILL.md index b56a3b5ed..e3f17885f 100644 --- a/skills/brainstorming/SKILL.md +++ b/skills/brainstorming/SKILL.md @@ -11,12 +11,48 @@ Start by classifying how much process the request needs, then work through your path: understand the context, refine the idea, present a design, and get your human partner's approval. +## Establish Shared Understanding + +The outcome of brainstorming is an understanding your human partner can +recognize and correct, grounded in what they want to accomplish. + +1. **Discover intent.** Use the request and available context to identify + the intended outcome, who it is for, and what success looks like. When + that information is missing, ask one focused question about purpose or + intended use before proposing features or an approach. Knowing the app + genre does not tell you why your partner wants it. Gathering missing + requirements does not ask them to authorize the task again. +2. **Write back your understanding.** Summarize the intended outcome, + relevant constraints, and success criteria in a short note your partner + can assess. Separate what they said from assumptions. Invite correction + and incorporate their answer before treating this as the design brief. +3. **Carry intent into the design.** Preserve the agreed understanding in + the selected path's design artifact: the written spec for architectural + work, or the in-chat design/probe for bounded work and spikes. Check + proposed features and technical choices against that understanding. + +When the request already supplies the purpose and constraints, reflect +that understanding instead of asking the same questions again. Keep the +note concise; its accuracy and the opportunity to correct it matter. + -Do NOT invoke any implementation skill, write any code, scaffold any -project, or take any implementation action until you have told your -human partner what you intend and they have approved it. This applies -to EVERY task on EVERY path below — the ceremony scales with the task; -the approval gate never does. +Before taking any implementation action, including invoking an +implementation skill, writing product code, scaffolding, installing +product dependencies, or creating an external project, complete the +selected path's prerequisites: + +- Spike: the human partner approves the question and probe. +- Bounded: the human partner approves the short in-chat design. +- Architectural: the human partner reviews and approves the written spec, + then reviews the written implementation plan and selects its execution + method. Conversational design approval only permits writing the spec; + written-spec approval only permits invoking writing-plans. + +A reply approves the stage actually presented. Approval of an idea or +feature scope does not approve artifacts that do not exist yet. Resume +at the earliest incomplete stage; do not turn one approval into permission +to skip the rest of the selected path. Read-only project exploration is +allowed while those prerequisites remain incomplete. ## Three Paths @@ -53,18 +89,17 @@ stop, say so, and step up. Nothing downgrades mid-task. ## Anti-Pattern: "Too Simple To Need Approval" -Every path ends with your human partner approving your intent before -implementation. A todo list, a single-function utility, a config -change — the design may be two sentences in chat, but you MUST present -it and get approval. "Simple" tasks are where unexamined assumptions -cause the most wasted work. What scales with simplicity is the -artifact, never the approval. +Every path ends with your human partner approving the required design +before implementation. A bounded change may need only two sentences in +chat. A new todo-list project is architectural and requires the written +spec and planning handoffs. Scale the artifact to the selected path; +complete that path's reviews before implementation. ## Red Flags | Thought | Reality | |---------|---------| -| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. | +| "This is too simple to need a design" | Follow the selected path: a bounded change gets a short chat design; an architectural change gets the written spec and planning handoffs. | | "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. | | "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. | | "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. | diff --git a/skills/diagnosing-superpowers/SKILL.md b/skills/diagnosing-superpowers/SKILL.md new file mode 100644 index 000000000..5e9f2f8f6 --- /dev/null +++ b/skills/diagnosing-superpowers/SKILL.md @@ -0,0 +1,118 @@ +--- +name: diagnosing-superpowers +description: 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 report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. +--- + +# 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. +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 + `~/.superpowers/diagnosing-superpowers//`, tell your + partner the path, and fill `templates/case.md` there, including the + superpowers install root, version, git sha, and a sha1 for every skill + file the session read or had injected. +3. **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`. +4. **Report.** Fill every section of `templates/report.md` in order, write + it to the workspace, show it, and give the path. +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`, repeating both until the audit returns CLEAN. + Show the scrub log and file list; archive (`zip -r` or `tar -czf`) + only after approval. With the archive path, state what it contains, + point at the scrub log for what was replaced, and say scrubbing can + miss things: they must review every file before sharing it. +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, 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. + +| Complaint | Read 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. +- **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 + +| Thought | Reality | +|---------|---------| +| "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. | diff --git a/skills/diagnosing-superpowers/prompts/analyst-common.md b/skills/diagnosing-superpowers/prompts/analyst-common.md new file mode 100644 index 000000000..d7c403306 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/analyst-common.md @@ -0,0 +1,38 @@ +You are an analyst subagent. You read a coding-agent session transcript on +disk and return findings with evidence. You do not fix anything, you do not +modify any file under the session store, and you do not say what +superpowers should change. + +Inputs (from your dispatcher): +- CASE: absolute path of the case file. Read it first. It names the session + files, the discovered sources and record meanings to use, and the + context-safety rules you must follow. Use the recorded meanings rather than + repeating discovery or assuming a harness format. +- RANGE (optional): a turn range or line range. If present, analyze only + that range and say so in your Checked line. + +Context safety: follow `references/context-safety.md`, named in CASE, on +every file before reading it, and extract fields with the recorded commands or +queries. "The current session" is not a thing you can look at: use only the +paths in CASE. + +Human prompts are the records the case file identifies as human-typed. Hook +output, system reminders, and tool results are not human prompts. In a subagent +transcript, "user" is the parent agent. + +Return format (nothing else): + +``` +## findings + +- finding: + evidence: : — "" + turns: – + confidence: high | medium | low + +Checked: +``` + +The dispatcher discards any finding without a `path:line`, so do not +write one. If you found nothing, return `- none found` and the Checked +line. diff --git a/skills/diagnosing-superpowers/prompts/cost-and-time.md b/skills/diagnosing-superpowers/prompts/cost-and-time.md new file mode 100644 index 000000000..fb9cc0a19 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/cost-and-time.md @@ -0,0 +1,28 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Cost and time + +Account for where tokens and wall-clock went. + +1. Tokens. Use only the usage records and counter meanings established in the + case file. State whether each counter is incremental or cumulative before + calculating totals; difference cumulative observations without turning a + missing observation into zero. Report the five turns with the largest + supported totals and the supported totals per associated session. +2. Wall-clock. Use the evidenced timestamp fields, event boundaries, and units + recorded in the case file. Report the five longest supported turns and any + gap longer than ten minutes between consecutive events (idle, waiting on an + associated session, or waiting on your human partner; say which only when + the records show it). +3. Largest tool results: use the case file's evidenced tool-result records to + report the ten largest results with their tool and turn. Measure records + before extracting bounded content. +4. Compactions: count and locate records whose meaning as compaction events was + established during discovery. Report available before/after counters and + what the session was doing when each fired; mark unsupported fields absent. +5. Associated sessions: count them and report supported usage, duration, and + dispatching turn for each. +6. Report the turns, subagents, tools, or repeats that dominate the + totals, with numbers. Do not speculate about why a + turn was expensive beyond what the transcript shows. diff --git a/skills/diagnosing-superpowers/prompts/plan-adherence.md b/skills/diagnosing-superpowers/prompts/plan-adherence.md new file mode 100644 index 000000000..aaaeac740 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/plan-adherence.md @@ -0,0 +1,29 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Plan adherence + +Recover the plan the session agreed to, then map each plan step to what +happened. "Plan" here means any agreed course of action, not git commits. + +1. Find the agreed plan: a design or plan agreed in chat (look for the + assistant text preceding a human "yes/ok/go ahead"), a spec or plan file + written during the session (tool calls that write under `docs/`, + `plans/`, `specs/`, or any file the human named), a todo-list record whose + meaning was established in the case file, or any numbered checklist in + assistant text. Quote each plan step with its `path:line`. +2. Mark structural events between the plan and its execution: compaction + events identified during discovery, resumes, aborted turns, and associated + session dispatches. Note their line numbers; plan drift right after one of + these is a distinct finding. +3. For each plan step, find the tool calls and assistant text that + executed it, or establish that none did. Report: + - steps skipped (no execution found; quote the plan step); + - steps executed out of order (line numbers show the order); + - steps silently changed (execution differs from the plan step in a + way the assistant never announced; quote both); + - steps invented (work done that no plan step covers); + - drift immediately after a structural event (cite the event line and + the first divergent action). +4. If there is no recoverable plan, say so as the only finding, with + the lines you checked. diff --git a/skills/diagnosing-superpowers/prompts/quality-evidence.md b/skills/diagnosing-superpowers/prompts/quality-evidence.md new file mode 100644 index 000000000..26ca5643d --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/quality-evidence.md @@ -0,0 +1,26 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Quality evidence + +Judge the process against its own claims. This is not a code review; do +not evaluate the code the session produced. + +1. Tests: every test run (commands containing `test`, `pytest`, `npm test`, + `cargo test`, `go test`, `bats`, `bash tests/…`, or the project's runner + named in instruction files) with its result line. Report runs that + failed and what the assistant did next. +2. Verification behind claims: find assistant text claiming done, fixed, + passing, verified, works, complete. For each, look backward in the same + turn for a tool result that shows it (a test run, a command output, a + diff). Report claims with no supporting result in that turn. +3. Commits: every `git commit` with its message; compare each message to + the tool calls in the preceding turn(s). Report commits whose message + claims work that no tool call performed, and work performed that was + never committed when the agreed plan said it would be. +4. Review feedback: where a reviewer (human or subagent) raised points, + find the response. Report points acknowledged but not acted on, and + points dismissed without a stated reason. +5. Acceptance criteria: if the case file's problem statement or the + agreed plan states criteria, report each as met / not met / + not checked with the evidence line. diff --git a/skills/diagnosing-superpowers/prompts/repeated-work.md b/skills/diagnosing-superpowers/prompts/repeated-work.md new file mode 100644 index 000000000..da2645a41 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/repeated-work.md @@ -0,0 +1,30 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Repeated work + +Find work the session did more than once. + +1. Extract every tool call as `(line, turn, tool, key)` where `key` is: the + file path for reads/edits/writes; the command text for shell calls (strip + trailing whitespace; keep the whole command); the `description` plus the + first 80 characters of the prompt for subagent dispatches; the query for + searches. +2. Group by `(tool, key)` and report the groups at or over threshold: + + | Category | Threshold | Exempt | + |---|---|---| + | reads, searches | 3 | | + | edits | 2 | | + | shell commands | 2 | status checks and test runs (`git status`, `ls`, `pwd`, test runners) | + | subagent dispatches | 2 with the same description | | +3. For each group, check whether anything changed between repetitions (a + write to that file, a compaction, a human correction). Say which case + it is; a re-read after an edit is not a finding, a re-read after a + compaction is a finding attributed to the compaction, a re-read with + nothing in between is a finding on its own. +4. Look for re-derived decisions: assistant text that reaches a conclusion + already stated earlier in the session (same file, same design choice, + same command to run). Quote both places. +5. One finding per group, with the first and last line numbers and the + count. diff --git a/skills/diagnosing-superpowers/prompts/request-conflicts.md b/skills/diagnosing-superpowers/prompts/request-conflicts.md new file mode 100644 index 000000000..4532236e7 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/request-conflicts.md @@ -0,0 +1,20 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Request conflicts + +1. List every human prompt with line and turn. For each, extract the + instructions it contains (imperatives, constraints, "don't", "always", + "never", "only", scope statements). +2. Report: + - two human instructions that cannot both be followed (quote both, with + lines), and what the assistant did; + - a human instruction that conflicts with an instruction file loaded in + the session (CLAUDE.md, AGENTS.md, GEMINI.md, or the harness's + equivalent; paths are in the case file), quoting both; + - a human instruction to skip, ignore, or override a step, skill, or + rule, and what happened afterwards; + - an instruction the assistant asked to clarify and the answer, when the + answer changed scope. +3. Do not judge whether your human partner was right. Report the conflict + and the assistant's resolution. diff --git a/skills/diagnosing-superpowers/prompts/scrub-audit.md b/skills/diagnosing-superpowers/prompts/scrub-audit.md new file mode 100644 index 000000000..658e3a0dd --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/scrub-audit.md @@ -0,0 +1,38 @@ +You are the scrub auditor. Another agent has already scrubbed every file +under BUNDLE. Your only job is to find what it missed. You do not fix +anything; you report. + +Inputs: +- BUNDLE: absolute path of the bundle directory. +- PUBLIC_REPOS and PROPRIETARY: same lists the scrubber had. + +Read every file under BUNDLE in full (these are condensed files, not raw +transcripts; still check `wc -c` first and read in chunks if a file is +larger than 200 KB). Look for anything in these categories that is not a +placeholder: email addresses; people's names or handles (including inside +quoted transcript text, commit messages, git author lines, and +`` placeholders that leaked the name next to them); account, +org, owner, tenant, workspace, or team identifiers; API keys, tokens, +passwords, bearer strings, private keys, `Authorization` headers; +hostnames and IP addresses that are not public package or docs domains; +absolute paths containing a username; repository names or URLs not in +PUBLIC_REPOS; any term in PROPRIETARY; and anything that reads as +customer, client, or internal-project content that a stranger should not +see. + +Return exactly one of: + +``` +CLEAN +``` + +or + +``` +MISSED +- : — — +... +``` + +Do not paste more than 20 characters of any missed value. Do not comment +on the scrub's quality. Do not suggest fixes. diff --git a/skills/diagnosing-superpowers/prompts/scrub.md b/skills/diagnosing-superpowers/prompts/scrub.md new file mode 100644 index 000000000..b84284908 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/scrub.md @@ -0,0 +1,38 @@ +You are the scrubber. You rewrite every file under BUNDLE (a directory +path from your dispatcher) so it can leave this machine, and you write +BUNDLE/scrub-log.md. You never touch anything outside BUNDLE. + +Inputs: +- BUNDLE: absolute path of the bundle directory. +- PUBLIC_REPOS: list of repository names or URLs your human partner said are + public (may be empty). +- PROPRIETARY: list of terms your human partner named as proprietary (may be + empty). + +Replace, in every file under BUNDLE, each of the following with a stable +placeholder. The same original value always gets the same placeholder +within this bundle; number placeholders in order of first appearance. + +| Category | Placeholder | What to catch | +|---|---|---| +| Email addresses | `` | anything shaped like an email | +| People | `` | given names, surnames, handles (`@name`), git author names; replace the whole name; role words ("the reviewer", "your human partner") stay | +| Account / org identifiers | `` | UUIDs and ids labelled account, org, owner, tenant, workspace, team | +| Secrets | `` | API keys, tokens, passwords, bearer strings, private keys, anything assigned to a variable named like `*_KEY`, `*_TOKEN`, `*_SECRET`, `PASSWORD`, `Authorization` | +| Hosts and addresses | `` | hostnames that are not public package or docs domains, IPv4/IPv6 addresses, internal URLs | +| Home paths | `~` | any absolute path under a home directory becomes `~/…`; the account-name segment is removed | +| Repositories | `` | repository names, slugs, and remote URLs, unless the name or URL is in PUBLIC_REPOS | +| Proprietary terms | `` | each term in PROPRIETARY, case-insensitive, whole-word | + +Session ids, tool names, skill names, superpowers file paths relative to +the install root, model ids, harness versions, and line numbers are kept: +the bundle is useless without them. + +Procedure: +1. `find BUNDLE -type f` and process every file, including + `environment.json` and `findings/*.md`. +2. Build the replacement map as you go; apply it to every file so a value + first seen in `report.md` is also replaced in `transcripts/`. +3. Write BUNDLE/scrub-log.md: a table of placeholder → category → number of + occurrences. Never write the original value into the log. +4. Return the scrub-log table and the list of files rewritten. Nothing else. diff --git a/skills/diagnosing-superpowers/prompts/similar-session.md b/skills/diagnosing-superpowers/prompts/similar-session.md new file mode 100644 index 000000000..d012001d2 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/similar-session.md @@ -0,0 +1,38 @@ +You are a matcher. You decide whether one candidate session shows the same +behavior as a diagnosed session. You do not modify any file. + +Inputs: +- CASE: absolute path of the diagnosed session's case file. Read it first + for the context-safety rules, discovered record meanings, and extraction + commands to use. +- CANDIDATE: absolute path of one session transcript to examine. +- SIGNATURE: a list of markers. Each marker is one of: + - `skill-sequence: then within turns` + - `error-string: ""` + - `repeated-command: "" ≥ times` + - `repeated-file: read ≥ times` + - `compaction-then: ` + - `missed-trigger: for requests matching ""` + - `free: ` (use only the transcript to judge) + +Procedure: +1. Apply `references/context-safety.md` to CANDIDATE. Extract its identity + with the commands recorded in CASE: session id, cwd, first human prompt, + first timestamp, harness version, and models. +2. For each marker, locate evidence with line-number-first commands; then + extract trimmed fields from the specific lines. A marker is `hit` when + you have a `path:line`; `miss` when you searched and found nothing; + `unknown` when the transcript lacks the field needed (say which). +3. Return exactly: + +``` +candidate: — +identity: , , "" +match: yes | partial | no +markers: +- : hit — : — "" +- : miss — checked +- : unknown — +``` + +`yes` = every marker hit; `partial` = at least one hit; `no` = none. diff --git a/skills/diagnosing-superpowers/prompts/skill-timeline.md b/skills/diagnosing-superpowers/prompts/skill-timeline.md new file mode 100644 index 000000000..ecbe21d11 --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/skill-timeline.md @@ -0,0 +1,30 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Skill timeline + +Build the per-human-turn record of skill and plugin use, then look for gaps. + +1. List the human prompts with line numbers and timestamps. +2. Using the skill-invocation and attribution meanings established in the case + file, list every explicit invocation, active-skill attribution, or read of a + file named `SKILL.md`. Record the line, the skill name, and the human turn it + happened in. +3. List every non-superpowers plugin, skill, agent type, MCP server, or + hook used. Use only the evidenced tool, attribution, agent-dispatch, MCP, + and hook meanings recorded in the case file; identify values associated + with something other than `superpowers`. +4. For each human turn, compare the request text against the trigger + descriptions of the superpowers skills installed (read + `/skills/*/SKILL.md` frontmatter `description` lines; the + install root is in the case file). Report as findings: + - a skill invoked, with the request that preceded it (one finding per + invocation is fine when there are few; group by skill when many); + - a turn whose request matches a skill's trigger description with no + invocation in that turn (state which description matched and quote + the request); + - a skill invoked one or more turns after the matching request (late); + - each non-superpowers plugin/skill/tool used, with where. + +Do not say whether a missed or late trigger was wrong. Report the match +and the absence; the reader decides. diff --git a/skills/diagnosing-superpowers/prompts/stumbles.md b/skills/diagnosing-superpowers/prompts/stumbles.md new file mode 100644 index 000000000..22b3705fc --- /dev/null +++ b/skills/diagnosing-superpowers/prompts/stumbles.md @@ -0,0 +1,28 @@ +Read `prompts/analyst-common.md` first; it gives your role, inputs, +context-safety rules, and the return format. This file adds the dimension. + +Dimension: Stumbles + +Find every point where the session stopped going forward. + +Sources, each using the case file's evidenced record meanings and extraction +commands to locate line numbers: +- tool results marked as errors, non-zero exits, or explicit failure records; +- shell commands that failed (non-zero exit in the result, "command not + found", "No such file"); +- retries: the same tool call re-issued within the same turn after an + error; +- reverted edits: an edit followed by an edit that restores the earlier + content, or `git checkout`/`git restore`/`git revert`/`git reset` on a + file the session touched; +- backtracking in assistant text ("actually", "let me instead", "that was + wrong", "I misread"); +- human corrections: a human prompt that contradicts or corrects the + assistant's immediately preceding action; +- permission denials, hook failures, API errors, rate limits, aborted turns, + and context overflow or compaction triggered mid-task. + +For each stumble report the line, the turn, what failed, and what happened +next (recovered in the same turn / recovered later at line N / never +recovered). Group identical repeated failures into one finding with a +count. diff --git a/skills/diagnosing-superpowers/references/context-safety.md b/skills/diagnosing-superpowers/references/context-safety.md new file mode 100644 index 000000000..be09ed84f --- /dev/null +++ b/skills/diagnosing-superpowers/references/context-safety.md @@ -0,0 +1,22 @@ +# Context safety for session transcripts + +One transcript record can exceed a megabyte or embed a whole history. Printing +one whole record can overflow the context of the session doing the diagnosis. +Every reader of a session file, controller or subagent, follows these rules for +every file, every time. + +1. **Measure before reading.** + + ```bash + wc -lc "$F" + awk '{ if (length($0) > 100000) print NR, length($0) }' "$F" # long lines + ``` + +2. **Never `cat` or `grep` for content.** Get line numbers and counts + first (`grep -n … | cut -d: -f1`, `jq -r '.type' | sort | uniq -c`), + then small fields from specific lines (`sed -n Np | jq -c '{…}'` or + `| cut -c1-500`). Use the field-extraction commands established during + discovery for the source in front of you. +3. **Narrow anything over 500 characters.** If a command returns more than + 500 characters for one record, tighten the field or the slice. +4. **Read-only.** Never modify, move, or delete a session file. diff --git a/skills/diagnosing-superpowers/references/github-issues.md b/skills/diagnosing-superpowers/references/github-issues.md new file mode 100644 index 000000000..e9a27a16a --- /dev/null +++ b/skills/diagnosing-superpowers/references/github-issues.md @@ -0,0 +1,47 @@ +# GitHub issues + +Use `gh` when it is installed and authenticated; it handles auth, rate +limits, and JSON. Fall back to the public API with curl, then to a URL +your partner opens. + +## Search + +```bash +gh search issues --repo obra/superpowers --limit 10 "" \ + --json number,state,title --jq '.[] | "\(.number)\t\(.state)\t\(.title)"' +``` + +Without `gh` (unauthenticated, 10 requests a minute): + +```bash +curl -s -H "Accept: application/vnd.github+json" \ + "https://api.github.com/search/issues?q=repo:obra/superpowers+is:issue+&per_page=10" \ + | jq -r '.items[] | "\(.number)\t\(.state)\t\(.title)"' +``` + +Without curl, hand over `https://github.com/obra/superpowers/issues?q=`. + +## File + +Write the filled `templates/issue.md` to the workspace and show the exact +text. After approval: + +```bash +gh issue create --repo obra/superpowers --title "" --body-file <path> \ + --label bug --label automated-issue-report +``` + +GitHub drops labels silently when the reporter lacks push access, so the +labels land only for collaborators; the template footer still marks the +issue as skill-filed. `gh` cannot attach files: give your partner the +bundle path to attach through the browser after the issue exists. + +Without `gh`, hand over a prefilled link on the `diagnosis_report.md` +template, which applies both labels for any reporter: + +``` +https://github.com/obra/superpowers/issues/new?template=diagnosis_report.md&title=<url-encoded title>&body=<url-encoded body> +``` + +GitHub rejects URLs over about 8,000 characters; past that, send the link +with the title only and tell your partner to paste the body from the file. diff --git a/skills/diagnosing-superpowers/references/session-discovery.md b/skills/diagnosing-superpowers/references/session-discovery.md new file mode 100644 index 000000000..d069ff8b9 --- /dev/null +++ b/skills/diagnosing-superpowers/references/session-discovery.md @@ -0,0 +1,31 @@ +# Discover the session history + +Resolve the session your human partner named using the tools and information +available in this environment. Your knowledge can suggest where to look; verify +the result against the actual history. + +Use the harness's exposed session tools, configured storage, local help, +documentation, or bounded filesystem inspection. Measure files before reading +their content and follow context-safety.md. Inspect archives or indexes when the +environment points to them. A supplied usable path does not need another search. + +Confirm identity using the available session id, working directory, timestamps, +and matching conversation content. Recency alone is not confirmation. Distinguish +the requested session from its children and unrelated candidates. Ask for a +missing identifying fact when the available evidence cannot distinguish them. + +For each filesystem source, obtain its full absolute path from the environment, +with home-directory shorthand and variables expanded. Use that same path in the +case record and in the discovery answer you give your human partner. + +Establish the record meanings needed for the requested investigation from +observed records or documentation. Distinguish human messages from injected +messages, tool results, and a parent agent's dispatch. Match tool calls to their +results. Establish usage-counter semantics before calculating totals. Do not +infer a format from another harness or turn a missing field into a zero. + +Record the exact sources, relevant field meanings, supporting record locations, +associated sessions, rejected plausible candidates, and unresolved information +in the case file. Subsequent readers use that record rather than repeating +discovery. If history is missing, inaccessible, or ambiguous, state the specific +limitation and ask for the missing path, export, or identifying detail. diff --git a/skills/diagnosing-superpowers/templates/bundle-README.md b/skills/diagnosing-superpowers/templates/bundle-README.md new file mode 100644 index 000000000..6d71c94a7 --- /dev/null +++ b/skills/diagnosing-superpowers/templates/bundle-README.md @@ -0,0 +1,47 @@ +# 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 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 | replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]` | + | evidence | kept only for events cited in 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. diff --git a/skills/diagnosing-superpowers/templates/case.md b/skills/diagnosing-superpowers/templates/case.md new file mode 100644 index 000000000..fff6fe66f --- /dev/null +++ b/skills/diagnosing-superpowers/templates/case.md @@ -0,0 +1,57 @@ +# 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 + +- 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"> diff --git a/skills/diagnosing-superpowers/templates/issue.md b/skills/diagnosing-superpowers/templates/issue.md new file mode 100644 index 000000000..89433de06 --- /dev/null +++ b/skills/diagnosing-superpowers/templates/issue.md @@ -0,0 +1,51 @@ +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">) + +## 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 + +The reporter has not tried reproducing without superpowers. 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>. Bundle: <attached, redaction level <level> | none +built>. +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 | +|---|---|---|---|---|---| diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index f74605bfa..b2304cd17 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -152,15 +152,25 @@ If you find issues, fix them inline. No need to re-review — just fix and move ## Execution Handoff -After saving the plan, offer execution choice: +After saving and self-reviewing the plan, link it for your human partner +to read. If they have already explicitly supplied an execution method, ask +them to review the plan and confirm it captures what they want; wait for that +review before implementation, then use the preserved method. Otherwise, ask +them to review the plan and choose an execution method before implementation. -**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Two execution options:** +**When no execution method has already been supplied:** + +**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Two execution options:** **1. Subagent-Driven (recommended)** - I dispatch a fresh subagent per task, review between tasks, fast iteration **2. Inline Execution** - Execute tasks in this session using executing-plans, batch execution with checkpoints -**Which approach?"** +**Does the plan capture what you want, and which approach should we use?"** + +**When an execution method has already been supplied:** + +**"Plan complete and saved to `docs/superpowers/plans/<filename>.md`. Please review the plan. Does it capture what you want?"** **If Subagent-Driven chosen:** - **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development diff --git a/tests/diagnosing-superpowers/test-skill-structure.sh b/tests/diagnosing-superpowers/test-skill-structure.sh new file mode 100755 index 000000000..e398ee36b --- /dev/null +++ b/tests/diagnosing-superpowers/test-skill-structure.sh @@ -0,0 +1,150 @@ +#!/usr/bin/env bash +# Structural checks for skills/diagnosing-superpowers. Behavior is tested by +# scenario evals kept by the maintainer; this script only checks the things a +# shell can check: frontmatter, referenced files exist, no local paths or +# names leaked into shipped files, SKILL.md word budget. +set -u + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +SKILL_DIR="$REPO_ROOT/skills/diagnosing-superpowers" +SKILL_MD="$SKILL_DIR/SKILL.md" +WORD_BUDGET=1000 + +PASSES=0 +FAILURES=0 + +pass() { echo " [PASS] $1"; PASSES=$((PASSES + 1)); } +fail() { echo " [FAIL] $1"; FAILURES=$((FAILURES + 1)); } + +echo "diagnosing-superpowers structure" + +# --- SKILL.md frontmatter ------------------------------------------------- +if [ -f "$SKILL_MD" ]; then + pass "SKILL.md exists" + frontmatter="$(awk 'NR==1 && $0!="---"{exit} NR>1 && $0=="---"{exit} NR>1{print}' "$SKILL_MD")" + if printf '%s\n' "$frontmatter" | grep -q '^name: diagnosing-superpowers$'; then + pass "frontmatter name is diagnosing-superpowers" + else + fail "frontmatter name is diagnosing-superpowers" + fi + description="$(printf '%s\n' "$frontmatter" | awk '/^description:/{sub(/^description:[ ]*/,""); print; found=1; next} found && /^[ ]/{print} found && !/^[ ]/{exit}' | tr '\n' ' ')" + if printf '%s' "$description" | grep -q '^Use when'; then + pass "description starts with 'Use when'" + else + fail "description starts with 'Use when' (got: ${description:0:60})" + fi + if [ "${#description}" -le 1024 ]; then + pass "description under 1024 characters" + else + fail "description under 1024 characters (${#description})" + fi + for banned in "dispatch" "then" "step"; do + if printf '%s' "$description" | grep -qiw "$banned"; then + fail "description contains workflow word '$banned'" + else + pass "description avoids workflow word '$banned'" + fi + done + + # --- word budget -------------------------------------------------------- + body_words="$(awk 'BEGIN{fm=0} NR==1 && $0=="---"{fm=1; next} fm==1 && $0=="---"{fm=2; next} fm==2{print}' "$SKILL_MD" | wc -w | tr -d ' ')" + if [ "$body_words" -le "$WORD_BUDGET" ]; then + pass "SKILL.md body within $WORD_BUDGET words ($body_words)" + else + fail "SKILL.md body within $WORD_BUDGET words ($body_words)" + fi + + # --- required sections -------------------------------------------------- + for heading in "## Hard rules" "## Red Flags"; do + if grep -q "^$heading" "$SKILL_MD"; then + pass "SKILL.md has section '$heading'" + else + fail "SKILL.md has section '$heading'" + fi + done + + # --- every referenced skill file exists -------------------------------- + while IFS= read -r ref; do + if [ -f "$SKILL_DIR/$ref" ]; then + pass "referenced file exists: $ref" + else + fail "referenced file exists: $ref" + fi + done < <(grep -o '\(references\|prompts\|templates\)/[A-Za-z0-9._-]*\.md' "$SKILL_MD" | sort -u) +else + fail "SKILL.md exists" +fi + +# --- expected files ------------------------------------------------------- +expected_files=( + references/session-discovery.md + references/context-safety.md + references/github-issues.md + prompts/analyst-common.md + prompts/skill-timeline.md + prompts/plan-adherence.md + prompts/repeated-work.md + prompts/stumbles.md + prompts/quality-evidence.md + prompts/request-conflicts.md + prompts/cost-and-time.md + prompts/scrub.md + prompts/scrub-audit.md + prompts/similar-session.md + templates/case.md + templates/report.md + templates/bundle-README.md + templates/issue.md +) +for rel in "${expected_files[@]}"; do + if [ -f "$SKILL_DIR/$rel" ]; then + pass "expected file present: $rel" + else + fail "expected file present: $rel" + fi +done + +# --- removed harness recipes stay removed -------------------------------- +removed_files=( + references/claude-code-sessions.md + references/codex-sessions.md + references/other-harnesses.md +) +for rel in "${removed_files[@]}"; do + if [ ! -e "$SKILL_DIR/$rel" ]; then + pass "removed reference absent: $rel" + else + fail "removed reference absent: $rel" + fi +done + +removed_reference_hits="$(grep -rn -E 'references/(claude-code-sessions|codex-sessions|other-harnesses)\.md' "$SKILL_DIR" --include='*.md' 2>/dev/null || true)" +if [ -z "$removed_reference_hits" ]; then + pass "active skill prose has no references to removed harness recipes" +else + fail "active skill prose has no references to removed harness recipes" + printf '%s\n' "$removed_reference_hits" | head -10 | sed 's/^/ /' +fi + +# --- no local paths or names in shipped files ---------------------------- +leaks="$(grep -rn -E '/Users/|/home/|jesse' "$SKILL_DIR" "$SCRIPT_DIR" --exclude=test-skill-structure.sh 2>/dev/null || true)" +if [ -z "$leaks" ]; then + pass "no machine-specific paths or names in shipped files (skills + tests)" +else + fail "no machine-specific paths or names in shipped files (skills + tests)" + printf '%s\n' "$leaks" | head -10 | sed 's/^/ /' +fi + +# --- "the user" never appears in skill prose ----------------------------- +user_hits="$(grep -rn -i 'the user' "$SKILL_DIR" --include='*.md' 2>/dev/null || true)" +if [ -z "$user_hits" ]; then + pass "skill files say 'your human partner', not 'the user'" +else + fail "skill files say 'your human partner', not 'the user'" + printf '%s\n' "$user_hits" | head -10 | sed 's/^/ /' +fi + +echo +echo "Passed: $PASSES Failed: $FAILURES" +[ "$FAILURES" -eq 0 ]