encero-systems/incan / .agents/skills/write-rfc
write-rfc
VerifiedDraft a new RFC document for the Incan language project. Use when the user asks to write, create, or draft an RFC, or wants to propose a new language feature or infrastructure change for Incan.
Write RFC — Incan Project
Canonical section order
Every Incan RFC must follow this section order. Omit optional sections only when they genuinely add nothing.
- YAML-style header block
- Summary — one tight paragraph; the central claim
- Core model (optional) — for complex RFCs: numbered foundation + mechanism list
- Motivation — the pain points that make this RFC necessary
- Goals — bullet list of what this RFC does
- Non-Goals — explicit exclusions (equally important as Goals)
- Guide-level explanation — how users think about and use the feature
- Reference-level explanation — precise normative rules
- Design details — syntax, semantics, interaction with existing features, compatibility
- Alternatives considered — what was rejected and why
- Drawbacks — honest trade-offs
- Implementation architecture (non-normative, optional) — recommended internal approach
- Layers affected — which compiler/tooling layers are touched
- Unresolved questions — open design questions
RFC numbering
Check workspaces/docs-site/docs/RFCs/ for the highest existing RFC number and increment by one. Do not reuse a number, even for a closed or superseded RFC.
Header block template
# RFC NNN: Title
- **Status:** Draft
- **Created:** YYYY-MM-DD
- **Author(s):** Name (@handle)
- **Related:**
- RFC NNN (brief description)
- **Issue:** —
- **RFC PR:** —
- **Written against:** v0.X
- **Shipped in:** —
Rules:
- "Related" entries are plain text —
RFC NNN (description)— never markdown reference links. Issuelinks to the governing issue; leave it as—until that issue is filed.RFC PRrecords only the PR or PRs that implement the RFC. Leave it as—until implementation PRs exist. Never put the proposal PR or a documentation-only PR in this field; opening an RFC proposal does not populate it.Written againstis the Incan version that was current when the RFC was drafted — the version whose syntax and semantics the RFC assumes. It records context, not intent. It never changes after the RFC is accepted.Shipped inis left as—until the feature is actually released. Never set it speculatively to a planned version — that belongs on the GitHub issue.
"Layers affected" section
This section describes what is touched, not how to implement it step by step. Prescriptive task lists belong in GitHub issues, not RFCs.
Never name this section "Implementation plan", "Suggested rollout", or similar.
## Layers affected
- **Parser / AST**: new syntax or AST nodes needed
- **Typechecker / Symbol resolution**: semantic checks or symbol table changes
- **IR Lowering**: how the new construct lowers to IR
- **Emission**: what changes in generated Rust output
- **Stdlib / Runtime (the `incan_std_<component>` facets)**: runtime-side changes
- **Formatter**: new syntax needs formatter support
- **LSP / Tooling**: completion, hover, diagnostics impact
Omit layers that are genuinely unaffected.
RFC cross-references
Never use markdown reference-link syntax for RFC cross-references. Always use plain text.
- ✅
RFC 005 (Rust interop)or justRFC 005 - ❌
[RFC 005]— renders as broken literal text without a link definition
Formatting rules
- No hard wraps in prose paragraphs. Each paragraph is a single unbroken line; let the renderer wrap. Hard line-breaks at ~100 chars cause WYSIWYG display issues in docs.
- Code blocks in Incan examples use the
incanlanguage tag. - Rustdoc
//////!comments inside code examples: ≤ 120 chars per line.
RFCs are not implementation tickets
An RFC describes what the language should do and why — not how the compiler internals should be changed to achieve it.
Allowed:
- Describing the user-facing surface (syntax, semantics, type rules, error messages)
- Sharing motivating research, prior art, or design alternatives
- Defining normative rules a future implementer must satisfy
- Non-normative architecture notes that describe a recommended shape (clearly labeled as such)
Not allowed:
- "Change
check_expr/calls.rsto handle …" - "Add a field to
FunctionInfonamed …" - "In
lower/decl/functions.rs, match on …" - Any prose that reads like a diff or a task list targeting specific files, functions, or data structures
If you find yourself writing file paths or function names, stop and ask: am I describing the contract, or am I writing the implementation? The RFC owns the contract. The implementation lives in the issue tracker and the code.
Normative language in reference-level explanations
Use RFC-style normative language:
must/must not— required/prohibited behaviorshould/should not— recommended behaviormay— permitted but not required
Unresolved questions
- List one open design question per bullet.
- Each should be answerable before Draft → Planned.
- End the file with:
<!-- 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. -->
Confidentiality
Never mention internal project names (any unreleased project) in RFC documents. Use generic descriptions such as "future query language surfaces" or "purpose-built libraries".
This also covers internal file references: do not link to or cite internal paths such as __strategy__/, research notes, pre-RFC documents, or any folder not part of the public repository surface. If inspiration came from an internal document, describe the concept in the RFC itself without referencing the source.
Pre-submission checklist
- RFC number is one higher than the current highest in
workspaces/docs-site/docs/RFCs/ - Status is
Draft(all new RFCs start as Draft) - Sections in canonical order
- Header block complete (all eight fields, including
Written againstandShipped in: —) - "Related" entries use plain text, not
[RFC NNN]links - No hard-wrapped prose paragraphs
- "Layers affected" present (not "Implementation plan")
- No prescriptive implementation prose (no internal file paths, function names, or struct fields)
- No confidential project names or internal path references
- Unresolved questions present with closing comment
- Incan code blocks use
incanlanguage tag - Reference-level explanation uses normative language
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |