Come with a
clear idea.

A proposal a person can read.

Aim for about one page. That's an editing target, not an excuse to hide a real risk. Answer the prompts below and drop the sections that genuinely don't apply.

# [A title that names the change]

## What gets better?
Who runs into this today? What happens now, and what should happen instead?

## Show the idea
Walk through the proposed experience with one concrete example.
For interface work, attach an annotated mockup or a short recording.

## What will you build?
Say what this contribution covers and what it deliberately leaves for later.
Name the existing components or services it extends.

## What could go wrong?
List real privacy, security, compatibility, data-loss or cost risks.
Describe recovery where it matters.

## How will we know it works?
A few observable acceptance checks, and how you will test them.

## What needs a decision?
The specific questions blocking the work. If none, say which approach you want reviewed.

For interfaces, show the interaction.

Annotated screenshots, an ASCII sketch, a rough HTML prototype or a short screen recording all work. Show where the person starts, the key action and the result. Include error, loading, narrow-screen, keyboard and accessibility states when they matter. For a spacing fix, a before-and-after pair is plenty. For a mini-app, show a person and a Familiar working on the same thing and passing control back and forth.

Give high-impact changes the detail they need.

Encryption, payments, deployment drivers, migrations and other consequential work 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 up front, and open a draft spec PR when line-by-line review helps.

AI can help. You own the contribution.

Agent-assisted work is welcome, as long as you understand it and can explain it. Lead with the problem, the change and the evidence. Leave out chat logs, planning scratch, repeated summaries and generated files a reviewer doesn't need. If an agent drafted your 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, so product and design direction stay coherent. Keep decisions, mockups and tests in one conversation, and say so there if your approach changes. A small correction doesn't need an issue, a spec and a slide deck.

Keep vulnerability reports private.

Never put suspected vulnerabilities, exploit details, credentials or private data in a public issue or pull request. Arrange private coordination with a maintainer before sharing anything sensitive, and only test systems you own or have written permission to assess.