Skip to content

encero-systems/incan / .agents/skills/add-learning

add-learning

Verified

Add a new learning to the agent learnings file. Use when the user says /add-learning, asks to record a lesson, or when an implementation produced a reusable insight worth preserving for future agents.

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:

SectionAdd here if the learning is about...
General pipeline pitfallsTypechecker/lowering/emission interactions, Program struct, type display
Testing strategyWhich tests to write, test coverage gaps, snapshot patterns
Parser and lexer patternsToken handling, bracket depth, warning infrastructure, soft keywords
Stdlib and registry patternsSTDLIB_NAMESPACES, stub vs wiring, runtime facades
Wiring: CLI and LSPWarning surfacing, feature gates, command coverage
Generic bounds and extern functionsBounds storage, extern diagnostics, shared helpers
Docs and RFC toolingRFC 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
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 319kUpdated Claude CodeCodexVerifiedInstall