Rfc

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

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

RFC Examples

Create

# Draft a new RFC from a topic
/rfc create event-driven architecture for notifications

# Multi-word topics work naturally
/rfc create migration from REST to gRPC for internal services

# If no topic given, you'll be asked
/rfc create

What happens: Gathers context from conversation history, research artifacts, ADRs, and codebase. Confirms scope with you. Writes a lightweight spec file (NNNN-<slug>.spec.md) for your approval. Then drafts a fully populated RFC with auto-numbering, including an Author's Notes section recording shortcuts, assumptions, and areas of uncertainty.

Review

# Review a specific RFC
/rfc review docs/rfcs/0003-event-driven-notifications.md

# If no path given, suggests globbing to find candidates
/rfc review

What happens: Loads the RFC and its companion spec file (if present). Discovers architecture standards from the project. Spawns the rfc-critic agent for an adversarial review — the critic reads the Author's Notes as prioritized attack vectors, evaluates 7 dimensions with a red-team mindset, checks RFC-vs-spec alignment, and produces a verdict with confidence score: Approve, Approve with changes, or Needs redesign. Every concern must cite evidence.

List

# List all RFCs with their status
/rfc list

Example output:

# Architecture RFCs

| # | Title | Status | Author | Date |
|---|-------|--------|--------|------|
| 0003 | Event-Driven Notifications | Draft | Jane Doe | 2026-03-15 |
| 0002 | API Gateway Migration | Approved | John Smith | 2026-02-20 |
| 0001 | Database Consolidation | Approved | Jane Doe | 2026-01-10 |

**Summary**: 3 total — 1 Draft, 0 Review, 2 Approved

Update

# Update specific sections after a review
/rfc update docs/rfcs/0003-event-driven-notifications.md

# Works best when:
# 1. You just ran /rfc review and want to address findings
# 2. You specify which sections to update in conversation

What happens: Reads the existing RFC, identifies which sections to update (from your instructions, review findings, or asks you), re-drafts those sections with fresh context while preserving everything else. Handles Author's Notes lifecycle — strips them on Approved status, refreshes after major re-drafts. Checks spec alignment if scope-related sections were changed. Shows a diff summary.

Status

# Transition RFC status with validation
/rfc status 3 review
/rfc status 3 approved
/rfc status 3 rejected

What happens: Finds the RFC by number, reads current status, validates the transition. Warns on unusual paths (e.g., Draft → Approved skips Review). If transitioning to Approved, strips the Author's Notes section entirely. Shows confirmation with old → new status and side effects applied.

Example: Normal transition:

RFC-0003: Draft → Review

Example: Warned transition (skipping Review):

⚠️ Warning: Skipping Review phase — consider getting review feedback first.

Proceed anyway?
  1. Yes, approve directly
  2. No, move to Review first

Example: Approval with side effects:

RFC-0003: Review → Approved
✓ Author's Notes stripped

Typical Workflow

# 1. Research and discuss a topic in conversation
"Let's discuss how to handle notifications in the system..."

# 2. Capture the discussion as an RFC (writes spec first, then full RFC)
/rfc create event-driven notifications

# 3. Adversarial review (uses rfc-critic agent)
/rfc review docs/rfcs/0003-event-driven-notifications.md

# 4. Address review findings
/rfc update docs/rfcs/0003-event-driven-notifications.md

# 5. Re-review after updates
/rfc review docs/rfcs/0003-event-driven-notifications.md

# 6. Approve the RFC (validates, strips Author's Notes)
/rfc status 3 approved

# 7. Check the pipeline
/rfc list

Spec: [Title]

Date: [YYYY-MM-DD] RFC: [will be NNNN-<slug>.md]

Problem Statement

[2-3 sentences: What is the problem? Who does it affect? What is the impact of NOT solving it?]

Key Constraints

• [Technical constraint — e.g., "Must support PostgreSQL 14+"]
• [Organizational constraint — e.g., "Team of 3, no dedicated DevOps"]
• [Timeline constraint — e.g., "Must ship before Q3 launch"]

Success Criteria

