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)

Required — the executive-summary block. The content opens with the **Status:** line and then, BEFORE the hook and stakes narrative, an executive summary. An RFC is a decision surface: the principal opens it to make a call, not to read an argument. Without this block the decision sits pages deep and the principal has to do the compression themselves.

## Executive summary (the decision in 60 seconds)

**The call: <the one decision that is genuinely the principal's, stated as a directive>.**

- <what changes>
- <what it costs / how long>
- <the main risk, and whether it is accepted or mitigated>
- <what it unlocks that is otherwise impossible>

Accepting this RFC = agreeing with the bolded call. Everything below is the reasoning.

Three to five bullets, one line each, no nested detail — if a bullet needs a sub-clause, that clause belongs in the body. The stakes-first structure from engineering-writing governs everything BELOW this block; the two compose (see that skill's §Decision artifacts lead with the decision).

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.)
• Executive-summary block immediately after the Status line — the principal's call in bold, 3–5 one-line consequence bullets, and the "Accepting = agreeing with the bolded call" closer
• 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

• Publishing without a decisionable summary. The RFC is where the principal makes the call; if the first screen is narrative, they cannot. Originating incident (2026-07-21): a ~3,500-word RFC opened to answer a Draft-vs-Accepted ask was bounced — "way too long... not decisionable." It recurred the next day on a freshly published RFC, which is why the block is a hard checklist item and not optional polish.
• 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 — the lifecycle demonstrated end-to-end