refactor(github): redesign templates for prose-first contributions#1522
Merged
refactor(github): redesign templates for prose-first contributions#1522
Conversation
The old template was 53 lines of checkbox theater—contributors ticked boxes mechanically without thinking. The git skill mandates prose over checkboxes, WHAT+WHY openings, and no file listings. Removed: Summary header, Changes Made section, Testing checklists (desktop + general), entire Checklist section (all 8 items were either linter-enforceable or unverifiable), Screenshots header, Additional Notes section. Kept: Changelog (feeds auto.release.yml), Closes # line, CODEOWNERS note (as blockquote), screenshots guidance (as inline HTML comment).
The "I have included all relevant information above" checkbox adds no
value—everyone checks it mechanically. The dedup checkbox ("I have
searched existing issues") is the only one that prompts real action.
Problem and Use case overlapped heavily—people described the same scenario in both. Additional details was almost always left blank. Merged into "Problem / use case" and kept "Proposed solution" as the one section that actually makes people think about implementation.
braden-w
force-pushed
the
opencode/prose-first-templates
branch
from
33675bf to
57b56df
Compare
Scrubbed all specific valuations ($9B, $100M, $1B+, $96k/year, $10/month, $100k/year), ARR figures, and "revenue"/"high-ticket"/"margin" language. Company names stay as references. "Revenue streams" becomes "How this sustains the project." The framing is financial sustainability, not a pitch deck.
Codifies that we say "financial sustainability" not "revenue" or "making money," never cite dollar-figure valuations for comps, and frame commercial licensing as funding open-source development.
braden-w
force-pushed
the
opencode/prose-first-templates
branch
from
57b56df to
82a2180
Compare
The changelog rules appeared twice—once under Commit Messages (lines 107–134) and again under PR Guidelines (lines 439–464). Identical content. Removed the second occurrence to save ~25 lines of context that was pure token waste per the ETH Zurich finding that unnecessary instructions increase reasoning tokens 14–22%.
Six diagram-type subsections (journey, layer, comparison, flow, composition tree, file relocation) plus a 50-line prose/visual rhythm tutorial taught the AI things it already knows. Research (Crosley, 2,500+ repos) shows instructions without verification commands are suggestions that get ignored or followed mechanically. Replaced 200+ lines of diagram tutorials with 8 lines of operational guidance: when to use diagrams, which characters to use, and the alternating prose/visual principle.
…definition of done The numbered 9-section format (opening → why → bullets → API migration → storage → technical → why-X → future → test plan) was a rigid template that contradicts prose-first writing. ETH Zurich research shows "instructions ARE followed, that's the problem"—rigid templates produce formulaic output. Replaced with concise principles the agent can apply with judgment. Added a Definition of Done checklist (Crosley's highest-impact pattern from 2,500+ repo analysis) so the agent knows when a PR description is complete without following a rigid format.
…command-first Research (Crosley) shows command-first instructions are the only pattern that reliably changes agent behavior. Both sections had useful gh commands buried in explanatory prose—extracted the commands and compressed the surrounding text. GitHub issues scanning: 22 lines → 10 (kept commands + reference format). Username verification: 12 lines → 3 (kept the command, cut the lecture).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rewrites the PR template, trims issue templates, and cuts the git skill from 631 to 357 lines. The same principle runs through all of it: contribution guidelines should produce prose, not checkbox theater.
Research backs this up. ETH Zurich's "Evaluating AGENTS.md" (2025) found that unnecessary instructions in agent skill files increase reasoning tokens 14–22% without improving output quality. Blake Crosley's analysis of 2,500+ repos found that instructions without verification commands are suggestions the agent ignores or follows mechanically. The git skill had both problems.
PR template (53 → 25 lines)
The git skill is explicit: "avoid bullet points or structured lists as a substitute for explanatory prose," never enumerate files changed, and "tests should be in the code, not described in prose." The old template violated all three.
Every checklist item failed the "does this need human judgment a checkbox can capture?" test:
typeoverinterface→ linter-enforceableGit skill (631 → 357 lines)
Four targeted cuts, each grounded in community best practices for agent instruction files:
Duplicate changelog section removed. The changelog rules appeared identically in both the Commit Messages and PR Guidelines sections. Pure token waste.
ASCII art catalog collapsed (206 → 4 lines). Six diagram-type tutorials (journey, layer, comparison, flow, composition tree, file relocation) taught the agent how to draw boxes it already knows how to draw. Replaced with one operational line: when to use diagrams, which characters to use. The agent uses judgment about which diagram type fits.
9-point architectural PR format replaced with principles + definition of done. The numbered template (opening → why → bullets → API migration → storage → technical → why-X → future → test plan) was a rigid format that produces formulaic output. Replaced with concise principles and a "Definition of Done" checklist—Crosley's highest-impact pattern—so the agent knows when a PR description is complete without following a rigid section order.
Operational sections compressed to command-first. GitHub issues scanning (22 → 10 lines) and username verification (12 → 3 lines) had useful
ghcommands buried in explanatory prose. Extracted the commands, cut the lectures.Issue templates (surgical)
Bug report: Removed the "I have included all relevant information above" checkbox. Everyone checks it without reading. The dedup checkbox stays—it prompts real action.
Feature request:
### Problem:and### Use case:overlapped heavily.### Additional details:was almost always left blank. Merged into### Problem / use case:.Financial language
Removed all dollar-figure valuations from FINANCIAL_SUSTAINABILITY.md and retitled it from "How to Monetize Epicenter" to "How We Fund Open-Source Development." The filename stays—
FINANCIAL_SUSTAINABILITY.mdis provocative enough to earn clicks in a repo root—but the title reframes the conversation around mission, not revenue. Company names (Grafana, Bitwarden, MinIO) stay as references; their valuations don't. The writing-voice skill now codifies this: say "financial sustainability," never cite valuations, frame commercial licensing as funding open-source development.