Skip to main content
skill CX Codex

frame-a-proposal — Claude Code skill: what it does, install

The frame-a-proposal skill shapes a design request into a reviewable RFC, starting with the problem and beneficiary before moving to options, trade-offs, and open questions.

MIT 248 installs ★ 17 updated 2026-10-21

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add inkeep/open-knowledge-skills --skill frame-a-proposal -a claude-code
Open on GitHub

What frame-a-proposal does

frame-a-proposal guides an agent through a new design proposal under proposals/. It asks for a named beneficiary, a checkable change, and the decision reviewers must make. The agent must confirm that framing before drafting the Design section or creating the file.

The workflow starts by scanning existing proposals and decisions, then takes the next sequence number and creates a document from the proposal template. The resulting structure covers motivation, design, genuine alternatives, drawbacks, unresolved questions, links, and validation. Proposal files use names such as 0001-feature-name.md, with status moving from draft to fcp and then to accepted/rejected.

The workflow requires a configured OpenKnowledge MCP server. Without it, the read and write operations used by this skill cannot run.

What it helps with

  • frame the problem before drafting a solution
  • identify a beneficiary and observable outcome
  • compare real design alternatives
  • record honest drawbacks for reviewers
  • create a proposal under proposals/ from a template

Example prompts for the agent

  • Frame a new design proposal for this change, name the beneficiary and observable outcome, then stop for confirmation before Design.
  • Scan prior proposals/ and decisions/, allocate the next filename, and draft an RFC for review.
  • Create a proposal under proposals/ with real alternatives, drawbacks, and a live list of unresolved questions.

How to install frame-a-proposal

1Skills CLI (Vercel)

npx skills add inkeep/open-knowledge-skills --skill frame-a-proposal -a claude-code

2Manually: put the files in place

~/.claude/skills/frame-a-proposal/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/frame-a-proposal/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about frame-a-proposal

How do I install frame-a-proposal in Claude Code?

Run npx skills add inkeep/open-knowledge-skills --skill frame-a-proposal -a claude-code, then check ~/.claude/skills/frame-a-proposal/SKILL.md.

What does frame-a-proposal do?

It guides an agent through writing a new RFC-style design proposal. The process starts with the problem and beneficiary, then covers the design, alternatives, drawbacks, and unresolved questions.

What does frame-a-proposal need to run?

The workflow requires a configured OpenKnowledge MCP server. The skill relies on it for knowledge-base file operations.

Source text

SKILL.md · MIT
---
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, 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 — 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.

---

## Step 5: Alternatives

Fill `## Alternatives` with **at least two real options**, each carrying **why it was not chosen**. Include the honest ones you'd have picked on a different day, plus "do nothing" if it's live.

Structure each:

```
### Alternative: <name>
What it is — one honest paragraph, argued at its best.
Why not — the specific tradeoff that lost, versus the proposed design.
```

Discipline:

- **Strawmen are a red flag — say so.** An Alternatives section where every option is obviously worse means the author didn't consider real ones, and reviewers will (correctly) distrust the whole proposal. If you can't state an alternative's genuine appeal, you haven't understood it well enough to reject it.
- "Do nothing" is a first-class alternative. Its "why not" is the Step 3 cost-of-doing-nothing.
- The right number is usually two to four. One means you're not proposing, you're announcing.

---

## Step 6: Drawbacks

Fill `## Drawbacks` with the honest cost of the proposed design — not the alternatives', its own.

- **A proposal with no drawbacks is under-examined, not perfect.** Every real design gives something up: complexity, a migration, a new failure mode, a maintenance burden, a closed door. Name them.
- Be specific about who pays and when — the cost may land on a different party than the beneficiary, and reviewers need to see that tradeoff.
- If you genuinely believe a drawback is acceptable, say why here rather than hiding it. A stated-and-accepted drawback is stronger than a silent one a reviewer discovers.

---

## Step 7: Unresolved questions

Fill `## Unresolved questions` as a **live backlog**, not a disclaimer. Each entry keeps a real open question visible instead of burying it in confident prose.

For each question:

```
- **<question>** — What would resolve it: <the evidence, experiment, or measurement>. Who decides: <role or person>.
```

