Add Learning — Incan Project

When to use

Add a learning when an implementation taught a durable, generalizable lesson that a future agent would get wrong without it. Good learnings are:

• Pitfalls where code passes one stage but fails another
• Non-obvious wiring requirements (e.g., "if you change X, you must also update Y")
• Patterns that look correct but produce subtle bugs
• Architectural constraints that aren't obvious from the code alone

Do not add:

• Implementation details specific to a single feature that are already in the code
• API documentation (that belongs in rustdoc)
• Temporary workarounds or known bugs (those belong in GitHub issues)

Workflow

Step 1: Identify the right section

Read .agents/learnings.md and determine which existing section the learning belongs in:

Section	Add here if the learning is about...
General pipeline pitfalls	Typechecker/lowering/emission interactions, Program struct, type display
Testing strategy	Which tests to write, test coverage gaps, snapshot patterns
Parser and lexer patterns	Token handling, bracket depth, warning infrastructure, soft keywords
Stdlib and registry patterns	STDLIB_NAMESPACES, stub vs wiring, runtime facades
Wiring: CLI and LSP	Warning surfacing, feature gates, command coverage
Generic bounds and extern functions	Bounds storage, extern diagnostics, shared helpers
Docs and RFC tooling	RFC graph maintenance, docs generators, index/reference regeneration

If no existing section fits, create a new one with a descriptive heading.

Step 2: Write the learning

Format as a bold-label bullet:

- **Concept in 3-5 words**: Explanation of the insight, why it matters, and what goes wrong without it. Include the triggering context (RFC number, issue number) in parentheses if applicable.

Guidelines:

• Lead with the principle, not the specific feature that taught it.
• Keep it to 1-2 sentences. If it needs more, it might be too specific.
• Include enough context that an agent can act on it without reading the original RFC/issue.

Step 3: Append to the file

Add the bullet to the appropriate section in .agents/learnings.md. Maintain alphabetical or logical ordering within the section.

Step 3.5: Spot-check 1-2 existing entries in the same section

.agents/learnings.md is never mechanically checked against the code it describes — the only thing that catches a stale learning is an agent noticing while already in that section. So do that noticing on purpose, every time:

• While you're in the section from Step 1, pick 1-2 other entries that name a concrete file path, function, struct, or pattern (not every entry does — skip pure-principle ones).

• Quickly confirm the named thing still exists and the described behavior still matches (a grep/Read is usually enough — this is a spot-check, not a re-audit).

• If an entry is stale (the file moved, the function was renamed, the described behavior changed), do not silently delete or rewrite it. Mark it in place so the correction itself is visible:

  - **Concept in 3-5 words**: ~~Original explanation~~ **[SUPERSEDED YYYY-MM-DD]**: what's true now, and why the original stopped applying (link the RFC/issue/commit that changed it if there is one).
  

  This keeps a record that the learning was wrong and got corrected — which is more useful to a future agent than a silent edit, and is itself worth an /add-learning note if the reason it went stale is a generalizable lesson on its own.

• If nothing in your quick check turns out stale, don't add noise — no need to annotate entries that are still accurate.

Step 4: Verify

Read back the file to confirm:

• The new bullet is in the right section
• It doesn't duplicate an existing learning
• It's generalizable (would help with future work, not just the current task)
• Step 3.5 happened — either something got marked [SUPERSEDED ...] or you confirmed the spot-checked entries are still accurate