• [ ] [Measurable outcome 1 — e.g., "API latency < 200ms at p99"]
• [ ] [Measurable outcome 2 — e.g., "Zero downtime migration"]
• [ ] [Measurable outcome 3]

Scope Boundaries

In scope:

• [Item 1]
• [Item 2]

Out of scope:

• [Item 1 — reason]
• [Item 2 — reason]

RFC: [Title]

Author: [name] Status: Draft | Review | Approved | Rejected | Superseded Date: [YYYY-MM-DD] Reviewers: [names]

Summary

[1-2 paragraph overview of what this RFC proposes]

Motivation

[Why is this change needed? What problem does it solve? Include data or user feedback if available.]

Goals

• [Goal 1]
• [Goal 2]

Non-Goals

• [Explicitly out of scope item 1]
• [Explicitly out of scope item 2]

Architecture Overview

[High-level description of the proposed architecture]

Diagram

graph TD
    A[Component] --> B[Component]

Data Model

[Schema changes, new entities, migrations]

-- Example migration

APIs

[New or modified API endpoints]

Infrastructure

[New services, configuration changes, deployment requirements]

Security Considerations

• Authentication: [impact]
• Authorization: [impact]
• Data privacy: [impact]
• Input validation: [approach]

Scalability

• Expected load: [metrics]
• Bottlenecks: [identified risks]
• Scaling strategy: [approach]

Observability

• Metrics: [what to track]
• Logging: [what to log]
• Alerting: [thresholds]

Risks and Mitigations

Alternatives Considered

Alternative 1: [Name]

[Description and why it was rejected]

Migration Plan

1. [Step 1] 2. [Step 2]

Rollback strategy: [how to revert if needed]

Open Questions

• [ ] [Question 1]
• [ ] [Question 2]

Author's Notes

These notes feed the adversarial review process and will be stripped when the RFC is approved.

• Shortcuts: [What was simplified or assumed without full analysis?]
• Assumptions: [What is believed but not confirmed from code or docs?]
• Uncertainties: [Which parts had the least available information?]
• Low-confidence sections: [Which sections does the author consider weakest?]

RFC Troubleshooting

No RFC Directory Found

Symptom: /rfc list returns no results or /rfc create doesn't know where to write.

Cause: No RFC directory exists yet in the project.

Fix: /rfc create will automatically create docs/rfcs/ as the default directory. For jd-docs projects, ensure docs/20-architecture/ exists or create it first.

RFC Numbering Conflict

Symptom: Auto-numbered RFC conflicts with an existing file.

Cause: RFCs exist across multiple convention paths (e.g., docs/rfcs/ and .arkhe/rfcs/) and the highest number wasn't detected.

Fix: The skill searches all convention paths before numbering. If a conflict occurs, manually rename the file with the next available number.

Template Not Found

Symptom: Create operation can't find the RFC template.

Cause: The template at ${CLAUDE_SKILL_DIR}/templates/rfc-template.md is missing.

Fix: Verify the skill is properly installed. The template should be at plugins/doc/skills/rfc/templates/rfc-template.md. Reinstall the plugin if needed.

No Architecture Standards for Review

Symptom: Review falls back to "general best practices" instead of project-specific standards.

Cause: No architecture documentation found in any of the expected locations.

Fix: Create architecture documentation in one of the supported paths:

• .arkhe/roadmap/architecture.md (arkhe convention)
• docs/20-architecture/ directory (jd-docs convention)
• docs/architecture.md or docs/architecture/ (generic)

Update Changed Wrong Sections

Symptom: Sections that should have been preserved were modified.

Cause: Section boundaries were ambiguous or the update instruction was too broad.

Fix: Be specific about which sections to update (e.g., "update the Security Considerations and Data Model sections"). Review the diff summary output to verify changes.

RFC Status Not Recognized

Symptom: /rfc list shows "Unknown" status for an RFC.

Cause: The **Status**: field is missing or uses a non-standard value.

Fix: Ensure the RFC header includes **Status**: Draft (or Review, Approved, Rejected, Superseded). The field must match exactly: **Status**: followed by one of the valid values.

Spec File Not Found During Review

Symptom: Review does not check RFC-vs-spec alignment.

