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:

| Found | Do this |
|---|---|
| An **accepted decision** covers this area | The new proposal MUST cite it (a markdown link into `decisions/`) and, in Motivation, say what changed that reopens it. If nothing changed, tell the user this may not need a proposal at all. |
| A **draft/fcp proposal** overlaps | Offer to extend or supersede it rather than open a near-duplicate. Two overlapping proposals split the review. |
| **Nothing** | Proceed clean. |

---

## 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:

```yaml
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 — i