diagnosing-superpowers: writing review fixes

Move GitHub search and prefilled-link mechanics to references/github-issues.md.
State the redaction levels neutrally instead of nudging toward more data.
Say that all seven analysts always run and what the quick-reference table
is for. Add a title slot and a bundle slot to the issue template. Drop the
duplicated human-prompts rule from request-conflicts. Prose fixes: active
voice, dangling modifier, vague referents, two lists turned into tables.

docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md

@@ -56,6 +56,7 @@ skills/diagnosing-superpowers/
     codex-sessions.md
     other-harnesses.md
     context-safety.md
+    github-issues.md
   prompts/
     analyst-common.md
     skill-timeline.md

skills/diagnosing-superpowers/SKILL.md

@@ -49,20 +49,16 @@ Create a todo per step. Steps 5–7 run only on their stated condition.
 5. **GitHub issues** — when report §7 says possible or likely, or your
    partner asks. Never use `gh`: its token usually has write access to
    every repo your partner can reach. Search open and closed issues for
-   the symptoms with curl against the public API
-   (`https://api.github.com/search/issues?q=repo:obra/superpowers+<terms>`),
-   else hand over a search URL. Show matches and suggest adding the
-   report to the closest. If none match, fill `templates/issue.md`, write
-   it to the workspace, show it, and build a prefilled link:
-   `https://github.com/obra/superpowers/issues/new?template=diagnosis_report.md&title=<encoded>&body=<encoded>`.
-   Over 8,000 characters, send the link with the title only and point at
-   the file to paste. Your partner submits and attaches any bundle in the
-   form; you never post.
+   the symptoms with the public API 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 it,
+   and hand over the prefilled link from that reference. Your partner
+   submits and attaches any bundle in the form; you never post.
 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: skeleton, evidence, or full; more information gives the
-   maintainers a better chance to help. Build the bundle per
+   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`)
@@ -76,7 +72,10 @@ Create a todo per step. Steps 5–7 run only on their stated condition.
 
 ## Quick reference
 
-| Complaint | Start with |
+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 |
@@ -96,9 +95,10 @@ Create a todo per step. Steps 5–7 run only on their stated condition.
   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. Pushing does not
-  waive this; point at the issue step and mention that a bundle is
-  available on request. No advice to your partner either.
+  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. You never post to GitHub; your partner submits the
   prefilled issue themselves.

skills/diagnosing-superpowers/prompts/analyst-common.md

@@ -32,7 +32,7 @@ Return format (nothing else):
 Checked: <what you examined: files, line ranges, commands used>
 ```
 
-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
+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.
 

skills/diagnosing-superpowers/prompts/cost-and-time.md

@@ -24,6 +24,6 @@ Account for where tokens and wall-clock went.
    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
+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.

skills/diagnosing-superpowers/prompts/repeated-work.md

@@ -10,11 +10,14 @@ Find work the session did more than once.
    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.
+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

skills/diagnosing-superpowers/prompts/request-conflicts.md

@@ -3,10 +3,6 @@ context-safety rules, and the return format. This file adds the dimension.
 
 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).

skills/diagnosing-superpowers/references/claude-code-sessions.md

@@ -14,7 +14,7 @@ and say so in coverage notes.
   (`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
+- The superpowers bootstrap 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.

skills/diagnosing-superpowers/references/codex-sessions.md

@@ -17,7 +17,7 @@ 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. Newer rollouts may carry no `user_message` event at all: when
-that command returns nothing, fall back to `response_item` messages with
+the human-prompts query under Safe extraction returns nothing, fall back to `response_item` messages with
 `role:"user"` (see Human-typed prompt below) and confirm against the first
 of those instead.
 

skills/diagnosing-superpowers/references/context-safety.md

@@ -1,8 +1,8 @@
 # Context safety for session transcripts
 
 One transcript line can exceed a megabyte; a Codex `compacted` line can
-embed a whole history. Printing one whole line can end the session doing
-the diagnosis. Every reader of a session file, controller or subagent,
+embed a whole history. Printing one whole line 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.**

skills/diagnosing-superpowers/references/github-issues.md

@@ -0,0 +1,34 @@
+# GitHub issues without `gh`
+
+A default `gh` login carries the `repo` scope: write access to every
+repository your human partner can reach. This step needs none of that, so
+it uses the public API and the browser.
+
+## Search
+
+Unauthenticated, 10 requests a minute. Search open and closed issues:
+
+```bash
+curl -s -H "Accept: application/vnd.github+json" \
+  "https://api.github.com/search/issues?q=repo:obra/superpowers+is:issue+<url-encoded terms>&per_page=10" \
+  | jq -r '.items[] | "\(.number)\t\(.state)\t\(.title)"'
+```
+
+If curl is unavailable, hand over the search URL instead:
+`https://github.com/obra/superpowers/issues?q=<terms>`.
+
+## File
+
+Write the filled `templates/issue.md` to the workspace, then build the
+link. The `diagnosis_report.md` template applies the `bug` and
+`automated-issue-report` labels for any reporter; the `labels=` parameter
+would not.
+
+```
+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. If the link exceeds
+that, send it with the title only and tell your partner to paste the body
+from the file. Your partner submits the issue and attaches any bundle in
+the form.

skills/diagnosing-superpowers/templates/bundle-README.md

@@ -7,12 +7,12 @@ Built: <ISO timestamp>
 
 ## What this is
 
-A scrubbed record of a coding-agent session in which superpowers was
-installed and something went wrong, prepared so that an agent or person
-who was not present can decide whether superpowers contributed and, if so,
-what to change. The report inside states what happened with `path:line`
-evidence. By design it contains no diagnosis of superpowers and no proposed
-fix; that is the reader's job.
+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
 
@@ -23,10 +23,13 @@ fix; that is the reader's job.
 - `timeline.md` — the per-turn timeline.
 - `findings/<dimension>.md` — raw analyst findings per dimension.
 - `transcripts/<session-id>.md` — condensed per-turn rendering of each
-  examined session (never the raw JSONL). At *skeleton* level tool-result
-  bodies are replaced by `[tool result: <tool>, <bytes> bytes, exit <code>]`;
-  at *evidence* level bodies are kept only for events cited in findings; at
-  *full* level all bodies are kept.
+  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).
 

skills/diagnosing-superpowers/templates/issue.md

@@ -1,3 +1,5 @@
+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)
@@ -15,8 +17,8 @@
 
 - [ ] 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.
+The reporter has not tried reproducing without superpowers. Evidence for
+involvement is below; it does not establish cause.
 
 ## What happened?
 
@@ -39,8 +41,8 @@ rewritten as `transcript line <n>`.>
 
 ## Debug log or conversation transcript
 
-Session id(s): <ids>. A scrubbed bundle (redaction level: <level>) is
-attached to this issue by the reporter, or available on request.
+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.
 

tests/diagnosing-superpowers/test-skill-structure.sh

@@ -82,6 +82,7 @@ expected_files=(
   references/codex-sessions.md
   references/other-harnesses.md
   references/context-safety.md
+  references/github-issues.md
   prompts/analyst-common.md
   prompts/skill-timeline.md
   prompts/plan-adherence.md