Skip to main content

Proposals — how they work

This page explains the methodology behind the proposals tier — when to write one, how the lifecycle moves, what each status means, and how triage runs.

For the live list of proposals (active, done, promoted, archived), see the proposals index.

When to write a proposal​

Write a proposal when:

  • You see an opportunity to improve infra, features, process, or tooling.
  • The work is roughly side-project sized (S / M — under three days).
  • You want a durable place for the idea so it doesn't die in a Slack thread or one person's head.

For small, contained changes that take an hour or two — just open a PR with no proposal. For multi-team, week-plus, contract-changing work — write an RFC instead.

Lifecycle​

  raw idea
     │
     │  /propose  (or copy the template manually)
     ▼
┌──────────────┐
│     open     │ ← default: no owner yet, surfaced for triage
│              │   (set claim during /propose if you want to drive)
└──────┬───────┘
       │ ── or ──> ┌──────────────┐
       │           │   claimed    │ ← author claimed it on creation
       │           └──────┬───────┘
       │                  │
       │                  ▼
       │  triage (manual cadence — no automation,
       │   look at the index when you're ready)
       ▼
┌──────────────┐
│   triaged    │  conflicts / duplicates resolved, ClickUp task opened
└──────┬───────┘
       │
       ▼
┌──────────────┐
│ in-progress  │ → ┌──────┐    ┌──────────┐    ┌──────────┐
│              │   │ done │    │ promoted │    │ archived │
└──────────────┘   └──────┘    │  → RFC   │    │  + why   │
                               │  / spec  │    │          │
                               └──────────┘    └──────────┘

Status meaning​

StatusWhat it meansWho sets
openIdea exists, no one's claimed implementation yet. Default for new proposals.Author on creation (owner: null)
claimedAuthor wants to drive it. Set when the author explicitly claims on creation.Author on creation
triagedReviewed in triage. Duplicates merged, ClickUp task opened.Triage
in-progressOwner is actively working on it.Owner
doneShipped. Linked to the PR / release.Owner
promotedOutgrew the proposal tier — moved to an RFC or PRD.Triage or owner
archivedWon't do. Rationale documented in the file.Triage

Triage cadence — manual​

No cron, no automated reminders. Look at the index when you're ready — usually monthly in a one-hour session, sometimes async via PR comments on the file. The job of triage:

  1. Surface clusters — proposals on overlapping topics that should be merged, sequenced, or split deliberately.
  2. Match open proposals to volunteers — assign an owner if someone wants it.
  3. Validate claimed proposals — confirm the author still has bandwidth and the scope still fits.
  4. Promote or archive anything that doesn't fit the proposal tier anymore.

Difference from RFCs​

RFCs require a 7-day comment window, multi-team review, and tend to land architecture-level changes.

Proposals are lighter — write one alone, get it triaged when convenient, ship it as a side project.

If a proposal grows during discussion (scope creep, contract changes, multi-team involvement), promote it to an RFC and link back via graduated_to:.

See also​