Review RFC — Incan Project

Workflow

1. Read the RFC document in full.
2. Read the Status: field in the header — it controls which checklists apply (see Status-aware checks below).
3. Verify the RFC number is not already taken — check workspaces/docs-site/docs/RFCs/ for conflicts.
4. Work through the universal checklists (1–5), then the status-specific checklist for the RFC's current status.
5. Fix issues directly (edit the file); RFC review is an editing task, not just a report.
6. If no GitHub issue exists yet, ask the user before creating one (see Issue creation). Once created, record the issue URL in the RFC header's Issue: field.
7. If review materially changes RFC filenames, numbers, or status/location (for example superseding or splitting an RFC), update RFC cross-references and regenerate the docs-site RFC snippets/index.
8. Ask before semantic restructures. Mechanical fixes, formatting cleanup, section-order repairs, and obvious lifecycle-field corrections should be applied directly. But if review suggests splitting an RFC, superseding it, renumbering it, or materially changing its scope/central design claim, stop and get explicit user confirmation before making that restructuring edit.

Status-aware checks

The RFC lifecycle has four statuses. Different sections are required — or forbidden — at each stage:

Existing In Progress and Implemented RFCs may retain an earlier inline plan for historical context. Preserve its evidence. The owning issue is authoritative for delivery work and the RFC checklist records progress.

Planned+ rule (Planned, In Progress, Implemented): the document must not contain a ## Unresolved questions heading. The design tail is ## Design Decisions only — remove or merge ## Unresolved questions at Draft → Planned (/bump-rfc).

Draft: may use ## Unresolved questions (open), ## Design Decisions (settled), or both. Keep roles honest (no open items under Design Decisions). May stay Draft with no open design work while review continues; do not invent questions.

HTML comment (Draft only): if ## Unresolved questions appears anywhere, include the EOF comment in Checklist 1; otherwise omit it.

Draft → Planned: nothing still open under ## Unresolved questions; ## Design Decisions holds the settled record; apply Planned+ rule via /bump-rfc.

Checklist 1 — Structural completeness (all statuses)

• Header block present with all eight fields: Status, Created, Author(s), Related, Issue, RFC PR, Written against, Shipped in.
• RFC PR is — unless implementation PRs exist. Every linked PR implements RFC scope; proposal PRs and documentation-only PRs must not appear in this field. Verify the linked PR changes rather than inferring implementation from its title.
• Written against: reflects the Incan version that was current when the RFC was authored (never a future or planned version).
• Shipped in: is — for Draft/Planned/In Progress; only filled for Implemented.
• Sections follow canonical order: Summary → (Core model) → Motivation → Goals → Non-Goals → Guide-level explanation → Reference-level explanation → Design details → Alternatives considered → Drawbacks → (Implementation architecture) → Layers affected → (progress checklist, In Progress/Implemented only) → Design Decisions / Unresolved questions (Draft: one or both, any order; Planned+ rule after that).
• Draft/Planned only: No section named "Implementation Plan", "Suggested rollout", or similar. Prescriptive task steps belong on the owning issue.
• In Progress: verify that the linked issue records the implementation plan.
• In Progress/Implemented only: "Checklist" (or "Progress Checklist") section present with - [ ] / - [x] items.
• Status: Draft and ## Unresolved questions present → EOF HTML comment: <!-- Rename this section to "Design Decisions" once all questions have been resolved. An RFC cannot move from Draft to Planned until no unresolved questions remain. -->

Checklist 2 — RFC cross-references (all statuses)

• No [RFC NNN] markdown reference-link syntax anywhere (header or body).
• All RFC cross-references use plain text: RFC NNN or RFC NNN (description).
• No dangling link definitions at the bottom of the file for RFC references.

Checklist 3 — Formatting (all statuses)

• No hard-wrapped prose paragraphs. Lines must not end mid-sentence at ~80–120 chars. Reflow each paragraph to a single unbroken line.
• Incan code blocks use the incan language tag (not python, rust, or untagged).
• Tables render cleanly with no broken Markdown.
• No <!-- REVIEW: ... --> comments left unaddressed in the file.

Checklist 4 — Content quality (all statuses)

