Skip to main content

Proposal Template

Copy into docs/proposals/proposal-YYYY-MM-DD-short-slug.md. A proposal is lighter than an RFC — no comment period, no formal review window, no architecture deep-dive. It's the durable record of an idea so it doesn't die in one developer's head.

Use a proposal when:

  • The change is in scope for one engineer as a side project (S / M effort)
  • You want to capture an idea before it's fully shaped
  • You may or may not drive it yourself — both are fine

If the idea grows into multi-team / multi-week work, graduate it to an RFC and link back.

---
id: proposal-YYYY-MM-DD-short-slug
title: "Short title"
description: "One-sentence summary that shows in the index"

# Lifecycle — see /proposals for the full status table
status: claimed          # claimed (default — author owns) | open (no owner, looking for one) | triaged | in-progress | done | promoted | archived
author: "@your-handle"
owner: "@your-handle"    # default = author. Set to null to mean "I propose, won't drive."
created: YYYY-MM-DD
triaged: null            # YYYY-MM-DD once reviewed in triage
category: infrastructure # infrastructure | feature | process | tooling | other
effort: S                # S (<1d) | M (1-3d) | L (>3d, consider RFC instead)

# Cross-links — fill in what's relevant
related: []              # ['proposal-...', 'rfc-...'] — peer proposals, related RFCs
clickup_id: null         # set after triage if a ClickUp task is opened
graduated_to: null       # set to RFC/spec id if status: promoted

tags: []
---

# Short Title

<div style={{display:'flex',gap:'0.5rem',marginBottom:'1.5rem'}}>
  <span className="badge badge--primary">Claimed</span>
  <span className="badge badge--secondary">Author: @handle</span>
  <span className="badge badge--secondary">Owner: @handle</span>
  <span className="badge badge--secondary">Effort: S</span>
</div>

## Problem

What's the pain or opportunity? Keep it concrete — a specific scenario, an incident, a complaint, a missed metric. Avoid "it would be nice if..." — that's a wish, not a problem.

## Proposal

One or two paragraphs. The idea, not the design. No architecture diagrams unless they fit on one screen.

## Why now / Why us

Why is this worth doing **now**, and why are **we** the ones to do it (vs. punting to a vendor / waiting / accepting the status quo)?

## Sketch of approach

Bullet points. Enough that the next person reading this can picture the work — not enough to count as a design.

- Component A: change X
- Component B: add Y
- One open call: do we touch Z or leave it?

## Open questions

- Q1?
- Q2?

## Related

- Links to specs, RFCs, ClickUp tickets, prior conversations.

---

## Triage notes

*Filled in during triage. Empty until then.*

**Reviewed:** YYYY-MM-DD
**Decision:** Approved as proposal / Merged with [proposal-...] / Promoted to [rfc-...] / Archived (rationale below)
**Owner:** @handle (if changed from the author)
**ClickUp:** [CU-XXX](https://app.clickup.com/t/XXX)