Bring a clear idea.

A proposal people can read.

Aim for roughly one readable page. That’s an editing target, not a reason to hide an important risk. Use the questions below and leave out sections that genuinely don’t apply.

# [A title that describes the change]

## What gets better?
Who has this problem? What happens today, and what should happen instead?

## Show the idea
Describe the proposed experience with a concrete example.
For interface changes, include an annotated mockup or short recording.

## What are you proposing to build?
State what this contribution includes and what it leaves for later.
Mention the existing components or services it would extend.

## What could go wrong?
Identify meaningful privacy, security, compatibility, data-loss, or cost risks.
Explain recovery where relevant.

## How will we know it works?
Give a few observable acceptance criteria and how you will test them.

## What needs a decision?
Ask the specific questions that prevent work from beginning.
If none, say what approach you want reviewed.

For interfaces, show the interaction.

An annotated screenshot, ASCII sketch, HTML prototype, or short recording is welcome. Show the starting point, the important action, and the result. Include the error, loading, narrow-screen, keyboard, or accessibility states that matter to the change. For a spacing fix, a before-and-after image is enough. For a mini-app, show a human and Genie working on the same thing and handing control back and forth.

Give consequential changes the detail they deserve.

Encryption, payments, deployment drivers, migrations, and other high-impact changes need a linked technical design when the short proposal can’t carry the reasoning. Cover authority, data flow, compatibility, failure, recovery, and tests. Keep the readable proposal at the front. Use a draft spec PR when line-by-line discussion is useful.

AI can help. You own the contribution.

AI-assisted contributions are welcome. Submit work you understand and can explain. Lead with the problem, the proposed change, and evidence that it works. Leave out chat transcripts, internal planning notes, repeated summaries, and generated files that aren’t needed to review the change. If an agent helped write the proposal, edit it before asking someone else to read it.

Agree on the approach. Then build.

For substantial work, get agreement before building the whole thing. Product and design direction stay coherent; contributors help make them better. Keep decisions, mockups, and tests in the same conversation. If your approach changes, say so there. A small correction does not need an issue, a spec, and a presentation.

Keep vulnerability reports private.

Do not put suspected vulnerabilities, exploit details, credentials, or private data in a public issue or PR. Arrange private coordination with a maintainer before sharing sensitive evidence. Test only systems you own or have explicit permission to assess.