Cause: The spec file NNNN-<slug>.spec.md does not exist alongside the RFC. This is normal for RFCs created before the spec step was added, or for quick drafts.

Fix: The review proceeds without spec alignment checking — this is expected. To add a spec retroactively, create the file manually following the spec template at ${CLAUDE_SKILL_DIR}/templates/rfc-spec-template.md.

Author's Notes Not Stripped on Approval

Symptom: The Author's Notes section persists after status changes to Approved.

Cause: The status was changed by manually editing the file rather than through /rfc update.

Fix: Use /rfc update <path> and request the status transition to Approved. The update operation automatically strips the Author's Notes section.

rfc-critic Agent Not Found

Symptom: Review operation fails to spawn the rfc-critic agent.

Cause: The doc plugin was not reinstalled after the update that added the agent.

Fix: Reinstall the plugin: /plugin uninstall doc@arkhe-claude-plugins then /plugin install doc@arkhe-claude-plugins.

RFC Workflows

Detailed per-operation workflows for the RFC skill.

Common: RFC Directory Discovery

Search Algorithm

Check all paths and merge results (deduplicate by filename). Exclude *.spec.md companion files from results:

1. docs/rfcs/*.md 2. docs/20-architecture/rfcs/*.md — jd-docs convention 3. .arkhe/rfcs/*.md — arkhe convention 4. arkhe/rfcs/*.md

jd-docs Detection

Check for jd-docs structure:

• .jd-config.json exists in project root, OR
• docs/20-architecture/ directory exists

Write Directory Resolution (for create/update)

Use the first match: 1. If jd-docs detected → docs/20-architecture/rfcs/ 2. Else if docs/rfcs/ exists → docs/rfcs/ 3. Else → create docs/rfcs/ as default

---

Create Workflow

Step 1: Determine Topic

• Extract topic from arguments after create
• If empty, ask the user what the RFC should be about

Step 2: Gather Context

Search for existing information before writing:

1. Conversation context — review the current conversation for discussion, decisions, and research already conducted 2. Research artifacts — search for related research documents:

• docs/30-research/
• docs/50-research/
• docs/research/

3. Memory files — grep the memory directory for cached research on the topic 4. Codebase — scan relevant source files to understand the current state (the "before" picture) 5. ADRs — check for related architecture decisions:

• docs/20-architecture/22-adr/
• docs/20-architecture/adr/
• docs/adr/

Step 3: Confirm Scope

Present a brief summary of findings and proposed RFC scope. Ask the user to confirm or adjust. Use AskUserQuestion with key scoping choices if there are meaningful alternatives.

Step 4: Resolve Number and Slug

Compute the auto-number and slug early — both the spec and RFC files share the same NNNN-<slug>:

1. Discover the write directory (see Write Directory Resolution above) 2. Glob all convention paths for the highest existing RFC number 3. Assign the next sequential number (zero-padded to 4 digits) 4. Ask user to confirm the title, then generate a kebab-case filename slug 5. Both files will use this: <dir>/NNNN-<slug>.spec.md and <dir>/NNNN-<slug>.md

Step 5: Write Spec File

Draft a lightweight spec to anchor the full RFC:

1. Read the spec template at ${CLAUDE_SKILL_DIR}/templates/rfc-spec-template.md 2. Fill in all four sections with concrete content:

• Problem Statement: 2-3 sentences describing the problem in terms of user/business impact. Include the cost of inaction.
• Key Constraints: Technical, organizational, or timeline constraints that bound the solution space. Be specific — "must support Postgres" not "database compatibility".
• Success Criteria: Measurable outcomes that indicate the RFC succeeded. Each criterion must be testable (e.g., "latency under 200ms at p99", "zero downtime migration").
• Scope Boundaries: What is explicitly in scope and out of scope. Out-of-scope items must include a reason.

3. Write to <dir>/NNNN-<slug>.spec.md using the resolved number and slug 4. Present the spec to the user. Use AskUserQuestion to confirm or adjust. 5. Only proceed to the full RFC draft after user confirms the spec.

Completeness test: Could someone who hasn't seen the original conversation draft a correct RFC from this spec alone? If not, add more detail.

Step 6: Read Template

Read ${CLAUDE_SKILL_DIR}/templates/rfc-template.md for section structure.

Step 7: Draft RFC

Fill every section with substantive content:

• Summary: 1-2 paragraph overview of the proposal
• Motivation: Real problems from the codebase/discussion, not placeholder text
• Goals / Non-Goals: Specific, actionable items
• Architecture Overview: Concrete technical approach with package names, file paths, patterns
• Diagram: Mermaid diagram showing the proposed architecture or data flow
• Data Model: Actual schema changes or "no changes required" with rationale
• APIs: Real endpoints or "no API changes" with rationale
• Infrastructure: Deployment impact assessment
• Security Considerations: Specific to this proposal
• Scalability: Realistic load assessment
• Observability: What to monitor
• Risks and Mitigations: Real risks with likelihood/impact assessment
• Alternatives Considered: At least 2 alternatives with clear rejection rationale
• Migration Plan: Step-by-step with rollback strategy
• Open Questions: Genuine unresolved decisions (not filler)

Set Author to the git user name, Status to Draft, Date to today.

Step 8: Append Author's Notes (Confession)

After completing all standard RFC sections, append ## Author's Notes below Open Questions:

• Shortcuts: What was simplified or hand-waved? (e.g., "Assumed Redis cluster mode works with our VPC setup without testing")
• Assumptions: What did the author believe but not confirm from the codebase or documentation? (e.g., "Assuming the payment API returns sorted results")
• Uncertainties: Which sections had the least information available?
• Low-confidence sections: Which sections does the author consider weakest?

Guidelines:

• Be specific and honest. Vague confessions like "some parts may need more thought" are useless.
• Reference specific RFC sections (e.g., "The Scalability section assumes linear scaling — not verified").
• Aim for 3-8 confession items. Fewer suggests overconfidence; more suggests the RFC is not ready.
• These notes feed the adversarial review — they are features, not bugs.

Step 9: Write RFC

Use the resolved number and slug from Step 4. Write to <dir>/NNNN-<slug>.md.

Step 10: Suggest Next Steps

• /rfc review <path-to-new-rfc> — for adversarial design review (uses rfc-critic agent)
• Manual review by team members

---

Review Workflow

Context Loading

1. Read the RFC document at the given path 2. Check for a companion spec file: replace .md with .spec.md in the filename (e.g., 0003-event-driven.md → 0003-event-driven.spec.md). 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)
• If none found, the agent reviews against general architecture best practices

4. Scan referenced modules/packages in the RFC to verify feasibility

Agent Delegation

Spawn the rfc-critic agent (subagent_type: doc:rfc-critic) via the Agent tool. Provide in the prompt:

1. The full RFC content 2. The spec file content (if found), with instruction: "Check RFC-vs-spec alignment for each success criterion and scope boundary" 3. Architecture standards content (if found) 4. Instruction: "Read the Author's Notes section first and use confessions as prioritized attack vectors"

The agent independently evaluates all 7 dimensions with adversarial framing and returns a structured review. It has read-only codebase access (Read, Grep, Glob, Bash) to verify claims made in the RFC.

Output Format

The agent produces output in this format:

# RFC Review: [RFC Title]
**Reviewer**: rfc-critic | **Date**: [date] | **RFC**: [path] | **Confidence**: [0-100]

## Verdict: [Approve | Approve with changes | Needs redesign]

## Summary
[2-3 sentence assessment]

## Strengths
- [strength with reference to RFC section]

## Concerns

### Critical
- [concern] — Section: [ref] | Evidence: [citation] | Impact: [description]

### Major
- [concern] — Section: [ref] | Evidence: [citation] | Impact: [description]

### Minor
- [concern] — Section: [ref] | Evidence: [citation] | Suggestion: [fix]

## Suggested Improvements
1. [improvement with rationale]

## Verdict Rationale
[Why this verdict was chosen. What must change before approval (if applicable).]
[Why confidence is at this level — what would raise or lower it.]

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

Notes

• Flag missing sections from the standard RFC template as Minor concerns
• After review, suggest /rfc update <path> to address findings

---

List Workflow

Header Extraction

For each RFC file found, extract from the file header:

• Number/Filename: from the file path (e.g., 0003 from 0003-event-driven.md)
• Title: from the # RFC: [Title] heading. If non-standard, use the first # heading.
• Status: from the **Status**: field. Valid values: Draft, Review, Approved, Rejected, Superseded. If missing, show "Unknown".
• Author: from the **Author**: field. If missing, show "—".
• Date: from the **Date**: field. If missing, show "—".

Output Format

# Architecture RFCs

| # | Title | Status | Author | Date |
|---|-------|--------|--------|------|
| 0003 | Event-Driven Notifications | Draft | Jane Doe | 2026-03-15 |
| 0002 | API Gateway Migration | Approved | John Smith | 2026-02-20 |
| 0001 | Database Consolidation | Approved | Jane Doe | 2026-01-10 |

**Summary**: 3 total — 1 Draft, 0 Review, 2 Approved

Sort by number descending (newest first).

---

Update Workflow

Section Identification

Determine which sections need updating:

1. Explicit user request: User specified sections in the conversation (e.g., "update the security section") 2. Post-review context: If invoked after /rfc review, parse review findings — update sections flagged with Critical or Major concerns 3. Interactive: If neither above applies, present the RFC's section list and ask the user which to revise

Preservation Rules

• Read the entire RFC before making changes
• Only modify the identified sections — preserve all other sections byte-for-byte
• Maintain the same heading structure and nesting
• Do not reorder sections
• Do not add or remove sections unless the user explicitly requests it

Context Gathering for Updates

For each section being updated: 1. Read the current section content 2. Search the conversation for relevant new information 3. Check for new research artifacts or codebase changes since the RFC was written 4. If the update was prompted by a review, reference the specific concern and suggested improvement

Diff Summary

After updating, output a summary:

## Update Summary

**RFC**: [path]
**Date**: [today]
**Sections updated**:
- **Security Considerations**: Added JWT token rotation strategy and OWASP references
- **Data Model**: Updated migration plan to handle backward compatibility
- **Open Questions**: Resolved 2 of 4 open questions based on team discussion

Status Transitions (within update)

• Keep Status unchanged by default
• If user explicitly requests a status change (e.g., "move to Review"), update the **Status**: field
• Valid transitions: Draft → Review → Approved/Rejected, any → Superseded
• For dedicated status changes with validation, prefer /rfc status which validates transitions and handles side effects automatically

Author's Notes Handling

• Status transition to Approved: Remove the ## Author's Notes section and all its content entirely.
• User requests "refresh confessions": Regenerate the Author's Notes based on the current RFC state, replacing the old section.
• Major sections re-drafted: After re-drafting, review the existing Author's Notes. If confessions reference sections that were substantially changed, update or remove those specific confession items.
• Otherwise: Preserve Author's Notes as-is, like any other section.

Spec Alignment on Update

If a companion .spec.md file exists and the update touches Goals, Non-Goals, Architecture Overview, or Scope-related content:

1. Re-read the spec file 2. Verify the updated RFC still aligns with the spec's Problem Statement, Key Constraints, Success Criteria, and Scope Boundaries 3. If drift is detected, flag it to the user and suggest updating either the spec or the RFC to restore alignment

---

Status Transition Workflow

Dedicated workflow for changing RFC status with validation and side effects. Invoked by /rfc status <number> <status>.

Find RFC

1. Resolve RFC number to file path by globbing all convention paths for NNNN-*.md (exclude *.spec.md) 2. Read the file and extract current status from **Status**: field 3. If RFC not found, report error with the number and searched paths

Validate Transition

Check current → target transition and warn on unusual paths:

On warning: use AskUserQuestion to ask user to confirm. If user declines, abort.

Apply Status Change

1. Update `Status:` field in the RFC file 2. Side effects by target status:

• → Approved: Strip the entire ## Author's Notes section and all its content. This is the primary enforcement mechanism for the confession lifecycle.

3. Preserve everything else — only modify the Status field and (if applicable) remove Author's Notes

Post-Transition

Show confirmation:

RFC-0003: Review → Approved
✓ Author's Notes stripped