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](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](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](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](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):
4. .arkhe/roadmap/architecture.md (arkhe convention)
5. docs/20-architecture/ directory (jd-docs convention)
6. docs/architecture.md or docs/architecture/ (generic)
7. Fall back to general best practices
8. 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](WORKFLOW.md) for delegation details.
9. 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.
10. Verdict criteria:
11. Approve: No critical concerns, minor issues only
12. Approve with changes: No critical concerns, has major concerns with clear fixes
13. Needs redesign: Has critical concerns or fundamental architecture issues
14. Flag missing RFC template sections as Minor concerns
15. 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:
3. If user specified sections in conversation, update those
4. If invoked after a /rfc review, use review findings to identify sections needing changes
5. Otherwise, ask the user which sections to revise
6. Gather fresh context from conversation, research, and codebase for the sections being updated
7. Re-draft sections — rewrite identified sections with improved content. Preserve all unchanged sections exactly as-is.
8. Update Date to today. Keep Status unchanged unless user requests a transition.
9. 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](WORKFLOW.md) for lifecycle rules.
10. 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.
11. Show diff summary — list which sections were changed and a brief description of each change
12. 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:
3. Valid: Draft → Review → Approved/Rejected, any → Superseded
4. Warn: Draft → Approved (skipping Review), Approved → Draft (going backwards)
5. On warning, use AskUserQuestion to confirm
6. Apply status change — update Status: field in the RFC
7. Side effects:
8. → Approved: Strip ## Author's Notes section entirely
9. 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