| name | community-proposal |
| description | Use this skill when contributing a design proposal to an open-source community — research, draft with evidence, file. |
Community Proposal
When to use
When you have a design decision or architectural insight and want to contribute it upstream — as a GitHub issue, RFC, or discussion post — with evidence, community context, and counterarguments addressed.
Steps
1. Identify the primary venue
Pick the repo where the standard is actively being defined, not where it is discussed in aggregate. Filing in a spec repo is more impactful than filing in a community forum or issue tracker that explicitly defers decisions elsewhere.
Signal for the right venue: maintainers there are empowered to merge normative spec changes based on the issue.
2. Research existing discussions
Search the target repo and related community repos for prior issues, PRs, and threads on the same topic. For each find, record:
- Issue/PR number and URL
- Author handle (for
@mention later)
- The core claim or proposal
- Current status (open, closed, merged, stalled)
- Whether it agrees with, partially overlaps with, or contradicts your proposal
Aim for 3–5 direct prior-art references. Stop when additional searches return nothing new.
3. Categorize positions
Separate what you found into two groups:
Agreements — issues/comments that independently converge on the same conclusion or identify the same problem. These are your supporting evidence; cite them directly.
Counterarguments — objections, alternative proposals, or explicit disagreements. Do not ignore them. For each, determine whether it is:
- Fully addressed by your proposal (state how)
- Partially addressed (acknowledge the gap)
- Out of scope (say so without dismissing it)
4. Write a research document
If the repo has a docs/research/ convention, save findings there before drafting the post. This separates durable evidence from the ephemeral issue body.
Use the format: YYYY-MM-<topic>.md. Include sources, community position table, and open questions.
5. Draft the post
Structure:
- Opening (2–3 sentences) — acknowledge what the project already got right before stating the problem. Establishes credibility and good faith.
- Ideas (not "Positions" or "Demands") — one section per idea, each with a concrete example (code, table, or quote).
- What I'd love to see clarified — a numbered list of specific, actionable asks. Use "Clarify" or "Recommend", not "Must" or "Require".
- Prior art and community support — bullet list, one per reference, with
@handle for authors.
- Anticipated pushback — and my take — address each known objection directly. Acknowledge before countering.
- Closing (2 sentences) — offer to contribute spec language; end with an open question to invite dialogue.
6. Calibrate the tone
Apply throughout the post:
| Area | Do | Avoid |
|---|
| General register | Casual, collegial — "feels like", "I think", "Sharing in case it's useful" | Formal position papers, "I propose that the spec shall" |
| Technical positions | Firm and specific — blockquotes, tables, concrete JSON examples | Hedging technical claims with "maybe" or "possibly" |
| Objection responses | Open with acknowledgment — "Fair concern." / "Agreed —" before the counter | Terse or dismissive rebuttals |
| Voice | First-person singular — "I", "I'm already shipping…" | "We" unless writing on behalf of a named team |
| Author handles | @username on all referenced authors so GitHub notifies them | Bare usernames that don't trigger notifications |
| Closing | End with a question that opens dialogue | Ending on a demand or deadline |
7. Final review before filing
Check:
8. File
gh issue create \
--repo <org>/<repo> \
--title "<title>" \
--body "$(cat <<'BODY'
<post body>
BODY
)"
Capture the URL from stdout and update the research document with a link to the live issue.
Anti-patterns
- Filing in the discussion forum instead of the spec repo — gets acknowledged but never acted on.
- Listing objections without addressing them — makes the proposal look incomplete; maintainers will raise them in comments anyway.
- "Position 1 / Position 2" headings — sounds like a formal debate brief; use "Idea 1 / Idea 2" instead.
- Ending with demands — "the spec MUST add this" closes the conversation; "I'd love to see this clarified" opens it.
- Skipping the prior art section — wastes maintainer time and signals you haven't read the existing discussions.
- Cross-posting to multiple venues simultaneously — pick the primary venue; cross-reference from secondary venues after the primary issue is live.
References
governance show skill-design — skill authoring rulesgovernance show skill-repo-structure — repo layout for saving research docs
