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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.2 KB |
SKILL.md
View on GitHub---
name: add-learning
description: 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:
| 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:
```markdown
- **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:
```markdown
- **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
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: 472k | 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: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |