references/template.md

• 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.

• 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

• 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

• 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

references/template.md

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.

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.

• 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.

Preprocessor::preprocess()

String

Lexer::tokenize()

Vec<Token>

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)

• 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?

• 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?

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

).

1. Save the RFC to its target file path.
2. Start the review server:
   bash

   bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" <doc-path> --title "<project name>"

   This starts an HTTP server on

   localhost:3118

   and opens the browser. Feedback auto-saves to

   <doc-dir>/.rfc-review/feedback.json

   as the user types (800ms debounce). The server also serves the latest version of the markdown on each refresh.
3. Tell the user: "I've opened the RFC review in your browser at http://localhost:3118. Add feedback to any section, highlight text for inline comments, then click Submit Feedback (for revisions) or Approve (if it looks good). Your feedback auto-saves as you type."
4. When the user says they're done reviewing, read feedback from the workspace:
   bash

   cat <doc-dir>/.rfc-review/feedback.json

• "status": "approved"

  — The user approved the RFC. Stop iterating. Announce that the RFC is finalized.

• "status": "needs_revision"

  — The user wants changes. Proceed to revision.

• "status": "draft"

  — The user closed the browser mid-review. Ask if they want to continue or if the current draft feedback is sufficient.

1. Inline comments (

   inline_comments

   ) — targeted at specific text. Address each one.
2. Section feedback (

   sections[].feedback

   ) — per-section concerns. Revise the relevant section.
3. Overall feedback (

   overall_feedback

   ) — broad themes. Apply across the document.

• The user clicks Approve in the UI (

  "status": "approved"

  )
• The user says "looks good", "ship it", "done", or similar
• The user explicitly says they don't want more rounds

• The user wants to collaborate on the RFC as it's being written
• The RFC is complex and benefits from iterative alignment on each section
• The user explicitly asks for "live", "interactive", or "step-by-step" mode

1. Plan the section headings for the RFC based on the template and project scope.
2. Start the server in live mode:
   bash

   bun run "$(dirname "$SKILL_PATH")/scripts/generate_review.ts" --live --title "<project name>" \
     --sections '["Abstract","Motivation","Goals and Non-Goals","Detailed Design","Approaches","Service SLAs","Rollout Plan"]'

   This opens the browser showing a skeleton with all planned sections as pending cards.
3. Tell the user: "I've opened the RFC in live authoring mode at http://localhost:3118. I'll write each section one at a time — you can approve or request changes on each section before I move to the next."

1. Write the section content as markdown.
2. Push it to the server:
   bash

   curl -s -X POST http://localhost:3118/api/section/add \
     -H 'Content-Type: application/json' \
     -d '{"id": "abstract", "heading": "Abstract", "markdown": "## Abstract\n\nYour content here..."}'

   The section appears in the browser immediately via SSE.
3. Wait for user feedback:
   bash

   curl -s http://localhost:3118/api/wait-feedback?section=abstract

   This blocks until the user clicks "Approve" or "Request Changes" in the browser (5-minute timeout).
4. Handle the response:

   • {"action": "approve"}

     — Move to the next section.

   • {"action": "request_changes", "text": "..."}

     — Read the feedback, revise the section, then push the update:
     bash

     curl -s -X POST http://localhost:3118/api/section/update \
       -H 'Content-Type: application/json' \
       -d '{"id": "abstract", "markdown": "## Abstract\n\nRevised content..."}'

     Then call

     /api/wait-feedback?section=abstract

     again.

   • {"timeout": true}

     — The user hasn't responded in 5 minutes. Prompt them in the CLI or retry.

• Present tense, declarative voice for architecture docs. Future tense only for proposals.
• Concise — every word should earn its place
• Prefer showing (diagrams, code, type signatures) over telling
• Short paragraphs — this is reference material, not prose
• Markdown formatting: bold for emphasis, code blocks for types/paths, tables for comparisons

1. Draft — Author is still writing. Not ready for formal review.
2. In Review — Shared with approvers. Specify what feedback is needed.
3. Approved — Approvers signed off. Plan of record.
4. Superseded — Newer RFC replaces this one. Link to replacement.
5. Deprecated — System no longer exists or proposal was abandoned.