/frame-a-proposal

name: frame-a-proposal
description: "Frame a new design proposal (RFC-shape) under proposals/ — problem before solution, named beneficiary and observable change, real alternatives, honest drawbacks, and a live open-questions backlog. Read when asked to frame a proposal, write an RFC, propose a design, pitch a change, draft a PRD-style design doc, or open a design proposal for review. Do NOT read to record a decision after it is accepted (use record-a-decision), to write an implementation spec (use write-a-spec), to write a postmortem (use write-a-postmortem), or to review or critique an existing design (use review-a-design)."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by `ok seed --pack software-lifecycle` (`ok-beta` for Beta)."
metadata:
  pack: "software-lifecycle"
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"

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,