- Every question names **what evidence would resolve it** and **who decides**. A question with neither is just an anxiety; either sharpen it or drop it.
- Questions that block acceptance belong here explicitly — they are the agenda for the `fcp` period.
- It is correct for this section to be non-empty at `draft`. Hiding uncertainty to look finished is the failure mode; an honest open-questions list is what makes the proposal safe to review.

---

## Step 8: Link + validate

Run before you tell the user it's ready:

- Every referenced decision, spec, or guide is a plain markdown relative link (`[text](./decisions/0004-x.md)`), never backticked, never an HTML anchor.
- Add backlinks from 1–2 closely related docs so the proposal is discoverable — the accepted decision it revisits, a related spec, the relevant guide. `links({ kind: "backlinks", ... })` to see what already points where.
- `audit({ path: "proposals/0007-async-export-pipeline.md" })` returns clean (every lint violation + broken internal link) — fix every finding.
- Frontmatter complete: `type: proposal`, a one-line `description`, `status: draft`, `authors`, `created`, `tags: [proposal]`.
- All five H2 sections present and non-empty: `## Motivation`, `## Design`, `## Drawbacks`, `## Alternatives`, `## Unresolved questions`. An empty Drawbacks or a strawman Alternatives fails this check even though the section technically exists.
- `status` is still `draft`. You do not advance it — see Non-goals.

---

## Step 9: Recap + path to fcp

Close with the user in conversation:

```
## Recap

- Framed: <beneficiary> gets <observable change>; forces the decision <…>.
- Proposal: proposals/NNNN-title.md (status: draft)
- Alternatives weighed: <n>, chosen over them because <one line>.
- Honest drawbacks: <the main one>.
- Open questions still live: <count> — the fcp agenda.

**To advance to `fcp`:** a human moves status draft → fcp and opens the final comment
period. Acceptance (→ accepted, then a record in decisions/) is a human decision, not
mine. If it's rejected, mark status: rejected and keep the doc — the reasoning is the value.
```

State plainly that advancing status and accepting the proposal are human acts. Your job ended at a well-framed, honestly-argued `draft`.

---

## Non-goals

- **Don't record the decision.** Acceptance graduates a proposal to a record in `decisions/` — that's the sibling `/record-a-decision` skill, run *after* a human accepts. This skill stops at `draft`.
- **Don't write the implementation spec.** Design altitude, not build detail. The spec is `/write-a-spec`.
- **Don't mark a proposal `accepted` (or `fcp`) on your own authority.** Advancing status is a human act. Leave `status: draft`; offer the recap of what advancing would require.
- **Don't skip the Step 1 framing gate.** Solution text before an agreed problem is the exact failure this skill exists to prevent. If you've drafted Design without a confirmed beneficiary and forced decision, you skipped the gate — back up.
- **Don't pad Alternatives with strawmen or leave Drawbacks empty.** Both are tells that the proposal wasn't really examined. Reviewers read them as such.

© Inkeep · MIT · inkeep/open-knowledge-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set17

The whole set →
consolidate-notes consolidate-notes turns a decision your team already made plus its draft research into one canonical article. Useful once the arguing is over and the source of truth needs writing down. CX Codex +1 862installs codebase-wiki codebase-wiki — a skill for Claude Code, Codex, Cursor, GitHub Copilot, and Gemini CLI that instructs the agent to build and maintain a source-grounded wiki inside the repository. CX Codex +1 461installs review-a-design review-a-design critiques technical proposals, specs, and ADRs for architectural soundness without editing the text. It flags flaws in goals, constraints, and alternatives. CX Codex +1 252installs record-a-decision The record-a-decision skill turns a settled architecture choice into an ADR with its context, alternatives, and consequences. Use it to keep decision history readable. CX Codex +1 252installs write-a-spec write-a-spec turns an accepted proposal into an implementation spec with current-system mapping, decision records, open questions, migration work, and tests. CX Codex +1 247installs software-lifecycle software-lifecycle gives a project a fixed shape for its docs: proposals, decisions, specs, postmortems and guides. The skill carries the status flows and per-folder rules. CX Codex +1 245installs write-a-postmortem write-a-postmortem drafts blameless incident reviews in postmortems/ using the Google SRE framework. Focuses on system affordances and evidence instead of personal fault. CX Codex +1 243installs note-taking note-taking guides agents working in a plain notes setup with notes/ and daily/ folders. Helps capture ideas quickly and connect pages with cross-links. CX Codex +1 179installs

Project sponsors

Companies that keep this analytics open