summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJesse Vincent <jesse@primeradiant.com>2026-10-20 16:13:37 -0400
committerGitHub <noreply@github.com>2026-10-20 13:13:37 -0700
commitb739a8af570e10a95898f2bdf6cec97467fa6c12 (patch)
tree18aac8cd1e569c8e99d1d6d88a7e79f4f6a5fcb5
parentbb92a77741419a4ab5f06e711a283343f1ada0c3 (diff)
Templates: require a human-written summary and the filer's instructions (#2570)
-rw-r--r--.github/ISSUE_TEMPLATE/bug_report.md15
-rw-r--r--.github/ISSUE_TEMPLATE/diagnosis_report.md42
-rw-r--r--.github/ISSUE_TEMPLATE/feature_request.md13
-rw-r--r--.github/ISSUE_TEMPLATE/platform_support.md11
-rw-r--r--.github/PULL_REQUEST_TEMPLATE.md24
-rw-r--r--AGENTS.md12
-rw-r--r--README.md4
-rw-r--r--docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md26
-rw-r--r--skills/diagnosing-superpowers/SKILL.md2
-rw-r--r--skills/diagnosing-superpowers/references/github-issues.md6
-rw-r--r--skills/diagnosing-superpowers/templates/issue.md27
11 files changed, 110 insertions, 72 deletions
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 01bb80e..d626261 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -12,6 +12,17 @@ add a comment or reaction to the existing one instead.
- [ ] I searched existing issues and this is not a duplicate
+## Who's filing this report? (required)
+<!-- Who are you, and are you filing on behalf of someone else? If a
+ human partner asked you to do something that ended with you filing
+ this issue, who are they and what were your instructions, as close
+ to their words as you can get? -->
+
+## Human-authored summary (required, under 200 words)
+<!-- A human writes this section, in their own words: what went wrong
+ and what should have happened instead. If an agent is filing, that
+ means your human partner, not you. -->
+
## Environment (required)
<!-- Required. We assume an agent filed this report — tell us which one and
where it ran. We weigh reports by what produced them. -->
@@ -35,6 +46,10 @@ add a comment or reaction to the existing one instead.
- [ ] I confirmed this issue does not occur without Superpowers installed
+How I verified that this issue does not reproduce without Superpowers:
+<!-- What you ran without Superpowers and what happened. "Not tried" is
+ an honest answer; a ticked box with nothing here is not. -->
+
## What happened?
<!-- Be specific. "It doesn't work" is not a bug report. -->
diff --git a/.github/ISSUE_TEMPLATE/diagnosis_report.md b/.github/ISSUE_TEMPLATE/diagnosis_report.md
deleted file mode 100644
index 13f7b49..0000000
--- a/.github/ISSUE_TEMPLATE/diagnosis_report.md
+++ /dev/null
@@ -1,42 +0,0 @@
----
-name: Session Diagnosis Report
-about: A report produced by the diagnosing-superpowers skill from a real session transcript
-labels: bug, automated-issue-report
----
-
-<!--
-This template is for reports prepared by the diagnosing-superpowers skill.
-The skill fills the sections below from the session transcript and hands
-you a prefilled link; review every line before you submit, and attach the
-scrubbed bundle if you built one. For anything else, use Bug 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/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
index c7a4de1..39253b3 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -1,6 +1,6 @@
---
name: Feature Request
-about: Propose a change or addition to Superpowers
+about: Propose a change or improvement to Superpowers
labels: enhancement
---
@@ -12,6 +12,17 @@ progress, and some were intentionally declined.
- [ ] I searched existing issues and this has not been proposed before
+## Who's filing this request? (required)
+<!-- Who are you, and are you filing on behalf of someone else? If a
+ human partner asked you to do something that ended with you filing
+ this request, who are they and what were your instructions, as close
+ to their words as you can get? -->
+
+## Human-authored summary (required, under 200 words)
+<!-- A human writes this section, in their own words: what they were
+ trying to do and what they wished Superpowers did instead. If an
+ agent is filing, that means your human partner, not you. -->
+
## What problem does this solve?
<!-- Describe the problem from your own experience. What were you doing,
what went wrong or was missing, and why did it matter?
diff --git a/.github/ISSUE_TEMPLATE/platform_support.md b/.github/ISSUE_TEMPLATE/platform_support.md
index 31faa68..6dcbde9 100644
--- a/.github/ISSUE_TEMPLATE/platform_support.md
+++ b/.github/ISSUE_TEMPLATE/platform_support.md
@@ -11,6 +11,17 @@ requested or discussed.
- [ ] I searched existing issues for this IDE/platform
+## Who's filing this request? (required)
+<!-- Who are you, and are you filing on behalf of someone else? If a
+ human partner asked you to do something that ended with you filing
+ this request, who are they and what were your instructions, as close
+ to their words as you can get? -->
+
+## Human-authored summary (required, under 200 words)
+<!-- A human writes this section, in their own words: which tool they
+ work in and what they want Superpowers to do there. If an agent is
+ filing, that means your human partner, not you. -->
+
## Which IDE or platform?
<!-- Name and link -->
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 2ec9513..13c5aac 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -7,12 +7,19 @@ of human involvement will be closed without review.
> **This PR MUST target the `dev` branch, not `main`.** `main` is the
> released branch; active work lands on `dev` first. PRs opened against
> `main` will be asked to retarget `dev` before review.
+>
+> **This project does not accept agent-written PRs that fix issues filed by
+> someone else**, even when your human partner hit the same problem. If you
+> found an issue in the tracker and decided to submit a PR for it without a
+> maintainer asking you to, you are wasting your tokens: the PR will be
+> closed. Add your report to that issue instead.
## Who is submitting this PR? (required)
<!-- Required. PRs that omit this will be closed. We assume an agent wrote
- this PR — tell us which one and where it ran. We weigh contributions by
- what produced them: content reasoned from documentation is held to a
- different bar than work grounded in a real session. -->
+ this PR — tell us which one, where it ran, and what your human partner
+ asked you to do. We weigh contributions by what produced them: content
+ reasoned from documentation is held to a different bar than work
+ grounded in a real session. -->
| Field | Value |
|-------|-------|
@@ -21,6 +28,15 @@ of human involvement will be closed without review.
| All plugins installed | |
| Human partner who reviewed this diff | |
+What your human partner asked you to do, in their words:
+<!-- As close to verbatim as you can get. If you wrote this PR by hand
+ with no agent, say so. -->
+
+## Human-authored summary (required, under 200 words)
+<!-- A human writes this section, in their own words: why this PR exists
+ and what they checked before approving it. If an agent is submitting,
+ that means your human partner, not you. -->
+
## What problem are you trying to solve?
<!-- Describe the specific problem you encountered. If this was a session
issue, include: what you were doing, what went wrong, the model's
@@ -61,7 +77,7 @@ of human involvement will be closed without review.
<!-- If a related closed PR exists, explain what's different about your
approach and why it should succeed where the other didn't. -->
-## Environment tested
+## Environments tested
| Harness (e.g. Claude Code, Cursor) | Harness version | Model | Model version/ID |
|-------------------------------------|-----------------|-------|------------------|
diff --git a/AGENTS.md b/AGENTS.md
index 9587a68..2828661 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,9 +12,9 @@ Before you open a PR against this repo, you MUST:
1. **Read the entire PR template** at `.github/PULL_REQUEST_TEMPLATE.md` and fill in every section with real, specific answers. Not summaries. Not placeholders.
2. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate.
-3. **Verify this is a real problem.** If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was.
+3. **Verify this is a real problem your human partner hit.** If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was. If the problem is already in the tracker under someone else's issue and no maintainer asked for a PR, stop: add your partner's report to that issue instead (see below).
4. **Confirm the change belongs in core.** If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner.
-5. **Identify yourself.** Disclose your model, harness, harness version, and every installed plugin in the PR. Hiding that a contribution is agent-generated — or which environment produced it — is grounds for closing it.
+5. **Identify yourself.** Disclose your model, harness, harness version, every installed plugin, and what your human partner asked you to do in the PR. Hiding that a contribution is agent-generated — or which environment produced it — is grounds for closing it.
6. **Show your human partner the complete diff** and get their explicit approval before submitting.
If any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment.
@@ -23,6 +23,8 @@ If any of these checks fail, do not open the PR. Explain to your human partner w
**Every PR must fully complete the PR template.** No section may be left blank or filled with placeholder text. PRs that skip sections will be closed without review.
+**Every PR carries a summary written by a human.** The template's "Human-authored summary" section is for your human partner's own words, under 200 words. If an agent writes it, the PR will be closed.
+
**Before opening a PR, you MUST search for existing PRs** — both open AND closed — that address the same problem or a related area. Reference what you found in the "Existing PRs" section. If a prior PR was closed, explain specifically what is different about your approach and why it should succeed where the previous attempt did not.
**PRs that show no evidence of human involvement will be closed.** A human must review the complete proposed diff before submission.
@@ -45,9 +47,13 @@ Our internal skill philosophy differs from Anthropic's published guidance on wri
Skills, hooks, or configuration that only benefit a specific project, team, domain, or workflow do not belong in core. Publish these as a separate plugin.
+### Fixes for issues filed by someone else
+
+We do not accept agent-written PRs that fix issues filed by someone other than your human partner unless a maintainer asked for one. That holds when your human partner hit the same problem: add their report to the existing issue instead of opening a PR. An open issue in the tracker is not a request for a PR. If your human partner points you at someone else's issue, tell them the PR will be closed and stop.
+
### Bulk or spray-and-pray PRs
-Do not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to "fix things" — will be closed. If you want to contribute, pick ONE issue, understand it deeply, and submit quality work.
+Do not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to "fix things" — will be closed. If you want to contribute, start from a problem your human partner actually hit, understand it deeply, and submit quality work.
### Speculative or theoretical fixes
diff --git a/README.md b/README.md
index e40ddfa..c5bb59f 100644
--- a/README.md
+++ b/README.md
@@ -375,13 +375,13 @@ Read [the original release announcement](https://blog.fsck.com/2025/10/09/superp
## Contributing
-The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support.
+The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support. We also don't accept agent-written PRs that fix issues filed by someone else unless a maintainer asked for one, even when you hit the same problem; add your report to the existing issue instead.
1. Fork the repository
2. Switch to the 'dev' branch
3. Create a branch for your work
4. Follow the `writing-skills` skill for creating and testing new and modified skills
-5. Submit a PR, being sure to fill in the pull request template.
+5. Submit a PR, filling in every section of the pull request template, including the summary a human writes in their own words.
Skill-behavior tests use the drill eval harness from [superpowers-evals](https://github.com/prime-radiant-inc/superpowers-evals/), cloned into `evals/` — see `evals/README.md` for setup. Plugin-infrastructure tests live at `tests/` and run via the relevant `run-*.sh` or `npm test`.
diff --git a/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md
index 3e7d238..e593ae3 100644
--- a/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md
+++ b/docs/superpowers/specs/2026-08-27-diagnosing-superpowers-design.md
@@ -253,18 +253,20 @@ user asks.
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
+3. **If nothing matches**, draft an issue from `templates/issue.md`: who
+ is filing and what the user asked for, a summary in the user's own
+ words, 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 and the summary holds their words, 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
+ `bug_report.md` template, which applies the `bug` label for any
reporter; GitHub caps that URL near 8,000 characters.
4. Nothing is posted anywhere without the user approving the exact text.
diff --git a/skills/diagnosing-superpowers/SKILL.md b/skills/diagnosing-superpowers/SKILL.md
index f1d479f..dda2692 100644
--- a/skills/diagnosing-superpowers/SKILL.md
+++ b/skills/diagnosing-superpowers/SKILL.md
@@ -100,7 +100,7 @@ yourself in step 3 and which findings to lead with in the verdict.
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.
+ text, and none with a placeholder summary.
- **Intake before analysis.** Nothing in steps 2–7 starts until your
partner has answered. If they are away, write the questions and stop.
A statement you reconstructed for them is not an answer. An
diff --git a/skills/diagnosing-superpowers/references/github-issues.md b/skills/diagnosing-superpowers/references/github-issues.md
index e9a27a1..de787f7 100644
--- a/skills/diagnosing-superpowers/references/github-issues.md
+++ b/skills/diagnosing-superpowers/references/github-issues.md
@@ -36,11 +36,11 @@ 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:
+Without `gh`, hand over a prefilled link on the `bug_report.md` template,
+which applies the `bug` label for any reporter:
```
-https://github.com/obra/superpowers/issues/new?template=diagnosis_report.md&title=<url-encoded title>&body=<url-encoded body>
+https://github.com/obra/superpowers/issues/new?template=bug_report.md&title=<url-encoded title>&body=<url-encoded body>
```
GitHub rejects URLs over about 8,000 characters; past that, send the link
diff --git a/skills/diagnosing-superpowers/templates/issue.md b/skills/diagnosing-superpowers/templates/issue.md
index d76c0c8..dec8cfc 100644
--- a/skills/diagnosing-superpowers/templates/issue.md
+++ b/skills/diagnosing-superpowers/templates/issue.md
@@ -2,6 +2,20 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
- [x] I searched existing issues and this is not a duplicate (searched: <query terms>; closest: <#n title, or "none">)
+## Who's filing this report? (required)
+
+<model and harness of this session>, filing on behalf of <how your
+partner wants to be named, or "my human partner">, who asked: "<their
+request from this session that led to the diagnosis or the issue,
+scrubbed>"
+
+## Human-authored summary (required, under 200 words)
+
+<Your partner's own words on what went wrong and what should have
+happened, pasted as written. Ask for them; a placeholder here means the
+issue is not ready to file. If they run long, ask them to trim rather
+than editing their words.>
+
## Environment (required)
| Field | Value | Provenance / supporting evidence |
@@ -17,8 +31,12 @@ Title: <skill or symptom>: <one-line observable> (<harness>)
- [ ] 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.
+How I verified that this issue does not reproduce without Superpowers:
+<"Not tried", or what your partner ran without superpowers and what
+happened, with the transcript path if there is one. Tick the box above
+only when a transcript shows the problem did not recur.>
+
+Evidence for involvement is below; it does not establish cause.
## What happened?
@@ -47,5 +65,6 @@ 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.
+Filed with the `diagnosing-superpowers` skill. The filing model and
+harness are under "Who's filing"; the diagnosed session's model, harness,
+versions, and plugins are in the Environment table.