@adia-ai/adia-ui-forge 0.1.3 → 0.8.0

package/skills/adia-ui-ops/references/recipes/cold-start-harvest.md

@@ -1,263 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - greenfield-setup.md
-  - audit-existing-repo.md
-  - concurrent-learnings-merge.md
-  - recommend-then-validate.md
-  - ../audit-patterns/redundancy-detection.md
-  - ../audit-patterns/staleness-tooling.md
-  - ../doc-types/adr-pattern.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices
-status: research-verified
----
-
-# Cold-start harvest (importing existing learnings into `ops-repo`)
-
-> **The premise.** Existing repos already have buried learnings: a fat `CLAUDE.md` from 2024, ADRs trapped in PR descriptions, post-mortems in Slack screenshots, an old `NOTES.md` in root, multiple competing convention docs. The destructive default — *delete it all and start fresh* — loses signal. The trusting default — *import everything* — imports stale and contradictory content. Cold-start harvest is the opinionated middle path: **inventory, triage, archive-the-junk, rehome-the-good, supersede-the-conflicts, preserve-the-archaeology**.
-
-## How this differs from `greenfield-setup.md`
-
-| | Greenfield | Cold-start harvest |
-|---|---|---|
-| Existing docs | None | Many, varying age and quality |
-| Conflicts | Impossible | Likely; resolution is the hard part |
-| Default disposition | Create canonical artifacts | Triage existing artifacts; *then* create canonical |
-| Time | Hours | Days (with iteration) |
-| Bounding | Linear procedure | Heuristic-bounded — don't try to harvest everything |
-
-If your repo is genuinely new, use `greenfield-setup.md`. If it's older than ~3 months and has any documentation at all, use this recipe.
-
-## Where the buried learnings live (inventory targets)
-
-```bash
-# Likely-stale top-level files
-find . -maxdepth 3 -type f \( \
-  -name '*NOTES*' -o -name '*WIP*' -o -name '*PLAN*' -o \
-  -name '*OLD*' -o -name '*LEGACY*' -o -name '*BACKUP*' -o \
-  -name 'STYLEGUIDE*' -o -name 'CONVENTIONS*' \
-\)
-
-# Markdown not in canonical locations
-find . -name '*.md' -type f \
-  -not -path './.brain/adrs/*' \
-  -not -path './.brain/postmortems/*' \
-  -not -path './.brain/runbooks/*' \
-  -not -path './.brain/architecture/*' \
-  -not -path './.brain/archive/*' \
-  -not -path './node_modules/*' \
-  -not -path './.git/*'
-
-# Commits that look like recorded decisions
-git log --all --grep='decided\|migrate\|switch from\|chose\|deprecate' \
-  --pretty=format:'%h %s' | head -50
-
-# PR bodies with ADR-shaped content (requires gh CLI)
-gh pr list --state all --limit 200 --json number,title,body --jq '
-  .[] | select(.body | test("## (Status|Decision|Consequences)"; "i"))
-       | {n: .number, t: .title}'
-
-# Issues labeled as incidents / postmortems
-gh issue list --state all --label 'incident,post-mortem,postmortem' --limit 100
-```
-
-## The triage matrix
-
-For each found artifact, classify:
-
-| Disposition | Meaning | Default action |
-|---|---|---|
-| **`keep`** | Already in the right place, current, correct | Leave alone; date-stamp if needed |
-| **`rehome`** | Good content, wrong location | Move to canonical location with provenance |
-| **`archive`** | Out of date but historically valuable | Move to `.brain/archive/` with provenance |
-| **`supersede`** | Conflicts with another artifact | Write resolving ADR; mark both `Superseded` |
-| **`reconcile`** | Two artifacts both partially correct, partially wrong | Most expensive: extract truths, write merged canonical, archive originals |
-| **`delete`** | Never had value (e.g., `*-copy.md`, generated junk) | Move to archive, not delete (preserve the audit trail) |
-
-### Triage rules of thumb
-
-| Found | Likely disposition |
-|---|---|
-| Current fat `CLAUDE.md` and no `AGENTS.md` | `rehome`: rename to AGENTS.md, generalize wording, demote CLAUDE.md to symlink/pointer |
-| `STYLEGUIDE.md` overlapping with AGENTS.md "Conventions" | `reconcile`: pick canonical, demote other |
-| `NOTES.md` in root | Read carefully. ADR-shaped sections → extract to `.brain/adrs/` (`rehome`); rest → `archive` |
-| `WIP_PLAN.md` | Almost always `archive`. If active work, extract goals into `docs/PLAN.md` |
-| `docs/legacy/`, `docs/old/`, `docs/_old_/` | `archive` to `.brain/archive/legacy-import-<date>/` |
-| `*_BACKUP*.md`, `*-copy*.md` | `archive` (don't delete; weird ones may have unique content) |
-| GitHub issues with `incident` / `post-mortem` label | Read each. Substantive ones → `rehome` to `.brain/postmortems/` with provenance link to original issue |
-| PR descriptions with ADR-shaped content | `rehome`: extract to `.brain/adrs/` with provenance pointer to original PR |
-| Two `Accepted` ADRs about the same subject (after rehoming) | `supersede`: human reviews, writes resolving ADR |
-
-## The 7 phases
-
-### Phase 1 — Inventory (mechanical)
-
-Run the inventory commands above. Collect into a single `.brain/cold-start-inventory.md` (transient — deleted after phase 7):
-
-```markdown
-# Cold-start inventory — 2026-04-27
-
-| Path | Last modified | Size | Triage |
-|---|---|---|---|
-| ./CLAUDE.md | 2024-09-12 | 240 lines | rehome → AGENTS.md |
-| ./NOTES.md | 2023-11-04 | 60 lines | archive (extract `### Postgres decision` → ADR first) |
-| ./STYLEGUIDE.md | 2024-03-01 | 90 lines | reconcile with `CONTRIBUTING.md` |
-| ./docs/old/architecture-v1.md | 2022-06-15 | 410 lines | archive |
-| PR #144 body | (closed 2024-08-22) | — | rehome decision section → .brain/adrs/2024-08-22-graphql-rejection.md |
-```
-
-This file is the working artifact. Update it as triage progresses.
-
-### Phase 2 — Triage (human-reviewed)
-
-Walk the inventory in time-bounded sessions. **Set a budget**: 4 hours. Stop when budget exhausted; the rest waits for next iteration. Don't try to harvest everything in one pass.
-
-Triage signals to escalate:
-- Anything that says "DO NOT MODIFY" or "SOURCE OF TRUTH" — flag for explicit confirmation before any action
-- Anything containing what looks like secrets (API keys, internal hostnames) — flag, don't process automatically
-- Anything in a language other than the repo's primary language — out of automated scope; flag for human review
-
-### Phase 3 — Bulk-archive obvious junk (PR)
-
-Anything matching the bulk-archive heuristics (legacy folders, *_BACKUP, untouched > 2 years AND unreferenced from any entry file) gets a single PR:
-
-```
-docs: cold-start harvest — bulk-archive 23 stale artifacts
-
-Moved to .brain/archive/legacy-import-2026-04-27/:
-- CLAUDE-OLD.md (last modified 2023-04)
-- NOTES_2023.md
-- docs/old/* (12 files)
-- ...
-
-No content lost — preserved with provenance.
-```
-
-Each archived file gets a `_Harvested from <original-path> on 2026-04-27 (cold-start harvest, untouched since <date>)_` line at the top.
-
-### Phase 4 — Rehome obviously-good content (per-artifact PRs)
-
-For each `rehome` disposition: separate PR, single artifact at a time.
-
-Example: `CLAUDE.md` (fat, current-ish) → `AGENTS.md`:
-
-1. `git mv CLAUDE.md AGENTS.md`
-2. Edit: replace "Claude Code" / "Claude" with "LLM coding agents (Claude Code, Codex, Devin, Cursor, Windsurf, Copilot, …)"
-3. Add `_Last reviewed: 2026-04-27_` line + `_Harvested from CLAUDE.md (cold-start)_`
-4. Create new thin `CLAUDE.md` (or symlink) per `claude-md-convention.md`
-5. PR with title `docs: harvest — rehome CLAUDE.md → AGENTS.md`
-
-For ADRs extracted from PR descriptions: each new ADR includes:
-
-```markdown
----
-date: 2026-04-27        # harvest date
-status: accepted
-harvested_from: PR #144 (closed 2024-08-22)
-original_decision_date: 2024-08-22
----
-
-# 2024-08-22-1500-graphql-rejection
-
-_Harvested from PR #144 (https://github.com/example/repo/pull/144) on 2026-04-27 during cold-start harvest. Original decision was made 2024-08-22; this ADR file backfills the artifact._
-
-## Status
-Accepted
-
-## Context
-[from PR description]
-...
-```
-
-Provenance is non-negotiable — future audits need to distinguish original artifacts from imported ones.
-
-### Phase 5 — Conflict resolution (ADR-by-ADR, human approval)
-
-After phases 3-4, run the redundancy-detection trip-wire from v1.0 against the rehomed state. Findings will surface:
-
-- Two ADRs with overlapping subject matter
-- AGENTS.md sections with internal contradiction
-- Conflicting style claims across CONTRIBUTING.md and AGENTS.md
-
-For each conflict: follow the **supersession protocol** from `concurrent-learnings-merge.md`:
-
-1. Surface the conflict
-2. Human picks resolution
-3. Write a new superseding ADR with full citation
-4. Mark originals as `Superseded by <new-ADR>` (do not delete or edit content beyond the status field)
-
-**This phase cannot be auto-applied even at `lax` strictness.** Supersession is a content decision affecting what future agents believe. The recipe forces `recommend-then-validate` with explicit human approval per supersession PR.
-
-### Phase 6 — Provenance pass
-
-Every harvested artifact must carry a provenance line:
-
-```
-_Harvested from <original-path-or-source> on 2026-04-27 (cold-start harvest)._
-```
-
-Run a sanity check: every file in `.brain/` modified during the harvest period either has a `_Last reviewed:_` line or a `_Harvested from..._` line. Files missing provenance get flagged.
-
-### Phase 7 — Re-audit
-
-Run the full audit (`audit-existing-repo.md`) against the post-harvest state. Confirm:
-
-- Promise 1 (less-wasteful): no orphans; CLAUDE.md is symlink/pointer to AGENTS.md
-- Promise 2 (token-optimized): AGENTS.md ≤200 lines
-- Promise 3 (less-stale): all docs dated; no broken cross-refs
-- Promise 4 (self-healing): hooks installed (per `self-healing-hooks.md`)
-- Promise 5 (continuously-learning): `.brain/adrs/` populated with both new and harvested ADRs; supersession chain intact
-
-If the post-audit shows any `critical` findings, return to phase 5. Iterate until clean.
-
-After phase 7 passes: delete `.brain/cold-start-inventory.md` (it's transient working state, not preserved memory).
-
-## The non-negotiables
-
-1. **No deletes.** Every disposition is `archive` (move to `.brain/archive/`) or `rehome` (move with provenance). Even the "delete" disposition in the triage matrix is implemented as archive. Future archaeology may need the original.
-2. **No silent supersession.** When two artifacts conflict, the resolution writes a NEW ADR; the originals are *marked* `Superseded`, not edited beyond the status field.
-3. **Provenance for everything imported.** No exceptions.
-4. **Time-bounded passes.** A 6-hour cold-start session is fine; a 6-week project is not. Iterate weekly until clean rather than blocking indefinitely.
-5. **Human-in-the-loop for every supersession.** Apply-mode never resolves a content conflict.
-
-## Cost-bounding heuristic
-
-Repos vary wildly in legacy-doc surface. A pragmatic floor:
-
-- **20-doc rule**: triage the 20 most-recently-modified candidate artifacts first. If they cover the substantive learnings, stop. The rest go to bulk-archive without per-artifact triage.
-- **6-month rule**: artifacts unmodified for 6 months get default-archived unless they're explicitly referenced from an active entry file.
-- **2-year rule**: artifacts unmodified for 2 years AND unreferenced get bulk-archived without review.
-- **Half-day budget per session**. If triage takes longer, split into multiple sessions across days.
-
-These rules are conservative — they preserve learnings rather than compressing them. They also don't try to be exhaustive on the first pass.
-
-## Cross-system imports (out of scope)
-
-This recipe assumes everything you want to harvest lives **in the repo today**. Not in scope:
-
-- **Slack post-mortems** — the recipe can't fetch them. Two paths: (a) one-time manual import (effort scales with volume); (b) maintain `.brain/postmortems/external-index.md` linking to authoritative external locations
-- **Notion / Confluence pages** — same
-- **GitHub issues from a different repo** — same
-- **Scattered Slack DMs / email** — never going to be harvested; the institutional knowledge that lives only there will need to be re-derived through the iterate pattern
-
-For external sources, document the *pointer*, not the content. The ops-repo's stance: institutional memory that isn't in the repo isn't reliably consultable by an LLM agent, but a pointer is better than nothing.
-
-## Anti-patterns
-
-- **Bulk-importing without triage.** Imports the staleness alongside the truth. Future audits surface conflicts you could have avoided.
-- **Skipping provenance lines** to save effort. You will regret this in 6 months when an audit asks "is this still current?" and there's no way to tell.
-- **Auto-superseding conflicts.** Forbidden. Humans pick.
-- **Trying to harvest everything in one pass.** Half-day budget rule. Iterate.
-- **Treating archived artifacts as deleted.** They're preserved; future agents may consult them. The archive is part of the brain.
-- **Forgetting to delete the cold-start-inventory.md** after phase 7. It's working state, not memory.
-
-## Cross-references
-
-- Concurrent learnings merge (related; ongoing operations after cold-start): `concurrent-learnings-merge.md`
-- Greenfield setup (the alternative path for new repos): `greenfield-setup.md`
-- Audit existing repo (the post-harvest verification step): `audit-existing-repo.md`
-- Redundancy detection (where conflict findings come from): `../audit-patterns/redundancy-detection.md`
-- ADR pattern (supersession protocol): `../doc-types/adr-pattern.md`
-- Recommend-then-validate (the gating mechanism for supersession PRs): `recommend-then-validate.md`

package/skills/adia-ui-ops/references/recipes/concurrent-learnings-merge.md

@@ -1,158 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - cold-start-harvest.md
-  - self-healing-hooks.md
-  - recommend-then-validate.md
-  - ../audit-patterns/redundancy-detection.md
-  - ../doc-types/adr-pattern.md
-primary_sources:
-  - https://github.com/changesets/changesets — Atlassian-originated changeset pattern (the borrowed convention)
-  - https://github.com/googleapis/release-please — alternative changeset/release tool
-status: research-verified
----
-
-# Concurrent learnings merge ("sync-and-reason")
-
-> **The premise.** When multiple users (or agents) log learnings to the same `ops-repo` folders, **textual merges hide semantic conflicts.** Person A's PR adds "Tests: Vitest" to AGENTS.md; Person B's PR adds "Tests: Jest" in a different region of the same file. Git accepts both. The repo now contradicts itself, and no merge tool will tell you. This recipe makes the semantic conflicts *visible*.
-
-## What's already trivially mergeable (and what isn't)
-
-| Artifact | Merge story | Conflict risk |
-|---|---|---|
-| ADRs (`.brain/adrs/<file>.md`) | One file per decision | **Only the next-number race** (two PRs both want `0042-`) |
-| Postmortems (`.brain/postmortems/YYYY-MM-DD-*.md`) | Date-prefixed, one per incident | Same-day collision → suffix `-2` |
-| Audit-history ledger (`.brain/audit-history/<date>.json`) | Append-only, dated | None — can't conflict |
-| **AGENTS.md** (single file) | Standard git merge | **Semantic conflict undetected** |
-| **CHANGELOG.md** (single file) | Standard git merge | **Same problem** — and solved by the changesets ecosystem |
-| Runbooks, postmortems, ADRs being *edited* (rare; they should be immutable) | Standard git merge | Should not be common; immutability is the design |
-
-The hard cases are **single-file artifacts that multiple PRs want to extend simultaneously**, and **conflicting decisions** in artifacts git can't see as conflicts.
-
-## Three conventions that solve it
-
-### Convention 1 — Timestamp-prefixed ADR filenames
-
-Replace `.brain/adrs/0042-postgres-choice.md` with **`.brain/adrs/2026-04-27-1342-postgres-choice.md`**.
-
-```
-.brain/adrs/
-├── 2026-04-12-1342-use-postgres.md
-├── 2026-04-15-0930-deprecate-redis.md
-├── 2026-04-27-1100-rest-not-graphql.md
-└── README.md     # auto-generated index; assigns ADR-N labels by chronological position
-```
-
-The next-number race disappears. ADR-N labels for human reading get computed at index-generation time from chronological order, recorded in `README.md`. The numeric identity ("ADR-42") survives in the *index*, not the filename.
-
-Backwards-compat: existing repos with sequential ADRs don't need to renumber. The convention applies to new ADRs going forward.
-
-### Convention 2 — AGENTS.md changeset pattern
-
-Borrowed directly from [`changesets/changesets`](https://github.com/changesets/changesets) (the Atlassian/Atlaskit tool used by every monorepo of consequence).
-
-**The rule:** PRs that want to modify AGENTS.md don't edit AGENTS.md. They drop a file:
-
-```
-.brain/changesets/2026-04-27-vitest-replaces-jest.md
-```
-
-```markdown
----
-date: 2026-04-27
-author: alice@example.com
-target_section: conventions
-operation: replace        # add | replace | remove
----
-
-## Replace in "Conventions" section:
-
-- "Tests: Jest" → "Tests: Vitest"
-
-## Why
-
-Migrated from Jest to Vitest in PR #389 (commit a3b4c5d). The "Jest" line in
-AGENTS.md is now wrong; this changeset corrects it.
-```
-
-A **merge-time consolidation job** (run as a GitHub Action on every push to main, or on a scheduled cadence):
-
-1. Reads all `.brain/changesets/*.md` files in chronological order.
-2. **Validates:** do any changesets target the same `target_section` with conflicting `operation`s?
-   - Two `add` to "Conventions" with semantically-overlapping content → CONFLICT
-   - One `add "use Vitest"` + one `add "use Jest"` for "Tests" → CONFLICT
-   - One `replace X→Y` + one `replace X→Z` → CONFLICT
-3. **If conflicts:** emit findings, halt consolidation, require human resolution. PR a "consolidation blocker" with the conflict report.
-4. **If clean:** apply each changeset to AGENTS.md in chronological order; delete the changeset files; commit `[ops-repo] Consolidate N changesets to AGENTS.md`.
-
-The conflict-detection step is the load-bearing one. It's where "Vitest vs Jest" gets caught — *before* both land. Use the LLM-on-diff pattern from `staleness-tooling.md` as the conflict-detector.
-
-Same pattern for CHANGELOG.md additions (and `release-please`-style consolidation if release-cadence is the trigger).
-
-### Convention 3 — Post-merge redundancy scan as a scheduled trip-wire
-
-Already exists per `self-healing-hooks.md` (the weekly scheduled audit). The weekly job runs `redundancy-detection.md`'s checks across the merged state and opens an issue when contradictions are found.
-
-This is the *backstop* for cases where the changeset pattern wasn't used (e.g., direct edits to AGENTS.md by repo maintainers, or runbook edits). It catches:
-
-- AGENTS.md sections with internal contradiction
-- Two ADRs with overlapping subject matter (both `Accepted`, both addressing the same decision)
-- Repeated facts across docs (Promise 1 redundancy detection)
-
-Output: a `CONFLICT-DETECTED` finding in the audit history ledger and an open GitHub issue tagged `ops-repo`.
-
-## The supersession protocol (when conflict IS found)
-
-The recipe **does not** auto-resolve conflicts. Resolution is a content decision that affects what future agents believe. Process:
-
-1. **Detect** — redundancy-scan or changeset-validator finds the conflict.
-2. **Surface** — emit a `CONFLICT-DETECTED` finding with both source paths and the contradiction quoted.
-3. **Prompt** — the audit's PR includes a template asking the human reviewer:
-   - Which decision is current?
-   - Was the older one superseded silently? (If yes, the older one needs `Status: Superseded`.)
-   - Or should both be archived in favor of a fresh decision?
-4. **Human picks resolution.**
-5. **Write a new superseding ADR** (`.brain/adrs/<timestamp>-resolve-X-vs-Y.md`) with:
-   - Full citation of both originals
-   - Resolution decision + reasoning
-   - References both originals in `Supersedes:` field
-6. **Mark originals** as `Status: Superseded by <new-ADR>`. Do not delete or edit beyond the status field — preservation is the invariant per `adr-pattern.md`.
-7. **Update AGENTS.md** (via a new changeset) to reflect the resolved fact.
-
-This protocol stays human-in-the-loop. Per the v1.1 Yegge alignment: *artifacts compound, not agents.*
-
-## Configuration
-
-`.brain/config.toml`:
-
-```toml
-[ops-repo.merge]
-adr_naming = "timestamp"          # "timestamp" | "sequential" | "hybrid"
-agents_md_changesets = true       # require .brain/changesets/ for AGENTS.md edits
-changeset_consolidation = "merge" # "merge" (on merge to main) | "manual" | "release"
-
-[ops-repo.merge.conflict_detection]
-llm_on_diff = true                # use LLM-on-diff for semantic conflict detection
-llm_on_diff_threshold = "medium"  # severity floor for opening blocker PR
-
-[ops-repo.merge.supersession]
-require_human_approval = true     # cannot be set to false; documented as hard rule
-```
-
-## Anti-patterns
-
-- **Auto-resolving semantic conflicts.** The recipe explicitly forbids this. Conflict resolution is a content decision; humans must own it.
-- **Editing AGENTS.md directly when changesets are enabled.** The merge-time job will detect the orphan edits and warn, but discipline matters.
-- **Letting changesets accumulate without consolidation.** Once `.brain/changesets/` has >5 files unconsolidated, the audit emits a finding. Consolidate at least weekly.
-- **Renumbering ADRs after-the-fact** (sequential scheme). Breaks every link to the old number. If you must use sequential, lock the number at PR-merge time, not PR-creation time.
-- **Treating textual merge success as semantic merge success.** Git is a content-addressable store, not a semantic-conflict resolver.
-
-## Cross-references
-
-- Cold-start harvest (related but distinct: importing existing learnings): `cold-start-harvest.md`
-- Redundancy detection (the conflict-detection trip-wire): `../audit-patterns/redundancy-detection.md`
-- Self-healing hooks (where the scheduled scan runs): `self-healing-hooks.md`
-- Recommend-then-validate (consumer of conflict findings): `recommend-then-validate.md`
-- ADR pattern (supersession invariants): `../doc-types/adr-pattern.md`
-- Audit history ledger (where conflicts get recorded): `../audit-patterns/audit-history-ledger.md`

package/skills/adia-ui-ops/references/recipes/continuous-learning-loop.md

@@ -1,169 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - self-healing-hooks.md
-  - ../doc-types/adr-pattern.md
-  - ../doc-types/postmortem-pattern.md
-  - ../guidance/llm-doc-writing.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices — Anthropic's iterate pattern
-  - https://www.humanlayer.dev/blog/writing-a-good-claude-md
-  - https://sre.google/workbook/postmortem-culture/
-status: research-verified
----
-
-# Continuously-learning loop (delivers Promise 5)
-
-> **The premise.** A repo that doesn't learn from each session reverts to its baseline competence every Monday. The continuously-learning loop captures three classes of insight — *agent corrections*, *architectural decisions*, *incident lessons* — at the moment they happen, into structured memory that compounds.
-
-## What "continuously-learning" means concretely
-
-A continuously-learning repo:
-
-1. **AGENTS.md gets smarter every week.** When the agent makes a mistake, the user (or the agent itself) adds a correction. Over weeks, the file converges on what's load-bearing for that repo.
-2. **Architectural decisions get captured at decision time** as ADRs in `.brain/adrs/`, not retroactively reconstructed from PR descriptions six months later.
-3. **Incidents get post-mortems within 1 week.** Blameless. The post-mortem is linked from AGENTS.md's "Memory primitives" section so future agents know to check it.
-4. **The decision log compounds.** A repo with 100 ADRs has more institutional memory than one with 10, *as long as the index stays current and the AGENTS.md pointer stays accurate*.
-
-If any of these flows are broken, the repo isn't learning — it's just sitting on a snapshot.
-
-## Three flows
-
-### Flow 1 — The Anthropic iterate pattern (AGENTS.md corrections)
-
-Source: [Anthropic Claude Code best practices](https://code.claude.com/docs/en/best-practices) and [HumanLayer's "Writing a good CLAUDE.md"](https://www.humanlayer.dev/blog/writing-a-good-claude-md).
-
-**The mechanism.** When Claude / any LLM coding agent makes a mistake during a session, the user (or the agent itself) adds a one-line correction to AGENTS.md *during that same session*. Examples:
-
-```markdown
-# AGENTS.md (...)
-
-## Conventions
-
-- Tests: use Vitest, not Jest. (Reminder added 2026-04-27 after agent
-  reached for Jest config three sessions in a row.)
-- Imports: ESM only. No `require()` in source files.
-- Migration files in `db/migrations/` are append-only — never edit existing
-  ones; create a new migration. (Added 2026-03-15 after agent edited
-  20260301-create-users.sql.)
-```
-
-The dated parenthetical is critical — it lets the user *delete* the correction six months later when it's clearly load-bearing rather than a one-off.
-
-**The audit check.** A healthy AGENTS.md shows evidence of iteration: dated correction notes, recently-added bullet points, occasional pruning. A frozen AGENTS.md (last commit 8 months ago) is a sign the loop isn't running.
-
-**The trip-wire (soft).** AGENTS.md modified within the last 90 days for any active repo. If not, the audit emits an advisory finding: "AGENTS.md hasn't been updated in 8 months; either the repo is stable or the iterate-pattern isn't running."
-
-**Pitfall.** Teams that *only* add to AGENTS.md and never delete from it grow it past the 200-line ceiling within a year. The token-waste-detection trip-wire (Promise 2) catches this.
-
-### Flow 2 — ADR-on-architectural-change
-
-**The mechanism.** When a PR introduces an architectural change (new service, framework swap, schema rewrite, performance migration, dependency choice), the PR template requires an ADR to land alongside the code.
-
-#### `.github/pull_request_template.md` (excerpt)
-
-```markdown
-## What
-
-[summary]
-
-## Why
-
-[motivation]
-
-## Architectural impact
-
-- [ ] No architectural change (no ADR needed)
-- [ ] Architectural change — ADR added at: `.brain/adrs/NNNN-*.md`
-- [ ] Architectural change — ADR exemption granted by: [name]
-      Reason: [why no ADR]
-```
-
-**The auto-detection.** A pre-merge CI job can flag PRs that touch likely-architectural surfaces (`docs/ARCHITECTURE.md`, top-level config files, `package.json` major-version bumps, new top-level directories) without an accompanying ADR.
-
-```yaml
-# .github/workflows/adr-required.yml (excerpt)
-- name: Architectural-impact ADR check
-  run: |
-    base=origin/${{ github.base_ref }}
-    arch_files_changed=$(git diff --name-only $base...HEAD -- \
-      'docs/ARCHITECTURE.md' 'package.json' 'pyproject.toml' \
-      ':(top)*.config.*' ':(top)*.toml' ':(top)Dockerfile*' || true)
-    new_adrs=$(git diff --name-only $base...HEAD -- '.brain/adrs/*.md' | grep -c '^' || echo 0)
-    if [ -n "$arch_files_changed" ] && [ "$new_adrs" -eq 0 ]; then
-      echo "::warning::PR changes likely-architectural files but adds no ADR. Verify exemption box is ticked."
-    fi
-```
-
-**The trip-wire.** `.brain/adrs/` should grow over time at a rate consistent with the repo's architectural-change rate. A 5-year-old repo with 2 ADRs is suspicious — either the team's not capturing decisions or they're capturing them somewhere else (PR descriptions, Slack, code comments). The audit flags repos with `<1 ADR per year of repo age` for `>1 year` repos.
-
-### Flow 3 — Postmortem-on-incident
-
-**The mechanism.** Within 1 week of a SEV-1 or SEV-2 incident, a blameless post-mortem lands in `.brain/postmortems/YYYY-MM-DD-name.md`. See `../doc-types/postmortem-pattern.md` for the template.
-
-The flow itself runs *outside* the repo (incident response, retrospective meeting, write-up) — but the *artifact* lands in the repo and gets indexed.
-
-**The trip-wire.** If the repo has had production incidents (heuristic: search `git log` for `revert`, `hotfix`, `incident`, `outage`, `rollback`) but `.brain/postmortems/` is empty, the audit flags it. False positives are fine — the prompt to write a post-mortem is the value.
-
-## How AGENTS.md should expose the memory primitives
-
-The "Memory primitives" section of AGENTS.md tells the agent *when to read* each memory type. Without this, the agent doesn't know to consult ADRs before architectural changes or post-mortems before debugging.
-
-```markdown
-## Memory primitives
-
-- **Before architectural changes**, read `.brain/adrs/` newest-first. If
-  your proposed change conflicts with an `Accepted` ADR, write a new ADR
-  superseding it; don't silently override.
-
-- **When debugging a production issue**, search `.brain/postmortems/` for
-  prior occurrences. Many "new" bugs are repeats.
-
-- **When you make a mistake the user has to correct**, ask: "Should I add
-  this to AGENTS.md so I don't repeat it?" Most of the time the answer
-  is yes. Add a one-line correction with a dated parenthetical.
-
-- **When a runbook is needed for a recurring operation**, file it in
-  `.brain/runbooks/` rather than embedding it in AGENTS.md.
-```
-
-This section is what makes the loop *closed* — without it, the artifacts exist in the repo but the agent doesn't know to consult them.
-
-## The compounding effect (why this matters more over time)
-
-Year 1: AGENTS.md is small, ADRs are 5-10, post-mortems are 1-2.
-
-Year 3: AGENTS.md is still ~150 lines (because the iterate pattern includes pruning), ADRs are 30-40 (mostly historical, some active), post-mortems are 8-15. The repo has *learned* what its actual gotchas are.
-
-Year 5: An LLM agent dropped into this repo for the first time has access to 5 years of explicit institutional memory in a navigable format. That's the compound interest.
-
-The opposite case: AGENTS.md was written once 5 years ago, never updated. ADRs don't exist. Post-mortems live in Slack. An agent dropped into this repo has no advantage over an agent dropped into any random repo.
-
-## Verification — what the audit checks
-
-| Flow | Check | Severity if missing |
-|---|---|---|
-| Iterate AGENTS.md | AGENTS.md last-modified date < 90 days for active repos (heuristic: repo has commits in last 90 days) | Advisory |
-| ADR-on-architectural-change | `.brain/adrs/` exists and contains ≥1 ADR per year of repo age (rough heuristic) | Medium |
-| ADR PR template | `.github/pull_request_template.md` includes architectural-impact checkbox | Low |
-| Postmortem-on-incident | If `git log` has incident-shaped commits, `.brain/postmortems/` is non-empty | Medium |
-| AGENTS.md "Memory primitives" section | Section exists and points to ADRs + postmortems | High (closes the loop) |
-
-A repo can pass all the *self-healing* checks (Promise 4) and still fail *continuously-learning* (Promise 5) — they're orthogonal. The hooks keep the surface clean; the loop makes it grow smarter.
-
-## Common anti-patterns
-
-- **AGENTS.md is in `Proposed` status forever** — corrections never get accepted into the canonical file. Loop is broken at the merge step.
-- **ADRs in PR descriptions** — they don't compound; nobody can find them. Move into `.brain/adrs/`.
-- **Post-mortems in private docs (Notion, Confluence)** — unreachable from the agent. Either move to `.brain/postmortems/` or link aggressively from AGENTS.md.
-- **Memory primitives section missing from AGENTS.md** — artifacts exist, agent never reads them. Single most common loop break.
-- **Post-mortems blame individuals** — chills future post-mortem candor. Audit the *language*, not just existence.
-
-## Cross-references
-
-- Self-healing hooks (Promise 4 — keeps the surface clean): `self-healing-hooks.md`
-- ADR pattern: `../doc-types/adr-pattern.md`
-- Post-mortem pattern: `../doc-types/postmortem-pattern.md`
-- LLM-doc-writing guidance (length / iteration): `../guidance/llm-doc-writing.md`
-- AGENTS.md spec: `../standards/agents-md-spec.md`