Skip to content

encero-systems/incan / .agents/skills/write-rfc

write-rfc

Verified

Draft 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.

  1. YAML-style header block
  2. Summary — one tight paragraph; the central claim
  3. Core model (optional) — for complex RFCs: numbered foundation + mechanism list
  4. Motivation — the pain points that make this RFC necessary
  5. Goals — bullet list of what this RFC does
  6. Non-Goals — explicit exclusions (equally important as Goals)
  7. Guide-level explanation — how users think about and use the feature
  8. Reference-level explanation — precise normative rules
  9. Design details — syntax, semantics, interaction with existing features, compatibility
  10. Alternatives considered — what was rejected and why
  11. Drawbacks — honest trade-offs
  12. Implementation architecture (non-normative, optional) — recommended internal approach
  13. Layers affected — which compiler/tooling layers are touched
  14. 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.
  • Issue links to the governing issue; leave it as — until that issue is filed.
  • RFC PR records 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 against is 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 in is 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 just RFC 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 incan language 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.rs to handle …"
  • "Add a field to FunctionInfo named …"
  • "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 behavior
  • should / should not — recommended behavior
  • may — 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 against and Shipped 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 incan language tag
  • Reference-level explanation uses normative language
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall