draft-rfc

---
name: draft-rfc
description: >-
  Draft a Minsky RFC end-to-end: scope check, research pass, write, dispatch
  expert-review subagent, revise, publish to Notion under the Minsky home with
  RFC: prefix and Draft status. Use when proposing a new subsystem, a
  multi-phase roadmap, a cross-cutting architectural move, or any strategic
  direction that benefits from a defensible written argument.
user-invocable: true
---

# Draft an RFC

End-to-end authoring lifecycle for an RFC (Request for Comments) in Minsky. RFCs propose strategic direction with alternatives weighed; they live in Notion under the Minsky home page; they get expert-review subagent passes before shipping; they produce implementation tasks once Accepted.

## Arguments

Required: the topic. A short phrase that names what the RFC is about (e.g., `/draft-rfc Braintrust trace shape`, `/draft-rfc memory system roadmap`).

Optional:

- The expert-review domain to dispatch a subagent for (e.g., `domain: LLM observability`). If omitted, the skill picks a domain heuristically from the topic.

## When to use this skill vs alternatives

- **Use `/draft-rfc`** when: proposing a new subsystem, a multi-phase roadmap, or a strategic direction with alternatives. Output goes to Notion.
- **Use `/draft-adr`** instead when: the work is one architectural decision with alternatives but no roadmap or multi-phase plan. Output goes to `docs/architecture/adr-NNN-*.md`.
- **Just write a Position paper** (no skill required) when: arguing a thesis without proposing implementation work.
- **Use `/create-task`** when: the work is a concrete actionable unit, not a strategic proposal.

See `documentation-taxonomy.mdc` for the full taxonomy.

## Process

### 1. Scope check — is this really an RFC?

Before committing to RFC scope, confirm:

- Is there more than one credible option to weigh? (If only one option, write a Design doc instead.)
- Does it span multiple phases or surfaces? (If single-phase, an ADR may be enough.)
- Will it produce more than one downstream task? (If only one task, the task spec itself is the right surface.)

If any of these fail, redirect to `/draft-adr`, `/create-task`, or a Position paper. Don't force a small decision into RFC scope.

### 2. Research pass — Minsky context

Before drafting, ground the proposal in existing Minsky context:

- `mcp__minsky__memory_search` with terms from the topic — surface prior thinking
- `mcp__minsky__tasks_search` — find related tasks (open, blocked, done)
- `mcp__minsky__rules_search` — find related rules
- Notion search via `mcp__plugin_Notion_notion__notion-search` — find sibling RFCs or position papers
- Read any cross-referenced material end-to-end, not just titles

Cite the surfaced material in the RFC's References section.

### 3. Research pass — external context

For non-trivial RFCs, also pass through external context:

- WebSearch for the relevant community / industry literature
- Read primary sources (vendor docs, OSS project READMEs, RFCs from adjacent projects)
- Identify the camps, the points of consensus, and the open questions in the field

Cite the external material in References too.

### 4. Draft using the engineering-writing skill

Invoke `engineering-writing` skill for the writing craft. Key structural moves to apply:

- **Stakes before position.** Lead with a concrete observation that motivates the problem before stating what you think.
- **Position section right after stakes.** Three to five positions in plain text; invite disagreement.
- **Threats / validation before prescription.** What failure modes does the proposal handle, and which does it not?
- **Phases integrated with gates.** Per-phase activation triggers, not timelines.
- **Strip internal task IDs from main body.** Reference them in the appendix or origin section only.

See `engineering-writing/SKILL.md` for the full writing checklist, AI-voice tells inventory, and revision workflow.

### 5. Dispatch the expert-review subagent

Before shipping, dispatch an expert review. This is the structural quality lever — Chinese-wall review for prose, mirroring how subagent reviewers catch issues in code PRs.

The Notion MCP tool names referenced below (`mcp__plugin_Notion_notion__notion-fetch`, `notion-search`, `notion-create-pages`, `notion-update-page`) are provided by Claude Code's harness-level Notion plugin, not by this repository. They are available in the agent's tool surface when the user has the Notion plugin connected. If the plugin is not connected, fall back to manual Notion edits — but for this skill we assume it is, since the doc lives in Notion. Verify presence with the harness's tool-search before assuming availability.

```
Agent({
  description: "Expert review of <RFC topic> draft",
  subagent_type: "general-purpose",
  model: "opus",
  prompt: "You are a <domain> expert reviewing a design RFC. Read the doc first: Notion page id <page-id>. Fetch via mcp__plugin_Notion_notion__notion-fetch (Notion plugin tool, harness-provided). Review carefully end-to-end. Specific axes: <axes>. Push back specifically with concrete findings. Deliver findings with severity (BLOCKING / IMPORTANT / NICE-TO-HAVE) and concrete recommendations. Return as final message; do not post to GitHub or Notion."
})
```

