rfc

name	rfc
description	Design and resolve RFC documents through evidence-gated multi-round workflow. Use when planning large architectural/program-level changes in docs/rfcs, enforcing goal/scope/direction clarity, explicit first-principles/long-term/original-fit proposal lenses with rationale, draft-to-formal progression, and resolve-time synchronization with task/backlog outcomes plus readiness validation.

RFC Workflow

Use this skill to design and finalize RFC documents before implementation. Scripts are executable; invoke them directly (no cargo +nightly -Zscript prefix).

This skill has two prompt workflows:

1. rfc create: design-phase RFC research, alternatives, draft, and formalization.
2. rfc resolve: post-implementation RFC synchronization and readiness checks.

rfc create Required Flow

1. Perform deep research first (docs + code + provided conversation context).
2. Produce multiple design proposals with explicit tradeoffs under the proposal quality gate.
3. Require user selection/feedback before drafting.
4. Create a draft RFC file (single file, status: draft) only after user approval.
5. Run additional discussion/refinement on the draft.
6. Require explicit approval before promoting draft to formal RFC (status: proposal or status: accepted).

Do not skip or reorder these steps.

Step 1: Run Deep Research

Read relevant architecture/process docs and inspect related code paths before proposals. At minimum, evaluate relevant files from:

• docs/architecture.md
• docs/transaction-system.md
• docs/index-design.md
• docs/checkpoint-and-recovery.md
• docs/table-file.md
• docs/process/issue-tracking.md

Then inspect impacted modules and call paths in doradb-storage/src/. Ground design decisions in concrete file-level impacts. If the RFC touches test strategy, timeout policy, or validation workflow, also read docs/process/unit-test.md.

Step 2: Enforce Evidence Gate

RFC must include explicit design inputs with references to:

1. Documents.
2. Code references.
3. Conversation references (user-provided constraints/discussion decisions).
4. Optional source backlogs.

Use docs/rfcs/0000-template.md structure and keep references traceable. Every major decision and every alternative must include at least one reference token.

Step 3: Round 1 (Initial Proposals)

Produce an initial package with:

1. Goal, scope, and direction framing.
2. Current-state analysis grounded in docs/code.
3. At least 3 proposals with these explicit labeled lenses:
   • First-Principles Proposal: derived from project goals and fundamentals, even when it conflicts with the developer's requested direction.
   • Long-Term Evolution Proposal: optimized for the project's long-term architecture and evolution, even when it broadens program scope or phasing.
   • Original-Requirement-Fit Proposal: best fit for the developer's requested scope/intention.
   • Additional proposals are welcome when they add real strategic value.
4. Scope change analysis, rationale, tradeoffs/drawbacks, and alignment/conflict with the original request for each proposal.
5. Recommended direction and rationale.

Recommendation defaults to the best overall direction for correctness and project evolution; do not default to the original request just because it was requested. If the recommended direction conflicts with the original request, explicitly describe the reasoning and findings that make the original direction weaker. If the Long-Term Evolution Proposal broadens scope beyond the original framing, state that scope change explicitly and, when useful, identify a prerequisite or Phase 0 task candidate. Proposal sets that differ only by effort level (for example easy / medium / hard) are weak by default. They are acceptable only when each option represents a materially different strategic direction, and that difference is stated explicitly.

The labeled proposal taxonomy is required in proposal rounds only; the final RFC doc should capture the chosen direction and materially relevant alternatives in the normal Decision and Alternatives Considered sections without needing to preserve the labels verbatim.

Then request user feedback. Round 1 is incomplete without explicit user input.

Step 4: Draft RFC (After Approval)

After user approves the recommended direction:

1. Determine next RFC id:

tools/rfc.rs next-rfc-id

2. Create RFC draft from template:

tools/rfc.rs create-rfc-doc \
  --title "RFC title" \
  --slug "rfc-title" \
  --auto-id

3. Keep frontmatter as status: draft during draft discussion.
4. In ## Implementation Phases, initialize each phase tracking pair as placeholders:
   • Task Doc: docs/tasks/TBD.md
   • Task Issue: #0 These placeholders must be replaced later when concrete task docs/issues are created.
5. For each non-trivial phase, include concise phase-design bullets when useful:
   • Prerequisites: only the conditions that must be true before this phase can safely start.
   • Phase-local Choices: decisions intentionally left to that phase's task design. Do not restate previous phase summaries. Keep these bullets focused on what the current phase needs or may decide locally.

If backlog docs are provided as source context, include them under Design Inputs -> Source Backlogs.

Step 5: Round 2 (Draft Revision)

Revise the draft with user feedback and finalize:

• goals/non-goals
• scope boundaries
• interfaces/contracts
• implementation phases
• alternatives considered (with rejection rationale)
• risks and test strategy

For phased RFCs, revise each phase so its prerequisites and phase-local choices are actionable for downstream task creation. Use these bullets only when they add signal; they should be concise, current-phase-specific, and should not duplicate the preceding phase's After This Phase text.

When test strategy includes enforced timeouts or hang detection:

• treat cargo-nextest as the repository's authoritative test runner;
• use docs/process/unit-test.md for the test workflow and .config/nextest.toml for timeout and hang-detection behavior; and
• define runner or configuration changes only when the RFC intentionally changes the existing test workflow.

Validate structure before formalization:

tools/rfc.rs validate-rfc-doc --doc docs/rfcs/0006-example.md --stage formal

Step 6: Require Explicit Approval Before Formalization

Ask for explicit approval before changing draft to formal status. Do not infer approval from silence.

Formal status transitions:

• Default: draft -> proposal
• Use accepted only with explicit user decision.

rfc resolve Required Flow

Use rfc resolve only after implementation tasks and tests are complete.

1. Update RFC Implementation Phases with concrete outcomes.
2. Ensure each phase has updated Implementation Summary.
3. Ensure linked task docs contain Implementation Notes.
4. Create/link follow-up backlog docs for intentionally deferred phase work when implementation surfaces issues that should not disrupt the current program step.
   • Use $backlog create and include:
     • Deferred From: current RFC doc plus the relevant task doc/phase when applicable.
     • Deferral Context: why the work is deferred now, what current implementation learned, and what future planning should revisit or prefer.
5. Resolve related backlogs with explicit per-item confirmation.
6. Update RFC status to implemented (or superseded if applicable).
7. Run the strict completion precheck:

tools/rfc.rs precheck-rfc-resolve --doc docs/rfcs/0006-example.md

For legacy RFC docs that do not follow parseable modern phase format, use fallback:

tools/rfc.rs precheck-rfc-resolve --doc docs/rfcs/0002-legacy.md --allow-legacy

Resolve + Task Integration

$task-resolve must always check RFC linkage. If a resolved task is an RFC sub-task, update the related phase during $task-resolve. Use:

tools/task.rs resolve-task-rfc --task docs/tasks/000123-example.md

This command enforces parent-RFC check and phase sync when applicable.

Output Quality Bar

Ensure every RFC is:

1. Decision-complete for implementation direction.
2. Explicit about goal, scope, and change direction.
3. Grounded in docs/code/conversation references.
4. Explicit about alternatives and rejection rationale.
5. Phase-structured for downstream task/issue tracking, including concise prerequisites and phase-local choices for phases that need them.
6. Based on proposal rounds that compare meaningfully different strategic directions, not just effort tiers.

Reference

Read references/workflow.md for detailed gate checklist and section-level expectations.