Rfc Workflow

RFC and Specification Workflow

This skill covers the practical RFC and spec integration workflow.

RFC Directory Structure

rfcs/src/NNNN-feature-name/
├── README.md     # The RFC document (design, motivation, examples)
├── impl.md       # Implementation progress tracking
└── todo.md       # Session-specific work tracking and context

Create new RFCs with: cargo xtask rfc new feature-name

Spec Paragraph Authoring

Spec paragraphs live in spec/src/ using MyST directive syntax.

Block directives

:::{spec} local-name tag1 tag2
Paragraph content describing one testable behavior.
:::

Tags:

• rfcNNNN — Links paragraph to an RFC (e.g., rfc0001)
• unimpl — Feature is specified but not yet implemented
• No tag for the local name means the ID comes from headings only

Inline sub-paragraphs

Inside a block, mark sub-items with inline spec tags:

:::{spec} rfc0001
String literals support these escape sequences:

* {spec}`backslash` `\\` produces a literal backslash.
* {spec}`newline` `\n` produces a newline.
:::

Each {spec}`name` creates a sub-paragraph with its own ID. Tags like unimpl can follow the name: {spec}`triple-quoted unimpl`.

Paragraph ID format

file-prefix.heading-segment.local-name.inline-name

• File prefix: from path (e.g., syntax.string-literals)
• Heading segments: H2+ headings, lowercased, spaces → hyphens
• Local name: from :::{spec} local-name
• Inline name: from {spec}`name`

Workflow: When to Put Spec Paragraphs Where

Design is mature → Author directly in spec/src/ with rfcNNNN unimpl tags. This is the preferred approach — it validates the spec structure early.

Design is still evolving → Draft in the RFC's spec.md, then move to spec/src/ during implementation.

The key insight: if you know enough to write a spec paragraph, put it in the spec. The unimpl tag makes it clear it's not yet implemented.

Implementation Tracking

impl.md

Track implementation progress in the RFC's impl.md:

# Implementation Progress

## Status: In Progress

### Completed
- [x] Spec paragraphs drafted in spec/src/
- [x] Basic string literal parsing

### In Progress
- [ ] Triple-quoted string support

### Not Started
- [ ] String interpolation

todo.md

Track session-specific context in todo.md:

# Current Session

## Focus
What we're working on right now

## Next Steps
- Specific actionable items

## Open Questions
- Things still being figured out

Cross-Referencing

• Tests → Spec: #:spec syntax.string-literals.escape-sequences.backslash
• Spec → RFC: rfc0001 tag on :::{spec} directives
• RFC → Spec: Reference spec section in RFC README.md

Keep these synchronized. When adding a new spec paragraph, check if tests exist. When writing tests, add the #:spec annotation.

Implementation Workflow

When implementing an RFC feature, follow this cycle for each piece of work:

1. Implement the feature in the compiler
2. Write tests with #:spec annotations
3. Remove unimpl from the spec paragraph tag
4. Update the RFC's impl.md — check off completed items, add new items discovered during implementation

Keep impl.md current as you go. It's the living record of what's done and what's next — don't wait until the end of a session to update it.