Frame A Proposal

Frame a proposal — turn a problem into a reviewable RFC

The platform /open-knowledge skill still governs every markdown operation here (reads via exec/search, writes via write/edit, links as plain relative markdown, never native Read/Edit/Grep/cat on in-scope files). This skill layers proposal-authoring craft on top: it decides what a good proposal contains and in what order you earn each section.

A proposal in proposals/ is a design argument, not a decision and not a plan. It exists to force a choice among options and to give reviewers enough to disagree with. Filename is 0001-feature-name.md — a zero-padded 4-digit sequence plus a kebab title. Status flows draft → fcp → accepted/rejected (fcp = final comment period). Acceptance graduates the proposal to a record in decisions/ — that is a separate, human act and a separate skill.

The failure this skill exists to prevent: an agent jumping to ## Design before anyone agrees what the problem is, padding ## Alternatives with strawmen, and leaving ## Drawbacks empty. Each step below has a gate that blocks that.

Mandatory execution order

Hard gates — do NOT skip ahead. If you are about to draft ## Design and you have not passed the Step 1 framing gate, STOP — you skipped a gate. The whole point of a proposal is that the problem is agreed before the solution is written.

0. Scan prior art — what already exists on this subsystem, in proposals/ and decisions/.
1. Frame the problem — STOP gate. Name beneficiary, observable change, forced decision. Get confirmation before any solution text.
2. Allocate the sequence number and create from the proposal template.
3. Motivation — problem, evidence, who is hurt today, cost of doing nothing, and explicit non-goals.
4. Design — the proposal at an altitude a reader can disagree with.
5. Alternatives — at least two real ones, each with why-not.
6. Drawbacks — the honest cost.
7. Unresolved questions — a live backlog, each with a resolver and resolving evidence.
8. Link + validate.
9. Recap + what advancing to fcp would require.

Create workflow tasks for steps 0–9 in your host's task system if it has one — they make a skipped gate visible mid-session.

Step 0: Scan prior art

Before framing anything, find out what the knowledge base already decided or proposed about this subsystem. A proposal that silently re-litigates an accepted decision is dead on arrival; a proposal that cites it and explains why the decision should be revisited is legitimate.

• search({ query: "<subsystem or problem keywords>" }) — semantic, catches synonyms.
• exec("ls -A proposals/") and exec("ls -A decisions/") — see the sequence space and what has landed.
• exec("grep -rln <keyword> proposals/ decisions/") — pinpoint files that name the same subsystem.
• For the 1–3 most relevant hits, exec("cat proposals/0003-x.md") to read the full doc plus its backlinks.

Classify what you find, and carry it into the draft:

Step 1: Frame the problem — STOP gate

This is the gate that makes the difference between an RFC and a pile of solution text. Do NOT draft ## Design, and do NOT create the file, until the user confirms the framing.

Produce and return exactly this, then STOP and wait:

## Framing (confirm before I draft)

**Beneficiary:** who is worse off today and will be better off if this ships. A named role or user, not "the system" or "us".

**Observable change:** the concrete, checkable difference they will see. "X drops from N to M", "Y becomes possible", "Z stops happening". Not "improve", not "streamline".

**Forced decision:** the one question this proposal makes reviewers answer. If accepting it doesn't commit anyone to anything, it is a report, not a proposal.

**Rough shape:** one sentence on the direction — enough to know we're framing the right problem, not the design itself.

Discipline:

• If you cannot name a beneficiary distinct from "the team," the problem isn't framed. Push back before drafting.
• "Observable change" is falsifiable or it isn't done. If you can't state how you'd check it, you're describing an activity, not an outcome.
• Vague trigger ("we should have a proposal for the cache")? Narrow it: for whom, forced by what decision, changing what they observe.
• In an explicitly headless/non-interactive run, state the framing AND proceed, but write the three fields verbatim into Motivation so a reviewer can reject the framing itself.

Step 2: Allocate the number and create from template

List, don't guess, the sequence. exec("ls -A proposals/"), take the highest existing NNNN, add one, zero-pad to four digits. Guessing collides the moment two proposals are drafted the same week.

Filename: NNNN-kebab-title.md (0007-async-export-pipeline.md). Create it from the template — this is the only way the ## Motivation → ## Design → ## Drawbacks → ## Alternatives → ## Unresolved questions skeleton and the frontmatter arrive correctly:

write({ document: { path: "proposals/0007-async-export-pipeline.md", template: "proposal" } })

The template stamps this frontmatter — fill it, don't retype it by hand:

type: proposal
description: "..."     # one line: the forced decision, not the feature name
status: draft          # stays draft until a human advances it — see Non-goals
authors: [<user>]
created: YYYY-MM-DD
tags: [proposal]

Set description to the decision the proposal forces, in one line — it is what a reader sees in a listing.

Step 3: Motivation

Fill ## Motivation by edit-ing the created doc. This section has to stand on its own: a reader who disagrees here will never read your Design, and that's correct.

• The problem, stated as the beneficiary experiences it — not as the absence of your solution. "Exports over 100MB time out and users lose the job" beats "we have no async export pipeline."
• Evidence it is real: a metric, a repeated report, a concrete incident. A proposal motivated only by "it would be nice" is under-motivated; say so to the user and go find one signal.
• Who is hurt today, named (the Step 1 beneficiary), and how often.
• Cost of doing nothing — the status-quo baseline every alternative, including "reject this," is measured against. If doing nothing is genuinely fine, the proposal may not need to exist.
• Non-goals — explicitly. List what this proposal deliberately does not address. Non-goals are how you keep a proposal reviewable; an unbounded proposal can't be accepted because no one can tell what they're agreeing to. Put them under a clear ### Non-goals line inside Motivation.

Step 4: Design

Fill ## Design with the actual proposal, pitched at the altitude where a reader could disagree with it. Too low (every function signature) and reviewers rubber-stamp a design they didn't evaluate; too high ("we'll make it faster") and there's nothing to accept. The target: a competent reader could read this section and say "no, I'd do it differently, because…"

• Describe the mechanism, the shape of the change, and the key interfaces or contracts it introduces or alters.
• Make the load-bearing choices explicit. If the design rests on one decision (a data model, a boundary, a sequencing), name it — that decision is usually what the whole proposal is really about.
• State how the Step 1 observable change is achieved. Tie the design back to the beneficiary.
• Link related specs, guides, and the decisions you're building on or revisiting, as plain relative markdown: [the export boundary decision](./decisions/0004-export-boundary.md).
• Keep implementation minutiae out — that granularity is the spec's job (a sibling skill), not the proposal's.