Pick the domain by the RFC's content (e.g., LLM observability, security architecture, persistence design, agent infrastructure). The subagent should run with `opus` model since this is high-stakes critique work.

### 6. Revise based on findings

For each BLOCKING finding:

- Determine whether it's correct. Don't reflexively accept; verify against the doc, the code, and the cited evidence.
- If correct, revise the doc. Major findings (phase ordering, missing sections) may require substantial restructuring; don't shortcut.

For each IMPORTANT finding:

- Address it inline unless explicitly deferred. Deferred items go in the "What's still open" section with rationale.

For each NICE-TO-HAVE:

- Address inline or note as a follow-up. Don't let small findings accumulate into a backlog.

Add an "Origin and review" section near the end of the RFC summarizing what the review found and how revision addressed it. This makes the lifecycle visible to future readers.

### 7. Publish to Notion

Use the Notion plugin's `notion-create-pages` tool (harness-provided as `mcp__plugin_Notion_notion__notion-create-pages` in Claude Code).

Required call shape:

- `parent`: `{ "type": "page_id", "page_id": "33a937f0-3cb4-8197-a93e-cd4a98a94261" }` — Minsky home page
- `pages`: array of one page with:
  - `properties.title`: `RFC: <topic>` (per `documentation-taxonomy.mdc` title pattern)
  - `content`: the revised body in Notion-flavored Markdown, starting with `**Status:** Draft (<date>)` on the first line
  - `icon` (optional): distinctive emoji (`🔭` observability, `🧠` memory, `🪢` mesh, `📐` architecture)

For updates to an existing RFC (status transitions, content revisions): use `notion-update-page` with `command: "update_properties"` to rename or change properties, or `command: "replace_content"` to rewrite the body. Title updates require `properties: { "title": "<new title>" }`; body updates require the full new content as `new_str`.

After publish, the returned page ID becomes the canonical reference. Save a memory anchor linking back to the page (via `mcp__minsky__memory_create`) so future agents pick it up automatically via memory search.

### 8. File implementation tasks

Each phase in the roadmap likely needs at least one task. File them with `mcp__minsky__tasks_create` and cross-reference the RFC's Notion page ID in each task spec's Context section.

The first-phase task should be filed and ready to move to PLANNING / READY before declaring the RFC done.

### 9. Update status as the proposal evolves

The RFC stays at `Draft` while discussion is active. Move to `Accepted` once the principal signs off (or implementation begins). Move to `Implemented` once the roadmap completes. Move to `Declined` or `Superseded` if direction changes.

Updates to the status are edits to the Notion page's status header at the top of the body.

## Output checklist

When the skill completes, verify:

- [ ] Notion page exists under Minsky home with `RFC:` prefix
- [ ] Status header reads `**Status:** Draft (<date>)` (or Accepted / etc.)
- [ ] Body has a concrete hook, stakes section, position section, framework / contribution, validation, roadmap, open questions, references
- [ ] Expert review was dispatched and findings were addressed (or explicitly deferred)
- [ ] "Origin and review" section near the end records the review lifecycle
- [ ] Memory anchor saved with page ID and short summary
- [ ] At least one implementation task filed referencing the RFC by page ID

If any of these are missing, the skill hasn't finished — return to the relevant step.

## Common failure modes

- **Skipping the expert-review subagent.** This is the highest-leverage step; skipping it forfeits the quality lever. Don't shortcut even for "small" RFCs — if it's worth an RFC, it's worth a review pass.
- **Drafting before research.** Producing prose without prior memory / task / web search produces shallow proposals. Research first, draft second.
- **Burying the position in section 8 of 12.** Readers stop reading before they reach it. Stakes section ends with the position teased; position section follows directly after stakes.
- **Forced symmetry.** Don't pad to "four camps" or "three phases" if your content has two or five. Real arguments have ragged edges.
- **Title-cased headings, AI-voice tics.** See `engineering-writing/SKILL.md` for the inventory.

## Cross-references

- `documentation-taxonomy.mdc` — the rule that names RFC as a category and points here
- `engineering-writing/SKILL.md` — writing-craft skill; this skill delegates the actual prose to it
- `create-task/SKILL.md` — for filing implementation tasks once an RFC is Accepted
- `humility.mdc §Escalation packaging` — for RFCs that surface principal-level decisions
- Example RFC: [Braintrust trace shape for Minsky](https://www.notion.so/35e937f03cb481baa6ddf1f571d1020a) — the lifecycle demonstrated end-to-end