Documentation menu
Learnings: nid learn
Agents make the same mistakes from run to run: they reach for npm in a pnpm repo, read
a file at a path that does not exist, or ask for an approval you always deny.
nid learn reads what your teams already did, finds what failed and what then
worked, and writes short project learnings into AGENTS.md, CLAUDE.md or
CLAUDE. Agents read those files when they start, so the next run skips the
mistake. The cost of that first mistake is tokens, so fewer repeats mean fewer tokens.
nid learn # preview: this repo's team
nid learn web # preview: group web
nid learn --all # preview: every group, merged per repository
nid learn --apply # write AGENTS.md
nid learn --target CLAUDE.local.md --applyGroups removed with nid rm are still learnable: rm archives their history (unless
--purge), and nid learn <group> and --all read the archive. rm also adds the
learnings to project memory.
A preview is the default and writes nothing. It prints the section as it would be
written and how many bullets are new, updated or kept. Add --apply to write it.
What it looks for#
nid learn mines the daemon's event log for every agent and vendor (Claude Code,
Codex, ACP agents), plus approvals, board notes and tasks:
| Learning | Evidence |
|---|---|
| Commands | A shell command fails and a related command then succeeds in the same session. The program changed and the arguments are similar (npm test → pnpm test), or an interchangeable program replaced it after a "command not found" error (python → node). Or the same program got corrected arguments after an invocation error (Missing script, unknown option, ERR_PNPM_*). A build or test that fails and later passes with the same command is not a learning. |
| Paths | A file tool (Read, Edit, Write, ...) fails with "not found" and a file with the same name at another path works next. Paths are made repository-relative, so every worktree's evidence counts together. |
| Denied approvals | Approval requests that were denied, by title. |
| Review feedback | The notes of every review "request changes" (identical notes from several rounds count once). |
| Stalled tasks | Tasks that nid released back to open after a stall or a rate limit, with the reasons. |
| Merge-conflict hotspots | Files named in integration or sync conflicts more than once. |
Each bullet ends with its evidence count and the agents it came from, for example
_(3×, claude, codex)_. The same learning from several sessions, vendors or groups is
one bullet. The most frequent 20 per kind are written.
The managed section#
nid writes only between two markers and leaves everything else in the file byte-for-byte unchanged:
<!-- nid:learn start -->
## Project learnings (nid learn)
...
### Commands
- Use `pnpm`, not `npm` (`npm test` failed (Missing script: test); `pnpm test` worked). _(3×, claude, codex)_ <!-- learn:command:npm=>pnpm -->
<!-- nid:learn end -->If the file does not exist, it is created. Without the markers, the section is added at the end. Running it again merges the section and does not add a second copy:
- Each bullet carries a hidden key. A re-run updates matching bullets and adds new ones.
- Bullets from earlier runs whose evidence has since been pruned from the event log (undefined) are kept, and counts never go down.
- Bullets you add inside the section without a key are kept under "Other". To remove a learning for good, fix its cause. To change one, edit outside the markers.
- With the same evidence, a re-run leaves the file byte-identical.
Incomplete or out-of-order markers stop the command with an error and change nothing.
Learn after DONE#
When the compression setting has learnAfterDone: true, nid mines the group as soon
as its lead posts DONE. It posts a nid learn: finding on the board with the top
learnings and the command that writes them. It never writes files by itself: you review
the preview and run nid learn --apply.
It is off by default. You can set it in ~/, per group in
nid.yaml, or with /. The group setting wins:
compression:
learnAfterDone: trueA failure here never affects the DONE note. It goes to the daemon log
(nid daemon logs).