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

package/skills/adia-ui-ops/references/doc-types/decisions-log.md

@@ -1,146 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - adr-pattern.md
-  - architecture-md.md
-  - plan-roadmap.md
-primary_sources:
-  - https://learn.microsoft.com/en-us/azure/well-architected/architect-role/architecture-decision-record — Microsoft Azure Well-Architected Framework on ADR / decision log
-  - https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html — AWS Prescriptive Guidance, "ADRs"
-  - https://adr.github.io — ADR organization (canonical hub)
-  - https://github.com/joelparkerhenderson/architecture-decision-record — Joel Parker Henderson catalog (most-cited examples library)
-  - https://github.com/npryce/adr-tools — adr-tools, including `adr generate toc`
-  - https://github.com/adr/adr-log — adr-log Markdown index generator
-status: research-verified
----
-
-# Decision log — what it actually is
-
-> **The canonical "decision log" is the index of all ADRs in `.brain/adrs/`. It is *not* a separate folder.** This is the load-bearing nuance most teams get wrong.
-
-## The canonical meaning (cite-able)
-
-Microsoft Azure Well-Architected Framework, AWS Prescriptive Guidance, and adr.github.io all converge on the same definition:
-
-> "An Architectural Decision Record (ADR) captures a single AD and its rationale; **the collection of ADRs constitutes the decision log.**"
-> — Microsoft Azure WAF, *Architecture decision record*
-
-> "A collection of ADRs creates a decision log that captures the architectural decisions for a project."
-> — AWS Prescriptive Guidance, *Architectural decision records*
-
-So when a repo has `.brain/adrs/0001-…md` … `0042-…md` and a `.brain/adrs/README.md` listing them, **that is the decision log**. There is no second folder needed.
-
-This skill delivers **Promise 5 (continuously-learning)** by ensuring the decision log is *navigable* — an ADR folder without an index is a scrapyard.
-
-## The two shapes the audit detects
-
-The repo-fixer audit must accept both shapes and not flag either as wrong. Just note which one is in play.
-
-| Shape | What's on disk | When appropriate |
-|---|---|---|
-| **Canonical (single-folder)** | `.brain/adrs/` containing all decisions; `.brain/adrs/README.md` is the log index | Default. Fits 90% of teams. |
-| **Split (two-folder)** | `.brain/adrs/` for big architecture decisions; `.brain/decisions/` for lighter day-to-day picks (tooling swaps, library choices, formatting conventions) | Larger orgs where ADR review is heavyweight and would gate routine choices |
-
-The split is **a team convention, not industry standard**. Some teams find it useful: ADRs gate architecture, `.brain/decisions/` lets engineers move on a tooling swap without scheduling an architecture review. Other teams find it confusing — two homes invites drift over which decision goes where.
-
-The audit's recommendation order:
-
-1. If only `.brain/adrs/` exists → recommend keeping it canonical; ensure `README.md` index is present and current.
-2. If only `.brain/decisions/` exists → recommend renaming to `.brain/adrs/` for tool/community alignment (ADR tooling expects `.brain/adrs/`).
-3. If both exist → recommend documenting the split rule in `AGENTS.md`'s "Where to find things" section so the agent knows which folder to write to.
-
-## Generating the index
-
-Three options, ordered by maintenance burden (lowest first):
-
-### Option 1 — `adr-log` (auto-generate)
-
-[`adr-log`](https://github.com/adr/adr-log) reads a folder of ADRs and writes a Markdown table of contents into a delimited region of `README.md`:
-
-```bash
-npm i -g adr-log
-adr-log -d .brain/adrs -i .brain/adrs/README.md
-```
-
-Wrap the index in begin/end markers so subsequent runs only update that region:
-
-```markdown
-# Architecture Decision Records
-
-<!-- adrlog -->
-- [ADR-0001](0001-record-architecture-decisions.md) — Record architecture decisions
-- [ADR-0002](0002-use-postgres-not-mysql.md) — Use Postgres, not MySQL
-<!-- adrlogstop -->
-```
-
-Add to a pre-commit hook or CI workflow so the index never drifts from filenames. See `../recipes/self-healing-hooks.md`.
-
-### Option 2 — `adr-tools generate toc`
-
-[`adr-tools`](https://github.com/npryce/adr-tools) ships a similar generator. Lightly maintained as of April 2026 — works, but no recent releases.
-
-```bash
-adr generate toc > .brain/adrs/README.md
-```
-
-### Option 3 — Hand-written index
-
-For small repos (<20 ADRs) the index is one line per ADR. Maintain by hand:
-
-```markdown
-# Architecture Decision Records
-
-| # | Title | Status | Date |
-|---|---|---|---|
-| [0001](0001-record-architecture-decisions.md) | Record architecture decisions | Accepted | 2024-01-12 |
-| [0002](0002-use-postgres-not-mysql.md) | Use Postgres, not MySQL | Accepted | 2024-03-04 |
-| [0003](0003-rest-not-graphql.md) | REST, not GraphQL | Superseded by 0017 | 2024-03-19 |
-| [0017](0017-graphql-for-public-api.md) | GraphQL for public API | Accepted | 2025-11-08 |
-```
-
-The hand-written form **adds the Status column**, which the auto-generated forms typically omit. Worth it for a navigable log.
-
-## How AGENTS.md links the decision log
-
-In the `Where to find things` section:
-
-```markdown
-- **Architecture Decision Records:** `.brain/adrs/` — see `.brain/adrs/README.md` for the indexed log; newest-first
-- **Lightweight decisions** (if your team uses the split): `.brain/decisions/`
-```
-
-In the `Memory primitives` section:
-
-```markdown
-- **Before making architectural decisions**, consult the decision log at `.brain/adrs/README.md`. If your proposed change conflicts with an `Accepted` ADR, write a new ADR superseding it; don't silently override.
-```
-
-## Audit checks for the decision log
-
-1. **`.brain/adrs/` exists** (or `.brain/architecture/decisions/` — accepted alias).
-2. **An index file exists** at `.brain/adrs/README.md` listing all ADRs.
-3. **The index is current** — every `NNNN-*.md` filename in the folder appears in the index. No orphans, no broken links.
-4. **The index sort order is meaningful** (chronological or by status group, not random).
-5. **AGENTS.md points at the index file**, not just the folder. Folder-only pointers force the agent to `ls` and guess.
-6. **If `.brain/decisions/` also exists**, AGENTS.md documents the split rule.
-
-The "index is current" check is the high-value one — it catches drift after a teammate adds an ADR but forgets to update the index.
-
-## Common anti-patterns
-
-- **No index** — folder of 40 ADRs, no `README.md`. The decision log exists but isn't navigable.
-- **Stale index** — index lists 18 ADRs; folder has 26. Catch with the audit + auto-generation.
-- **Two parallel logs that drift** — `.brain/adrs/` and `.brain/decisions/` both have ADRs about Postgres. Pick a rule and document it.
-- **Decision log as a single Markdown file** — `.brain/decisions.md` with all decisions in one document. Editing one decision rewrites file history; no per-decision audit trail. Strongly recommended against.
-- **Folder named `.brain/architecture-decisions/`** — works, but `.brain/adrs/` is what tooling expects. Prefer `.brain/adrs/`.
-- **Numbering reset on folder split** — if you split into `.brain/adrs/` and `.brain/decisions/`, do NOT restart numbering at 0001 in the second folder. Keep the global sequence so cross-references work.
-
-## Cross-references
-
-- ADR pattern (canonical): `adr-pattern.md`
-- Architecture overview (current state, not decisions): `architecture-md.md`
-- Plan / roadmap (forward-looking, not decisions): `plan-roadmap.md`
-- Self-healing index generation: `../recipes/self-healing-hooks.md`
-- Memory organization: `../recipes/memory-organization.md`
-- AGENTS.md memory primitives section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/doc-types/plan-roadmap.md

@@ -1,182 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - decisions-log.md
-  - changelog.md
-  - architecture-md.md
-primary_sources:
-  - https://keepachangelog.com/en/1.1.0/ — Keep a Changelog 1.1.0 (date-stamp convention)
-  - https://linear.app/docs/markdown-export — Linear Markdown export (issues / projects)
-  - https://help.shortcut.com/hc/en-us/articles/360057451511 — Shortcut Markdown / API export
-  - https://docs.basecamp.com/article/29-export-your-account — Basecamp project export
-  - https://docs.github.com/en/issues/planning-and-tracking-with-projects — GitHub Projects (issue-tracker plan source)
-  - https://www.atlassian.com/agile/project-management/program-roadmaps — Atlassian on roadmaps vs plans
-status: research-verified
----
-
-# PLAN.md and ROADMAP.md — active work vs forward-looking
-
-> **PLAN.md is *now* — what's in flight this week or sprint. ROADMAP.md is *next* — what's coming this quarter or year.** They are two different documents with different update cadences and different audiences. Conflating them is the most common failure mode.
-
-This pattern delivers **Promise 1 (less-wasteful)** and **Promise 3 (less-prone-to-staleness)**: when the boundary between active and forward-looking is clear, neither doc rots into a TODO graveyard.
-
-## The split
-
-| | `.brain/PLAN.md` | `.brain/ROADMAP.md` |
-|---|---|---|
-| **Horizon** | This week / sprint / current iteration | This quarter / half / year |
-| **Granularity** | Specific tasks, owners, due dates | Themes, milestones, target months |
-| **Cadence** | Updated weekly or per-sprint | Updated quarterly |
-| **Audience** | The team doing the work; LLM agents picking up tasks | Stakeholders, leadership, contributors deciding whether to invest |
-| **Status verbs** | "in progress", "blocked", "in review", "done" | "planned", "in progress", "shipped", "deferred" |
-| **Source of truth** | Often a mirror/export of the issue tracker | Hand-maintained by leads/PMs |
-
-If a team has only one of the two, **`PLAN.md` is the higher-value one for LLM agents** — the agent needs to know what to pick up, not what's coming in Q3. Skip `ROADMAP.md` until there is one to publish.
-
-## PLAN.md — shape and conventions
-
-### Minimal template
-
-```markdown
----
-updated: 2026-04-27
-horizon: 2026-W17 (Apr 21 – Apr 27)
----
-
-# Plan — Week of 2026-04-21
-
-## In progress
-
-- **[#412] Migrate auth to Auth.js v5** — @alice — due 2026-04-28
-- **[#418] Replace Redis with Postgres LISTEN/NOTIFY** — @bob — due 2026-05-02
-  - Blocked on ADR-0042 review
-
-## Up next (this week)
-
-- [#421] Cron worker → BullMQ — unassigned
-- [#423] Strip dead `lib/legacy/` — @carol
-
-## Done this week
-
-- [x] [#405] Bump TypeScript 5.7 → 5.8 (@alice, merged 2026-04-23)
-- [x] [#408] Drop Node 20 from CI matrix (@bob, merged 2026-04-25)
-
-## Archive
-
-See `.brain/archive/plan-2026-W16.md`.
-```
-
-### Conventions
-
-- **Date the doc**: Keep-a-Changelog-style `updated: YYYY-MM-DD` in YAML frontmatter, plus an English `Week of …` line in the H1. Without a date stamp the agent can't tell whether the plan is current. ([keepachangelog.com](https://keepachangelog.com/en/1.1.0/) date-stamp convention.)
-- **Issue numbers**: link to the tracker so the plan is a *view*, not a parallel source of truth.
-- **Owners**: an unowned item drifts. If no one will own it this week, push it to the roadmap.
-- **Due dates**: explicit ISO dates beat "next week" — relative dates rot.
-- **Archive completed work weekly**: copy the "Done" section to `.brain/archive/plan-YYYY-Www.md` and clear it from `PLAN.md`. The archive is a free changelog.
-
-### The TODO-graveyard anti-pattern
-
-The most common failure: items accumulate, nothing leaves. After a year `PLAN.md` is 800 lines, half of it is "Up next" from 8 months ago, the agent doesn't know which items are real.
-
-Mitigations:
-
-1. **Time-box "Up next"** to the current iteration. Items that don't make it move to `ROADMAP.md` or get closed.
-2. **Archive on a fixed cadence** (every Friday, end-of-sprint).
-3. **Run a staleness audit**: any line item with a due date >30 days in the past, or unedited for >60 days, is flagged. See `../audit-patterns/staleness-tooling.md`.
-
-## ROADMAP.md — shape and conventions
-
-### Minimal template
-
-```markdown
----
-updated: 2026-04-15
-horizon: 2026-Q2 / Q3
----
-
-# Roadmap
-
-## Now (Q2 2026)
-
-- **Multi-tenant scoping** — required for enterprise GA. Owner: @alice. Target: 2026-05.
-- **Webhook delivery v2** — exponential backoff, replay tooling. Owner: @bob. Target: 2026-06.
-
-## Next (Q3 2026)
-
-- **Self-serve billing portal** — Stripe Customer Portal integration.
-- **OpenTelemetry instrumentation** — replace ad-hoc logging.
-
-## Later (2026-H2 and beyond)
-
-- Federated SSO
-- Audit-log export to customer S3
-
-## Recently shipped
-
-- 2026-Q1 — SAML SSO (Enterprise tier)
-- 2025-Q4 — Async webhook delivery v1
-```
-
-### Conventions
-
-- **Now / Next / Later** is the standard public-roadmap shape ([ProductPlan](https://www.productplan.com/learn/now-next-later-roadmap/) popularized this; widely adopted). Keeps things vague enough to ship.
-- **No daily-task granularity.** If an item belongs in a sprint, it belongs in `PLAN.md`.
-- **Recently shipped** doubles as a release-notes pointer — link to `CHANGELOG.md`.
-- **Quarterly review** ritual: at end of quarter, move "Now" → "Recently shipped", promote "Next" → "Now", review "Later".
-
-## Issue-tracker exports — when the plan IS the export
-
-Many teams treat the issue tracker as truth and `PLAN.md` as a generated view. This works well — and the agent gets a Markdown view it can read without API access.
-
-| Tool | Export mechanism | Notes |
-|---|---|---|
-| **Linear** | [Markdown export](https://linear.app/docs/markdown-export) per issue or project; API for bulk | Project view exports clean Markdown with status grouping |
-| **Shortcut (formerly Clubhouse)** | [API + Markdown rendering in CLI](https://help.shortcut.com/hc/en-us/articles/360057451511) | Iteration views map to weekly plans |
-| **GitHub Projects** | [GraphQL API](https://docs.github.com/en/graphql/reference/objects#projectv2); community scripts dump views to Markdown | Native to GitHub — no separate auth |
-| **Jira** | REST API; `jira-cli`, `gojira` | Heavier setup; usually only worth it for Jira-mandated orgs |
-| **Basecamp** | [Account export](https://docs.basecamp.com/article/29-export-your-account) | Coarser; better for archive than weekly plan |
-
-The pattern: a CI job (or pre-commit hook) regenerates `.brain/PLAN.md` from the tracker on a cron schedule, commits the diff. Now the agent reads a current plan without an API token.
-
-## How AGENTS.md links them
-
-In the `Where to find things` section:
-
-```markdown
-- **Active plan:** `.brain/PLAN.md` — what's in flight this week
-- **Roadmap:** `.brain/ROADMAP.md` — quarterly horizon
-```
-
-In the `Memory primitives` section:
-
-```markdown
-- **When picking up work**, start at `.brain/PLAN.md`. Items there are scoped for the current iteration.
-- **For longer-horizon questions** ("are we going to support X?"), check `.brain/ROADMAP.md` before proposing new work.
-```
-
-## Audit checks
-
-1. **Date stamps present** — `updated:` frontmatter or visible date in H1. A `PLAN.md` without a date is unverifiable.
-2. **PLAN.md updated within the last 14 days** (sprint cadence). Older = staleness flag.
-3. **ROADMAP.md updated within the last 90 days** (quarterly cadence). Older = staleness flag.
-4. **No items in PLAN.md with due dates >30 days past** (TODO graveyard).
-5. **`.brain/PLAN.md` and `.brain/ROADMAP.md` are referenced from AGENTS.md.**
-6. **Archive folder exists** if the team is using weekly archival (`.brain/archive/plan-YYYY-Www.md`).
-
-## Common anti-patterns
-
-- **One file called `TODO.md`** at repo root, mixing this-week and someday. Split it into PLAN.md + ROADMAP.md or kill it.
-- **No date on either doc** — agent can't tell if the plan is from last sprint or last year.
-- **PLAN.md as immortal backlog** — items added, never removed. Time-box and archive.
-- **ROADMAP.md with weekly-task granularity** — wrong horizon. Push detail to PLAN.md.
-- **PLAN.md and the issue tracker disagree** — pick one as truth (usually the tracker) and generate the other.
-- **Roadmap contains commitments without owners or target months** — it's a wishlist, not a roadmap.
-
-## Cross-references
-
-- Decision log (decisions, not plans): `decisions-log.md`
-- Changelog (shipped, not planned): `changelog.md`
-- Self-healing PLAN.md regeneration: `../recipes/self-healing-hooks.md`
-- Staleness detection: `../audit-patterns/staleness-tooling.md`
-- AGENTS.md "Where to find things" section: `../standards/agents-md-spec.md`

package/skills/adia-ui-ops/references/doc-types/postmortem-pattern.md

@@ -1,206 +0,0 @@
----
-date: 2026-04-27
-coverage: extended
-peers:
-  - adr-pattern.md
-  - decisions-log.md
-primary_sources:
-  - https://sre.google/workbook/postmortem-culture/ — Google SRE postmortem culture
-  - https://sre.google/sre-book/example-postmortem/ — Google SRE example postmortem
-  - https://www.atlassian.com/incident-management/postmortem/templates — Atlassian postmortem templates
-  - https://github.com/dastergon/postmortem-templates — most-cited template catalog
-status: research-verified
----
-
-# Post-mortem pattern
-
-> **Storage convention.** This skill recommends `.brain/postmortems/` (most common) or `.brain/incidents/` (also common). Avoid `.brain/traces/` — "traces" risks being read as observability traces (OpenTelemetry / Jaeger), which is a different concept.
-
-## What a post-mortem is
-
-A **dated write-up of an incident**: what happened, what the impact was, what caused it, what we did, what we learned. Filed after the incident is resolved; serves as **memory** so the same failure doesn't repeat.
-
-The load-bearing principle is **blameless**: post-mortems describe systems failures, not personal failures. People did what felt reasonable given the information they had. The post-mortem looks for systemic improvements — process, tooling, alerting, documentation — not someone to blame.
-
-Source: [Google SRE — Postmortem Culture: Learning from Failure](https://sre.google/workbook/postmortem-culture/).
-
-## Two canonical templates
-
-### Google SRE postmortem (the gold standard)
-
-Sections (per Google's [example postmortem](https://sre.google/sre-book/example-postmortem/)):
-
-- **Summary** — one paragraph
-- **Impact** — users affected, duration, severity
-- **Root causes** — the underlying *why* (often plural)
-- **Trigger** — the proximate event that fired the latent bug
-- **Resolution** — what stopped the bleeding
-- **Detection** — how we noticed (monitoring? user report? both?)
-- **Action items** — concrete follow-ups, with owners + due dates
-- **Lessons learned** — what went well / what went poorly / where we got lucky
-- **Timeline** — chronological log with timestamps
-
-Stored internally at Google as Google Docs, not Markdown — but the structure ports directly to Markdown.
-
-### Atlassian postmortem template
-
-Sections (per [Atlassian](https://www.atlassian.com/incident-management/postmortem/templates)):
-
-- **Summary**
-- **Leadup** — what was happening before
-- **Fault** — the specific failure
-- **Impact**
-- **Detection**
-- **Response**
-- **Recovery**
-- **Five Whys** — recursive root-cause drill
-- **Action items**
-
-Atlassian's split between *Detection / Response / Recovery* maps cleanly to incident-management process steps; the skill recommends this structure for teams with formal IM tooling.
-
-## Filename + storage
-
-Recommended:
-
-```
-.brain/postmortems/
-├── 2026-04-12-checkout-outage.md
-├── 2026-03-08-payment-double-charge.md
-├── 2026-01-22-search-degradation.md
-└── README.md   # index, sorted newest-first
-```
-
-Filename pattern: `YYYY-MM-DD-short-incident-name.md`. The date prefix sorts chronologically.
-
-`.brain/incidents/` is an accepted alias. `.brain/post-mortems/` (with hyphen) also works. Pick one and stick with it.
-
-## File template (Google SRE flavor)
-
-```markdown
----
-date: 2026-04-12
-status: resolved
-severity: SEV-2
-duration: 47 minutes
----
-
-# Checkout outage — 2026-04-12
-
-## Summary
-
-For 47 minutes on April 12 starting at 14:23 UTC, the checkout endpoint
-returned 500s for ~30% of requests due to a database connection-pool
-exhaustion triggered by a bot scrape.
-
-## Impact
-
-- ~12,000 affected users
-- ~$40K in dropped revenue
-- SEV-2 declared at 14:31 UTC
-
-## Root causes
-
-1. Connection pool sized for normal load only; no headroom.
-2. Bot scrape was not detected by rate-limiter (User-Agent allow-listed
-   in legacy config from 2024).
-3. No alert on connection-pool saturation; alert fired only on response-
-   latency p95.
-
-## Trigger
-
-GoogleBot-impersonating scrape from AS12345, 14:21 UTC, 800 req/s.
-
-## Resolution
-
-- Killed scrape via WAF rule (14:55 UTC).
-- Connection pool drained naturally over 90s.
-
-## Detection
-
-User report at 14:27 UTC. Internal alert fired 14:29 UTC.
-
-## Action items
-
-- [ ] (Alice, due 2026-04-19) Add connection-pool-saturation alert.
-- [ ] (Bob, due 2026-04-26) Review WAF allow-list; remove stale entries.
-- [ ] (Charlie, due 2026-05-03) Right-size connection pool with headroom.
-
-## Lessons learned
-
-### What went well
-- Time-to-resolution was 32 minutes once root cause identified.
-- WAF tooling was usable without a vendor escalation.
-
-### What went poorly
-- 4 minutes between user report and our alert firing.
-- WAF allow-list hadn't been reviewed in 18 months.
-
-### Where we got lucky
-- Scrape happened at 14:23 UTC (low-traffic window). At peak we'd have
-  exhausted the pool faster.
-
-## Timeline (UTC)
-
-- 14:21 — bot scrape begins
-- 14:23 — first checkout 500
-- 14:27 — user report in #incidents
-- 14:29 — internal latency alert fires
-- 14:31 — SEV-2 declared
-- 14:48 — root cause identified (DB connection pool)
-- 14:55 — scrape blocked at WAF
-- 15:10 — incident resolved
-```
-
-## How AGENTS.md should reference post-mortems
-
-In the `Where to find things` section:
-
-```markdown
-- **Post-mortems:** `.brain/postmortems/` — newest-first; read when investigating recurring issues
-```
-
-In the `Memory primitives` section:
-
-```markdown
-- **When debugging a production issue**, search `.brain/postmortems/` for prior occurrences. Many "new" bugs are repeats of fixed-and-forgotten issues.
-```
-
-## Audit checks for post-mortems
-
-1. **Folder exists** at `.brain/postmortems/` (or `.brain/incidents/` — accepted alias).
-2. **Filename pattern is consistent** (`YYYY-MM-DD-name.md`).
-3. **Each post-mortem has a `status:` field** (resolved / ongoing / blocked) and `date:`.
-4. **An index file (`README.md`) exists** in the folder, sorted newest-first.
-5. **`.brain/postmortems/` is referenced from AGENTS.md**.
-
-The audit should NOT flag a missing `.brain/postmortems/` folder for projects that haven't had production incidents — heuristic: search commit log for `revert`, `incident`, `outage`, `hotfix` to estimate whether the project should have post-mortems.
-
-## Trigger rules — when to write a post-mortem
-
-A post-mortem is *not* required for every bug. The skill recommends writing one when **any one** of:
-
-1. **A `release(.*hotfix` commit lands within 24h of a non-hotfix `release(` commit.** This is the canonical trigger — the hotfix exists *because* something escaped the prior release. The mechanism that allowed the escape needs writing down.
-2. **A consumer-facing bug spent more than 1h in `latest` on npm** (or equivalent — the user-visible default channel for the package). The lag-to-detection is the unit of regret; capture how it happened and shorten the next loop.
-3. **An audit emits a `severity: high` finding affecting anything outside `[Unreleased]`.** OPEN findings on shipped artifacts are incidents-in-waiting; if they trace to a published version, write the post-mortem.
-4. **A trip-wire (CI gate, pre-commit hook) failed silently and the failure mode was discovered post-hoc.** "The check that should have caught this didn't" is exactly the class of process lesson post-mortems exist to capture.
-5. **A user-reported runtime error against a tagged release.** External-detected runtime failures are the cleanest signal that internal verification missed.
-
-The point isn't ceremony — it's that the *mechanism* of failure is captured *once*, in plain text, so the next session inherits the diagnosis instead of re-walking it. A post-mortem that says "we'll be more careful" is failing the test; one that says "we'll add `<specific trip-wire>`" passes.
-
-**Mapping to `ops-repo` artifacts.** When a post-mortem identifies a structural fix (new trip-wire, new convention, new generator), record the finding-to-fix pairing in `.brain/findings/INDEX.md` under `## Graduations`. The post-mortem is the narrative; the graduations table is the structured index. See [`../recipes/findings-index-readout.md`](../recipes/findings-index-readout.md).
-
-## Common anti-patterns
-
-- **Folder named `.brain/traces/`** — confused with observability traces.
-- **No date prefix on filename** — files don't sort chronologically.
-- **Post-mortem is a finger-pointing exercise** — violates blameless principle. Convert to systems-language.
-- **Action items without owners or due dates** — they don't get done.
-- **No timeline section** — losing the "what happened when" loses the chance to improve detection.
-- **Not linked from AGENTS.md** — agent doesn't know to check.
-
-## Cross-references
-
-- ADR pattern (architecture decisions, separate concept): `adr-pattern.md`
-- Decision log (collection of ADRs): `decisions-log.md`
-- AGENTS.md "Memory primitives" section: `../standards/agents-md-spec.md`
-- Memory-organization recipe: `../recipes/memory-organization.md`