encero-systems/incan / .agents/skills/add-learning
add-learning
VerifiedAdd 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:
| 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/Readis 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-learningnote 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 467k | Updated | Claude CodeCodex | Verified | Install |
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |