rfc

RFC Manager

Manage architecture RFCs with 5 operations: create, review, list, update, status.

Argument Parsing

Parse $ARGUMENTS to determine the action:

First word	Remaining args	Operation
create	<topic>	Draft a new RFC
review	<path-to-rfc>	Review an existing RFC
list	(none)	List all RFCs
update	<path-to-rfc>	Update specific RFC sections
status	<number> <status>	Transition RFC status with validation and side effects
(empty)		Ask the user which action to perform

If the first word does not match any action, treat the entire $ARGUMENTS as a topic and default to create.

RFC Directory Discovery

Used by all operations. Search for RFC files across all convention paths (exclude *.spec.md companion files):

1. docs/rfcs/*.md
2. docs/20-architecture/rfcs/*.md (jd-docs — detected via .jd-config.json or docs/20-architecture/ directory)
3. .arkhe/rfcs/*.md (arkhe convention)
4. arkhe/rfcs/*.md

For create and update, resolve a write directory:

• If jd-docs detected → docs/20-architecture/rfcs/
• Else if docs/rfcs/ exists → docs/rfcs/
• Else → create docs/rfcs/ as default

Operation: create

Draft a populated RFC — NOT a blank template. Gather context, write a spec, then write a real first draft with honest self-assessment.

1. Determine topic from args after create (or ask if empty)
2. Gather context — search conversation, research artifacts (docs/30-research/, docs/50-research/, docs/research/), memory files, relevant source code, and ADRs (docs/20-architecture/22-adr/, docs/20-architecture/adr/, docs/adr/). See WORKFLOW.md for detail.
3. Confirm scope with user before drafting — present what you found and proposed scope. Use AskUserQuestion for meaningful alternatives.
4. Resolve number and slug — discover write directory, glob all convention paths for highest existing number, assign next (zero-padded 4 digits). Confirm title with user, generate kebab-case slug. Both spec and RFC will use NNNN-<slug>.
5. Write spec file — read spec template at ${CLAUDE_SKILL_DIR}/templates/rfc-spec-template.md. Fill Problem Statement, Key Constraints, Success Criteria, and Scope Boundaries with concrete content. Write to <dir>/NNNN-<slug>.spec.md. Present to user for confirmation via AskUserQuestion. See WORKFLOW.md for spec guidance.
6. Read RFC template at ${CLAUDE_SKILL_DIR}/templates/rfc-template.md for section structure
7. Draft populated RFC filling every section with substantive content. See WORKFLOW.md for per-section guidance. Set Author to git user name, Status to Draft, Date to today.
8. Append Author's Notes — below Open Questions, record: shortcuts taken, unverified assumptions, areas of uncertainty, low-confidence sections. Aim for 3-8 items. Be specific — these feed the adversarial review. See WORKFLOW.md for confession guidelines.
9. Write RFC to <dir>/NNNN-<slug>.md
10. Suggest next steps: /rfc review <path> for adversarial design review (uses rfc-critic agent)

Operation: review

Adversarial review of the RFC using the rfc-critic agent — a dedicated red-team reviewer that reads the Author's Notes as attack vectors and checks spec alignment.

1. Read RFC at the given path (if empty, ask — suggest globbing docs/rfcs/*.md and docs/20-architecture/rfcs/*.md)
2. Load spec file — check for a companion NNNN-<slug>.spec.md alongside the RFC. If found, read it.
3. Discover architecture standards (check in order, use first found):
   • .arkhe/roadmap/architecture.md (arkhe convention)
   • docs/20-architecture/ directory (jd-docs convention)
   • docs/architecture.md or docs/architecture/ (generic)
   • Fall back to general best practices
4. Spawn rfc-critic agent — use the Agent tool (subagent_type: doc:rfc-critic). Pass: the RFC content, spec content (if found), architecture standards (if found). See WORKFLOW.md for delegation details.
5. Present review output — the agent returns a structured review with confidence score, verdict, concerns by severity (each with evidence citations), and improvements. Display to user.
6. Verdict criteria:
   • Approve: No critical concerns, minor issues only
   • Approve with changes: No critical concerns, has major concerns with clear fixes
   • Needs redesign: Has critical concerns or fundamental architecture issues
7. Flag missing RFC template sections as Minor concerns
8. Suggest next steps: /rfc update <path> to address findings

Operation: list

List all architecture RFCs with their current status.

1. Search all convention paths (see RFC Directory Discovery)
2. For each RFC, extract from headers: Number/Filename, Title (from # RFC: [Title] or first # heading), Status (Draft/Review/Approved/Rejected/Superseded — default "Unknown"), Author (default "—"), Date (default "—")
3. Output markdown table sorted by number descending (newest first):

# Architecture RFCs

| # | Title | Status | Author | Date |
|---|-------|--------|--------|------|

**Summary**: X total — Y Draft, Z Review, W Approved

4. If no RFCs found, suggest /rfc create <topic>

Operation: update

Re-draft specific sections of an existing RFC based on new context or feedback.

1. Read RFC at the given path (if empty, ask for path)
2. Identify sections to update:
   • If user specified sections in conversation, update those
   • If invoked after a /rfc review, use review findings to identify sections needing changes
   • Otherwise, ask the user which sections to revise
3. Gather fresh context from conversation, research, and codebase for the sections being updated
4. Re-draft sections — rewrite identified sections with improved content. Preserve all unchanged sections exactly as-is.
5. Update Date to today. Keep Status unchanged unless user requests a transition.
6. Handle Author's Notes — if status transitions to Approved, strip the Author's Notes section entirely. If major sections were re-drafted, refresh the confessions. See WORKFLOW.md for lifecycle rules.
7. Check spec alignment — if a companion .spec.md file exists and the update touches Goals, Non-Goals, or Architecture Overview, verify the RFC still aligns with the spec. Flag drift to the user.
8. Show diff summary — list which sections were changed and a brief description of each change
9. Suggest next steps: /rfc review <path> to verify the updates

Operation: status

Transition RFC status with validation, warnings, and side effects.

1. Find RFC — resolve number to file path by globbing all convention paths for NNNN-*.md. Read current status from **Status**: field.
2. Validate transition — check against valid transitions. Warn (but allow) on unusual paths:
   • Valid: Draft → Review → Approved/Rejected, any → Superseded
   • Warn: Draft → Approved (skipping Review), Approved → Draft (going backwards)
   • On warning, use AskUserQuestion to confirm
3. Apply status change — update **Status**: field in the RFC
4. Side effects:
   • → Approved: Strip ## Author's Notes section entirely
5. Confirm — show old status → new status, side effects applied

Valid statuses: Draft | Review | Approved | Rejected | Superseded

Note: The update operation still handles inline status changes during content updates. Use /rfc status for dedicated status transitions with validation.

Quality Standards

• Every section must contain real content, not placeholder text like [describe here]
• Reference specific files, packages, and patterns from the codebase
• If a section doesn't apply, state that explicitly with a one-line rationale
• Drafts should be good enough to review immediately, not skeletons to fill in later

Progressive Disclosure

• WORKFLOW.md — detailed per-operation workflows
• EXAMPLES.md — usage examples for all operations
• TROUBLESHOOTING.md — common issues and solutions