RFC Manager

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

Argument Parsing

Parse $ARGUMENTS to determine the action:

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

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