encero-systems/incan / .agents/skills/review-rfc
review-rfc
VerifiedReview an Incan RFC document for formatting, structural, and content issues before GitHub submission. Use when the user asks to review an RFC, check an RFC for problems, prepare an RFC for submission, or says /review-rfc.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.8 KB |
SKILL.md
View on GitHub---
name: review-rfc
description: Review an Incan RFC document for formatting, structural, and content issues before GitHub submission. Use when the user asks to review an RFC, check an RFC for problems, prepare an RFC for submission, or says /review-rfc.
---
# 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:
| Status | Delivery plan | RFC progress checklist | `Shipped in:` | Design-status tail |
| --- | --- | --- | --- | --- |
| `Draft` | Outside the RFC | Absent | `—` | Open questions and/or decisions |
| `Planned` | Outside the RFC | Absent | `—` | Planned+ rule |
| `In Progress` | Tracked on the owning issue | Required | `—` | Planned+ rule |
| `Implemented` | Retained on the owning issue | Complete | Release version | Planned+ rule |
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 | Fix |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `[RFC NNN]` reference links without definitions | Convert to plain text `RFC NNN` |
| Section named "Implementation plan" in a Draft or Planned RFC | Remove or defer to GitHub issue; keep only "Layers affected" |
| Missing issue plan or RFC checklist for In Progress | Apply `/bump-rfc`: record the plan on the issue and add the checklist to the RFC |
| Prose references specific files or functions (`calls.rs`, `FunctionInfo`, etc.) | State the design contract in the RFC and put delivery details on the owning issue |
| `v1` / `V1` phrasing such as "v1 does X" or "stable v1 renderer" | Replace with concrete RFC commitments or "a follow-up RFC may define X" future-extension framing |
| Hard-wrapped prose (lines ending mid-sentence) | Reflow each paragraph to a single line |
| `Shipped in:` filled for a Draft/Planned/In Progress RFC | Set to `—`; only fill once the feature is released |
| `Shipped in:` still `—` for an Implemented RFC | Fill with the actual release version |
| Missing "Layers affected" section | Add with affected layers from Parser, Typechecker, Lowering, Emission, Stdlib, Formatter, LSP |
| **Planned+** still has **`## Unresolved questions`** | **Planned+ rule** — fix via **bump-rfc** merge/rename steps |
| `<!-- REVIEW: ... -->` comment left in file | Address the comment and remove it |
| Internal project name mentioned | Replace with a generic description |
| Link to internal path (`__strategy__/`, research notes) | Remove the link; describe the concept inline |
| Code blocks untagged or wrongly tagged | Add `incan` language tag |
| One RFC mixes a general feature and a specific library proposal | Recommend split/supersession or justify the coupling explicitly |
| RFC file moved or status changed but docs index still points at old path | Update references and regenerate RFC snippets/index |
| Review flags Draft for "no open questions" | Valid during review; **Draft** rules above |
---
## 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`).
```bash
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
| Status | Meaning | Trigger |
| ------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `Draft` | Design and/or review in flight | New RFCs start here; may list open questions, or none while settled design awaits review before bump |
| `Planned` | Design settled; ready for implementation | **Planned+ rule**; review complete; user confirms (`/bump-rfc`) |
| `In Progress` | Active implementation underway | Implementation started; the issue carries the plan and the RFC carries the progress checklist (see `/bump-rfc`). |
| `Implemented` | Implementation complete and shipped | All checklist items checked, `Shipped in:` filled, release notes updated (use `/bump-rfc`) |
Use the `/bump-rfc` skill to perform status transitions correctly.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |