Skip to content

An agentic skills framework & software development methodology that works.

Templates: require a human-written summary and the filer's instructions (#2570)

Jesse Vincentb739a8af570e
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index 01bb80e2e..d626261f5 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 13f7b4924..000000000
--- 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 c7a4de120..39253b35b 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 31faa68b9..6dcbde9c2 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 2ec951316..13c5aac9b 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 9587a6836..2828661a9 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 e40ddfa8f..c5bb59fda 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 3e7d23801..e593ae3ab 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 f1d479fbc..dda2692d5 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 e9a27a16a..de787f7b7 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 d76c0c88a..dec8cfc25 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.