• Summary is a single tight paragraph stating the central claim.
• Goals and Non-Goals are balanced — Non-Goals make explicit what is out of scope.
• Guide-level explanation uses realistic, typed Incan code examples that are clear and well-explained without being excessive. It should be immediately obvious to the reader what the feature achieves.
• Prose flows naturally with no duplicated concepts across sections.
• Reference-level explanation uses normative language (must, must not, should, may).
• "Layers affected" describes impacts (not task steps); lists only layers that are actually affected.
• "Alternatives considered" includes a rationale for rejection for each alternative.
• No prescriptive implementation prose in the design sections. The RFC must not reference specific internal files, function names, struct fields, or data structures in the design sections. Track those implementation details on the owning issue. If found in design sections, rewrite as a normative contract statement or remove.
• No v1 / V1 shorthand. RFCs should define their own north-star contract, not an implementation phase labeled as "v1". Rewrite phrases like "v1 does X" or "the stable v1 renderer" as concrete RFC commitments ("this RFC requires X", "the required renderer is Markdown") or explicit future-extension framing ("a follow-up RFC may define Y").
• Ambition check. RFCs should be end-to-end and favor complete solutions over incremental stubs. Flag if the RFC is too dismissive or handwavy about hard parts. Equally, if the RFC is ambitious, verify that the ambition is well-motivated, clearly explained, and not excessive.
• Coupling check. If an RFC bundles a general language feature with a specific stdlib or product surface, challenge whether those concerns should stay together. If the coupling is not clearly justified in the document, flag it or recommend a split/supersession path.

Checklist 5 — Confidentiality (all statuses)

• No internal or unreleased project names. Replace with generic descriptions: "future query language surfaces", "purpose-built libraries", etc.
• No links or citations to internal paths (__strategy__/, research notes, pre-RFC documents, or any folder outside the public repository). Describe the concept inline instead.

Checklist 5b — RFC graph hygiene (all statuses)

• If an RFC is renamed, renumbered, split, or superseded, update inbound references in active RFCs and docs so they point at the new target rather than the stale file.
• If an RFC moves between active and closed/ folders, regenerate workspaces/docs-site/docs/_snippets/rfcs_refs.md and workspaces/docs-site/docs/_snippets/tables/rfcs_index.md.
• If the RFC index generator fails locally, fix the generator or note the blocker; do not leave the docs index knowingly stale after RFC lifecycle edits.

Checklist 6 — Draft-specific

• ## Unresolved questions and/or ## Design Decisions — open vs settled as in Status-aware checks; no invented questions.
• EOF HTML comment matches Checklist 1 iff ## Unresolved questions exists.
• Do not use Planned while ## Unresolved questions still lists open items.

Checklist 7 — Planned-specific

• Planned+ rule satisfied (bump-rfc); Design Decisions has no open bullets.
• GitHub issue labeled feature (not RFC).

Checklist 8 — In Progress-specific

• The owning issue records the delivery plan. The RFC may retain an existing inline plan.
• "Checklist" (or "Progress Checklist") section present with - [ ] / - [x] items, grouped by area (e.g. Spec, Parser/AST, Typechecker, Lowering/IR, Emission, Stdlib/Runtime, Tests, Docs).
• At least one checklist item is - [x] (otherwise the RFC has not actually started).
• Shipped in: is still —.

Checklist 9 — Implemented-specific

• All checklist items are - [x] (no open - [ ] items).
• Shipped in: is filled with the actual release version (not —, not TBD).
• Release notes updated in workspaces/docs-site/docs/release_notes/.

Common issues found in practice

Issue creation

Only create an issue if one does not already exist. Always ask the user first.

Create the issue with gh issue create. Include at minimum: a one-paragraph summary, the motivation, and the path to the RFC document. Use the RFC label and any relevant area labels (incan language semantics, incan compiler, incan stdlib, incan tooling).

gh issue create \
  --title "RFC NNN: <Title>" \
  --label "RFC" \
  --body "..."

See .github/ISSUE_TEMPLATE/rfc_proposal.yml for the fields the template covers — use those as a guide for what to include in the body.

Once the issue is created, record its URL in the RFC's Issue: header field.

RFC lifecycle

Use the /bump-rfc skill to perform status transitions correctly.