learnings
The project's episodic memory: a timestamped ledger of rules paid for with real outages and near-misses, one entry per incident, plus `work/`: the plans, designs and open thoughts behind planned or pa
SKILL.md.agents/skills/learnings/SKILL.md
GitHubProject learnings: the episodic ledger
Every rule this repository paid for with downtime or a near-miss is one entry in a timestamped, append-only ledger. The ledger is the full history, in the order it was learned.
| Path | What it is |
|---|---|
MEMORY.md |
The index. One line per entry, newest first: recorded time (UTC) and the rule. Generated. |
entries/<YYYY-MM-DDTHHMMSSZ>-<slug>.md |
One entry. The filename timestamp is when it was recorded. |
scripts/new-entry.sh |
Starts a new entry stamped with the current UTC time and rebuilds the index. |
scripts/index.sh [--check] |
Rebuilds MEMORY.md from entries/, or fails if it is stale. |
work/<topic>/ |
Plans, designs and open thoughts for planned, in-flight or parked work. Living documents, not part of the ledger. Index and rules: work/README.md. |
Entries recorded before 2026-09-25 were split out of the old single-file register. Their
recorded time is the commit that first wrote them (commit in the frontmatter).
Recall: before you touch a surface
- Search the index and the full text for the surface you are about to change:
Use the words of the surface:grep -i '<keyword>' .agents/skills/learnings/MEMORY.md grep -ril '<keyword>' .agents/skills/learnings/entries/migration,CONCURRENTLY,deploy-dev,promote,wake,Stop,gateway,preview, the file or route name. - Read every matching entry in full. Obey its Rule, and keep its Enforcement green.
Done when every entry that names the surface you touch has been read.
Record: after an incident or near-miss resolves
Record in the same session. An incident that leaves no entry is not finished.
- Start the entry:
.agents/skills/learnings/scripts/new-entry.sh "<the rule, as an imperative>" [incident-date] - Fill the four sections the script writes:
- Rule: the imperative a developer can obey while coding.
- Trigger surface: what someone is doing when it applies.
- Incident: date, version or PR, blast radius, in one to three lines.
- Enforcement: the test, lint, or CI gate that goes red when the rule breaks. An entry with an enforcer is a fact. One without is a TODO: name the enforcer to build.
- Commit the entry and
MEMORY.mdin the same commit.
Done when scripts/index.sh --check exits 0 and the entry is committed.
Ledger rules
- Append-only. After an entry merges, its text does not change. When a rule changes,
or an Enforcer moves or is retired, record a new entry. Put
supersedes: <entry filename>in its frontmatter and state what changed. - One entry, one file, one timestamp.
recordedin the frontmatter matches the filename. It is the time of recording, never the incident date. The incident date goes inincident_date. MEMORY.mdis generated. Runscripts/index.shafter any entry change. It merges with git'suniondriver, so two branches that each add an entry do not conflict. A GitHub squash merge keeps a branch's index line where the branch put it, so the order onmaincan drift until the nextindex.shrun.index.sh --checkandtests/unit/learnings-ledger.test.tscompare the lines, not their order: they fail on a missing, extra, or retitled index line, or a malformed entry.- Keep an entry short: about 8 to 20 lines. Deep detail belongs in the PR body.
Cite the PR number (
PR #1234). - An entry is self-contained. The ledger in
entries/is the only incident record. Do not write a separate incident, RCA, spec, or runbook file, and do not link one. The repository has nodocs/tree, and the pre-commit hook rejects new files under it. - Synthetic identifiers only. An entry is committed text, so the AGENTS.md customer-data
rule applies. Write "a customer", "an enterprise workspace",
<session_id>.