dev-rfc

Files (11)

• SKILL.md
• marked.min.js · assets/
• mermaid.min.js · assets/
• review_template.html · assets/
• bun.lock
• metadata.json
• package.json
• template.md · references/
• generate_review.py · scripts/
• generate_review.test.ts · scripts/
• generate_review.ts · scripts/

SKILL.md (first lines)

# Dev RFC Skill

Write RFCs and technical proposals that serve two purposes: **aligning stakeholders on what to build and why** (RFCs), and **helping engineers understand how a system works** (architecture docs). Most real proposals blend both — the skill helps you pick the right sections for the situation.

## Reference Templates

Read `references/template.md` for the three structural templates:

- **RFC** — for pre-build alignment. Focuses on abstract, approaches (with fair comparison), service SLAs, observability, and rollout plan.
- **Architecture Doc** — for documenting built systems. Focuses on diagrams, source tree, data flow, design philosophy.
- **One-Pager** — for small changes (< 1 week). Problem, Proposed Solution, Rollout. ~20 lines.

## Step 0: Pick the Mode

Ask the user (or infer from context) which situation they're in:

| Situation | Mode | Key question the doc answers |
|-----------|------|------------------------------|
| Planning a new system or major change | **RFC** | "Should we build this, and how?" |
| Documenting an existing system | **Architecture Doc** | "How does this system work?" |
| Proposing a change to an existing system | **RFC** (with before/after diagrams in Detailed Design) | "Why are we changing this, and what will it look like?" |
| Small scoped change (< 1 week) | **One-Pager** | "What and why, briefly?" |

For changes to existing systems, use the RFC structure as the backbone but include before/after architecture diagrams in the **Detailed Design** section, with `[NEW]` and `[CHANGED]` markers on components.

### File Placement

- **Formal proposal or RFC** — `docs/rfcs/RFC-NNN-title.md` as primary location
- **Architecture doc for the whole project** — `ARCHITECTURE.md` at the repo root
- **Subsystem doc** — `docs/design/subsystem-name.md` or alongside the code it describes

If the user hasn't specified where to put the doc, ask.

## Step 1: Understand the Project

Before writing anything, build a mental model.

**For RFCs:**
- Clarify the problem statement and constraints with the user
- Understand who the stakeholders and approvers are
- Ask about existing systems this interacts with or replaces
- Identify hard constraints (timeline, budget, compatibility, compliance)
- Ask what alternatives have already been considered or rejected

**For architecture docs:**
- Read the project's README, CLAUDE.md, and any existing docs
- Explore the source tree to identify major subsystems and their boundaries
- Trace the main data flow from input to output
- Look at key types/interfaces that flow between modules
- Check git history for context on architectural decisions

## Step 2: Draft the Document

Follow the appropriate structure from `references/template.md`. The sections to include depend on mode and project complexity — the template has scaling guidance for small/medium/large projects.

**The most important sections per mode:**

RFC — the sections approvers care about most:
1. **Abstract** — 3-5 sentence executive summary. A reader should be able to decide whether to read the full RFC from this alone.
2. **Approaches** — all evaluated options with fair comparison. This is what distinguishes an RFC from a spec.
3. **Service SLAs & Observability** — production readiness. Shows the proposal accounts for how the system will behave and be monitored in production.

Architecture Doc — the sections new contributors care about most:
1. **High-Level Architecture** (with diagram) — the single-glance understanding.
2. **Source Tree** — the "where do I find X" index.
3. **Key Design Decisions** — the "why is it done this way" answers.

## Step 3: Write Effective Content

**Not all systems are pipelines.** Choose the diagram shape that matches the system:
- **Pipeline** — compilers, data pipelines, ETL. Linear stages with data flowing through.
- **Request-flow** — services, APIs. Request path through middleware, handlers, dependencies.
- **Event-flow** — event-driven systems. Producers, queues/topics, consumers.
- **Layer diagram** — web apps, CRUD. UI → API → service → data layers.

The diagram is the centerpiece. A reader should understand the overall system flow from it alone. Use ASCII box-drawing art. Label stages with module paths and descriptions. Show data formats between stages.

**Be concrete, not abstract.** Instead of "Module A processes the input and passes it to Module B", write: "`Preprocessor::preprocess()` emits `String` (expanded text with line markers), which `Lexer::tokenize()` consumes to produce `Vec<Token>`." For proposals, use proposed type/interface names.

**Approaches should present genuine alternatives with fair pros/cons.** Don't strawman alternatives to make the recommended approach look better. Each approach should have real strengths acknowledged. A reviewer who disagrees with your recommendation should feel their preferred option was represented honestly.

**Goals & Non-Goals should be specific and falsifiable.** Example (for "migrate auth to OAuth2"):

> **Goals:**
> - All user-facing login flows use OAuth2 authorization code flow by end of Q3
> - Support Google and GitHub as identity providers at launch
> - Session token storage meets SOC 2 requirements (encrypted at rest, 24h max lifetime)
>
> **Non-Goals:**
> - Migrating service-to-service auth (stays on mTLS for now)
> - Building a custom identity provider — we'll use Auth0
> - Supporting SAML (enterprise SSO is a separate Q4 project)

**Service SLAs should be concrete.** Don't say "high availability" — state "99.95% uptime." Don't say "low latency" — state "P99 under 300ms." Justify each target.

**Separate decisions from philosophy.** Key Design Decisions are factual choices ("We use SSA form"). Design Philosophy captures principles that guide ongoing decisions ("Separation of concerns through representations").

## Step 4: Review Checklist

**For RFCs:**
- [ ] Is the Abstract clear enough that a reader can decide whether to read the full RFC?
- [ ] Does Approaches honestly represent all options with genuine pros/cons?
- [ ] Is the Recommendation well-justified — does it explain what's being given up?
- [ ] Are Service SLAs concrete with specific numbers, not vague ("high availability")?
- [ ] Are Goals & Non-Goals specific enough to evaluate the proposal against?
- [ ] Is there a concrete rollback plan with decision criteria?
- [ ] Are Open Questions clearly flagged for approver input?

**For architecture docs:**
- [ ] Can someone unfamiliar with the project understand the flow from the diagram alone?
- [ ] Are concrete types and method names in Data Flow accurate?
- [ ] Do Key Design Decisions cover what a new contributor needs first?
- [ ] Are cross-references to other docs (README, per-module docs) included?

## Step 5: Collect Feedback & Iterate (Optional)

After writing the RFC, offer to open a review UI in the user's browser. The review UI runs a local server that auto-saves feedback, supports multiple revision rounds, and lets the user explicitly approve the document.

> **Path resolution:** In the commands below, `$SKILL_PATH` refers to the absolute path of this SKILL.md file. Resolve it as the directory containing this file (e.g., if SKILL.md is at `/path/to/dev-rfc/SKILL.md`, then `$(dirname "$SKILL_PATH")` is `/path/to/dev-rfc`). **Requires Bun (or Node 22+ with `--experimental-strip-types`).**

From pproenca/dot-skills, MIT.

More from pproenca/dot-skills