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

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

@@ -0,0 +1,206 @@
+---
+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`

package/skills/adia-ui-ops/references/genres/prose-and-writing.md

@@ -0,0 +1,149 @@
+---
+date: 2026-04-27
+coverage: extended
+peers:
+  - ../recipes/greenfield-setup.md
+  - ../recipes/memory-organization.md
+  - ../doc-types/adr-pattern.md
+  - ../doc-types/postmortem-pattern.md
+primary_sources:
+  - https://diataxis.fr/
+  - https://www.amwa.org/page/style_guides
+  - https://en.wikipedia.org/wiki/Series_bible
+  - https://github.com/errata-ai/vale
+status: research-verified
+---
+
+# Genre: prose and writing
+
+> **Premise.** ops-repo was designed for code repositories, but five of the six promises (less-wasteful, token-and-context-optimized, less-prone-to-staleness, self-healing partial, continuously-learning) translate cleanly to prose, fiction, journalism, and documentation projects. The skill works — with a vocabulary swap and one fewer trip-wire.
+
+_Last reviewed: 2026-04-27_
+
+## Where it fits
+
+| Genre | Fit | Why |
+|---|---|---|
+| Technical documentation | Excellent | Drift-vs-code is the same concern; ADRs map 1:1 to documentation decisions |
+| Long-form non-fiction (book) | Excellent | Voice EDRs, source-of-fact registries, revision retrospectives all matter |
+| Long-form fiction (novel/series) | Excellent | "Series bible" is exactly the brain metaphor; EDRs become world-building decisions |
+| Academic / research writing | Strong | Citation-stale (papers retracted, replaced) is the same as live-link-stale-content |
+| Journalism / essays | Partial | Revision retrospectives become "what I'd revise"; EDRs less natural for one-off pieces |
+| Screenplay / playwriting | Partial | Character-bible decisions are EDR-shaped; but writers' rooms don't usually want the process ceremony |
+| Marketing / SEO copy | Low | Optimization is dominated by A/B testing; not a docs problem |
+| Poetry | Poor | Wrong tool. Voice is not decomposable into decision records. |
+
+## Vocabulary translation
+
+| ops-repo (code) | Prose equivalent |
+|---|---|
+| `AGENTS.md` | `STYLE.md` or `VOICE.md` (the canonical style/voice guide) |
+| ADR (Architecture Decision Record) | EDR (Editorial Decision Record) — voice/POV/structure decisions |
+| Postmortem | Revision retrospective — "what broke in this draft" |
+| Runbook | Process ritual — "how I plan a chapter," "submission checklist" |
+| Architecture overview | Series bible / world bible (fiction) or content map (docs) |
+| Trip-wire | Editorial gate (e.g., "no draft published without sensitivity check") |
+| Audit | Manuscript health check |
+| Browserslist baseline | House-style baseline (AP, Chicago, NYT, brand-specific) |
+
+## Folder layout (prose adaptation)
+
+```
+.brain/
+├── config.toml
+├── edrs/                  # editorial decision records (was adrs/)
+│   ├── 0001-pov-third-limited.md
+│   ├── 0002-no-second-person.md
+│   └── 0003-style-guide-AP-not-Chicago.md
+├── retrospectives/        # was postmortems/
+│   ├── draft-1-feedback-synthesis.md
+│   └── reader-survey-q1.md
+├── rituals/               # was runbooks/
+│   ├── chapter-planning.md
+│   └── pre-submission-checklist.md
+├── bible/                 # was architecture/
+│   ├── characters.md
+│   ├── world.md
+│   └── timeline.md
+├── archive/               # superseded EDRs, abandoned drafts (not deleted)
+└── audit-history/         # manuscript-health JSON ledgers
+```
+
+The dotfile prefix is *more* useful for prose than for code: drafts live at the repo root or in `chapters/` / `posts/`, and `.brain/` is structurally clearly the "out of band" memory layer that humans curate but don't read every day.
+
+## Promise-by-promise applicability
+
+| Promise | Applies to prose? | How |
+|---|---|---|
+| 1. Less-wasteful | Yes | Style-guide drift detection (one canonical, no duplicated style rules across files) |
+| 2. Token-and-context-optimized | Yes | Prose has the same agent-context-window problem; STYLE.md ≤200 lines |
+| 3. Less-prone-to-staleness | Yes | Citation rot, character-name conflicts across drafts, world-bible vs current-draft drift |
+| 4. Self-healing | Partial | Pre-commit hooks for spelling/style work (Vale, markdownlint); but most prose tooling is editor-internal not git-hook-internal |
+| 5. Continuously-learning | Yes | Voice/POV decisions accumulate; series spans years; humans curate the editorial log |
+| Reliability dial | Yes | A novelist working alone uses `lax`; a magazine staff with multiple writers uses `strict` |
+
+## What translates as-is
+
+- `../standards/agents-md-spec.md` — replace `AGENTS.md` → `STYLE.md`; the 8-section skeleton works (Project overview = book/series overview, Build/test/run = build commands for the manuscript build, Conventions = style rules, etc.)
+- `../audit-patterns/orphan-detection.md` — orphan files in `.brain/` not reachable from STYLE.md
+- `../audit-patterns/redundancy-detection.md` — same style rule repeated in two files
+- `../audit-patterns/format-hygiene.md` — every EDR has a date and status
+- `../audit-patterns/staleness-tooling.md` — Vale, lychee work for prose too (Vale is *primarily* a prose tool)
+- `../audit-patterns/token-waste-detection.md` — STYLE.md bloat is the same problem
+- `../recipes/self-healing-hooks.md` — Vale + spell + style-rule hooks instead of code linters
+- `../recipes/audit-existing-repo.md` — survey an existing manuscript repo
+- `../recipes/cold-start-harvest.md` — same procedure for an old manuscript with style notes scattered everywhere
+- `../guidance/context-budget.md` — same math; agent context is finite
+- `../guidance/reliability-dial.md` — strictness picker
+
+## What needs translation
+
+- `../doc-types/adr-pattern.md` → EDR pattern. Change the `## Status` allowed values to `Drafted | Adopted | Superseded | Abandoned`. Keep the Y-statement / MADR templates.
+- `../doc-types/postmortem-pattern.md` → revision retrospective. Replace "incident timeline" with "draft timeline"; keep "blameless" and "what we'd do differently."
+- `../doc-types/architecture-md.md` → series bible. matklad's pattern translates: "what is where in this story-world."
+- `../doc-types/decisions-log.md` → editorial decision log.
+
+## What doesn't apply
+
+- `../standards/cross-tool-matrix.md` — Cursor/Codex/Devin don't have prose equivalents. Use Claude/ChatGPT/Cursor-for-prose; one entry file (STYLE.md) plus one tool-specific pointer is enough.
+- `../audit-patterns/entry-file-coverage.md` — partial. Fewer entry-file conventions in prose; just STYLE.md.
+- `../audit-patterns/memory-fragmentation.md` — partial. Less likely to fragment when one author works alone.
+
+## When NOT to use ops-repo for prose
+
+- Single short essay or a one-week project. Overhead exceeds benefit.
+- Pure ideation / brainstorming. Premature structuring kills exploration.
+- Marketing copy where the "right answer" comes from A/B tests, not editorial decisions.
+- Poetry. Voice is not decomposable into decision records.
+
+## Examples in the wild
+
+- **Fiction series bibles** — Brandon Sanderson's wikis, the WGA "showrunner bible" pattern — these are exactly `architecture-md.md` content, just predating the convention.
+- **House style guides** — Chicago, AP, NYT, The Economist — these are STYLE.md / EDR collections.
+- **Diátaxis / Divio documentation framework** — already practices most of ops-repo's promises; this skill names what's already happening in well-run docs orgs.
+
+## Greenfield prose setup (analogue of `recipes/greenfield-setup.md`)
+
+Drop these files at the repo root of a manuscript or docs repo:
+
+```
+STYLE.md                                       # canonical style/voice guide (≤200 lines)
+.brain/
+├── config.toml
+├── edrs/0001-record-editorial-decisions.md   # bootstrap EDR
+├── retrospectives/.gitkeep
+├── rituals/.gitkeep
+├── bible/.gitkeep
+└── archive/.gitkeep
+.github/pull_request_template.md               # "Editorial impact" checkbox
+```
+
+The 5 promises ship from day one. EDR 0001 records the decision to use EDRs, exactly mirroring ADR 0001 in the code-greenfield recipe.
+
+## Cross-references
+
+- AGENTS.md spec (the analogue of STYLE.md): `../standards/agents-md-spec.md`
+- Greenfield setup (procedural): `../recipes/greenfield-setup.md`
+- Memory organization (folder layout rationale): `../recipes/memory-organization.md`
+- ADR pattern (the EDR template): `../doc-types/adr-pattern.md`
+- Reliability dial: `../guidance/reliability-dial.md`

package/skills/adia-ui-ops/references/guidance/context-budget.md

@@ -0,0 +1,137 @@
+---
+date: 2026-04-27
+coverage: canonical
+peers:
+  - llm-doc-writing.md
+  - ../audit-patterns/token-waste-detection.md
+  - ../standards/agents-md-spec.md
+primary_sources:
+  - https://code.claude.com/docs/en/best-practices — Anthropic's CLAUDE.md guidance
+  - https://docs.anthropic.com/en/docs/about-claude/models — Claude model context windows
+  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
+status: research-verified
+---
+
+# Context budget (delivers Promise 2)
+
+> **The premise.** Every token in AGENTS.md / CLAUDE.md / loaded docs is a token *not* available for the actual code being worked on. "Token-and-context-optimized" means treating the agent's context window as a budget — and refusing to spend it on prose that could be a link.
+
+## The math
+
+Claude model context windows (April 2026):
+
+| Model | Context window |
+|---|---|
+| Claude Opus 4.7 | **1M tokens** (1,000,000) |
+| Claude Sonnet 4.6 | 200K tokens |
+| Claude Haiku 4.5 | 200K tokens |
+
+That sounds like a lot. It isn't — once you load:
+
+- AGENTS.md / CLAUDE.md (load every session — Anthropic loads CLAUDE.md automatically)
+- The files the agent is editing (often 3-10 files, 200-2000 lines each)
+- The files the agent is *reading* to make decisions (10-50 files easily)
+- Tool-call results (test output, lint errors, build logs)
+- The conversation transcript itself (can grow to 30K+ tokens in long sessions)
+
+A naked 800-line AGENTS.md costs **~10K tokens** — 5% of Sonnet's window, just for the entry file. If `ARCHITECTURE.md` is 1500 lines and gets loaded too, that's another 18K. Now you've spent 14% of the window on metadata before doing any work.
+
+The Opus 4.7 1M window changes the math but not the principle. **Token economy is good engineering regardless of window size** — bigger window means tokens are cheaper, not free.
+
+## Anthropic's load-bearing rule
+
+> Keep CLAUDE.md under ~200 lines. Instruction quality decreases as count increases.
+>
+> — [Anthropic Claude Code best practices](https://code.claude.com/docs/en/best-practices)
+
+The **same ergonomic ceiling applies to AGENTS.md.** This isn't an arbitrary number — it's where empirical observation says adherence drops. Long files are skimmed, ignored, or contradicted by their own later sections.
+
+GitHub's [analysis of 2,500+ AGENTS.md files](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) confirms this — the most-effective files cluster around 50-150 lines.
+
+## Layered docs (the navigability principle)
+
+The ceiling forces a structural choice: **detail goes into linked subfolders, not into the entry file**.
+
+```
+AGENTS.md  (~150 lines: agent persona, build/test/run, conventions, trust
+            boundaries, where-to-find-things, memory primitives)
+   ↓ links to
+ARCHITECTURE.md  (~500 lines: system overview, component map,
+                  data-flow diagrams, deployment topology)
+   ↓ links to
+.brain/adrs/0001-*.md  (each ADR ~100 lines: one decision in depth)
+.brain/postmortems/2026-04-*.md  (each ~150 lines: one incident)
+.brain/runbooks/*.md  (each ~100 lines: one procedure)
+```
+
+The agent loads AGENTS.md every session (~150 lines, ~2K tokens). It loads ARCHITECTURE.md *only when needed* (~7K tokens). It loads a specific ADR *only when about to make a related decision* (~1K tokens).
+
+**Total cost in the common case: 2K tokens. Total cost when deeply needed: ~10K tokens.** Compare to a flat 800-line AGENTS.md (10K every session, even when not relevant).
+
+## The budget breakdown for a healthy repo
+
+A target shape:
+
+| Surface | Line ceiling | Token cost (approx) | When loaded |
+|---|---|---|---|
+| AGENTS.md | 200 | 2-3K | Every session |
+| CLAUDE.md | 15 (thin pointer or symlink) | 0-200 | Every session (Claude Code) |
+| README.md | 200-300 | 3-5K | Sometimes (human-facing) |
+| ARCHITECTURE.md | 500 | 6-8K | When agent needs system overview |
+| .brain/PLAN.md | 200 | 2-3K | When agent needs current priorities |
+| .brain/adrs/<one>.md | 100-200 | 1-3K each | When agent makes architectural decisions |
+| .brain/postmortems/<one>.md | 100-200 | 1-3K each | When agent debugs production issues |
+| .brain/runbooks/<one>.md | 100-200 | 1-3K each | When agent runs operational procedures |
+| `CHANGELOG.md` | (any) | varies | When agent needs version history |
+
+The rule of thumb: **anything an agent needs *every session* must be tiny; everything else can be large but must be reachable on demand**.
+
+## What violates the budget (the trip-wires)
+
+The token-waste-detection audit (Promise 2) flags these specifically:
+
+1. **AGENTS.md or CLAUDE.md > 200 lines** — hard cap.
+2. **AGENTS.md or CLAUDE.md > 150 lines** — warning (approaching cap).
+3. **A `.brain/` file > 500 lines that isn't in `.brain/adrs/`, `.brain/postmortems/`, or `.brain/architecture/`** — likely a place where one big doc should be a folder of smaller ones.
+4. **Repeated content** — the same command listed in AGENTS.md, README.md, AND CONTRIBUTING.md. Pick one canonical, link from the others.
+5. **Verbose prose where bullets would work** — 8 paragraphs explaining what could be a 3-bullet checklist.
+6. **Generated content checked in** — TypeDoc / JSDoc / API reference generated docs that should be regenerated, not committed.
+
+## What does NOT violate the budget
+
+- **Long ADRs** — an ADR should be as long as the decision warrants. Some are 30 lines; some are 300. Don't compress for compression's sake.
+- **Long post-mortems** — same: an incident with a complex root cause needs depth.
+- **CHANGELOG.md** — append-only history, expected to grow without bound. Agents rarely load all of it.
+- **Long ARCHITECTURE.md** — within reason; if it gets >1500 lines, split into `.brain/architecture/`.
+
+## How to reduce a bloated AGENTS.md (the recipe)
+
+Bloated AGENTS.md is the most common failure. Recipe to compress:
+
+1. **Strip "we use TypeScript" lines.** If `tsconfig.json` is present, the agent already knows.
+2. **Strip personal preferences.** Move to `CLAUDE.local.md` (gitignored) or `~/.claude/CLAUDE.md` (user-global).
+3. **Strip TODOs / WIP notes.** Move to `.brain/PLAN.md` and link.
+4. **Strip long history / motivation.** Move to `README.md` or `ARCHITECTURE.md`.
+5. **Compress prose to bullets.** "Run tests with Vitest, our preferred test runner" → "Tests: Vitest".
+6. **Replace inline detail with a link.** "Our deployment uses Cloud Run with the following 14 steps..." → "Deployment: see `.brain/runbooks/deploy.md`".
+7. **Audit for self-contradictions.** A file that contradicts itself is worse than incomplete.
+8. **Re-read the file as if you were the agent.** Anything that doesn't change behavior gets cut.
+
+A 600-line AGENTS.md typically reduces to 120-150 lines without losing instructional value.
+
+## The Anthropic feedback loop applied to context budget
+
+When AGENTS.md grows past 200 lines, two patterns work:
+
+**Pattern A — extract to a linked file.** A "Conventions" section growing past 30 lines becomes `.brain/CONVENTIONS.md` linked from AGENTS.md. The link is permanent; the file can grow.
+
+**Pattern B — ask Claude to compress.** "AGENTS.md is 280 lines. Compress to 180 while preserving all instructional content. Move detail to linked subfolders if needed." This is the inverse of the iterate-pattern: instead of *adding* corrections, *delete* what no longer earns its tokens.
+
+Run pattern B quarterly. The audit can prompt this with a finding: `WARN: AGENTS.md is 240 lines. Run quarterly compression pass.`
+
+## Cross-references
+
+- LLM-doc-writing (companion guidance on content quality): `llm-doc-writing.md`
+- Token-waste detection (the audit pattern that catches violations): `../audit-patterns/token-waste-detection.md`
+- AGENTS.md spec: `../standards/agents-md-spec.md`
+- Self-healing hooks (the pre-commit length check): `../recipes/self-healing-hooks.md`

package/skills/adia-ui-ops/references/guidance/llm-doc-writing.md

@@ -0,0 +1,116 @@
+---
+date: 2026-04-27
+coverage: extended
+peers:
+  - ../standards/agents-md-spec.md
+  - ../standards/claude-md-convention.md
+primary_sources:
+  - https://code.claude.com/docs/en/best-practices — Anthropic Claude Code best practices
+  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/ — empirical study of 2,500+ AGENTS.md files
+  - https://www.humanlayer.dev/blog/writing-a-good-claude-md
+status: research-verified
+---
+
+# Writing AGENTS.md / CLAUDE.md content well
+
+> **The empirical case for short, specific, navigable.** Not a style guide — a set of load-bearing constraints distilled from Anthropic's own best practices and GitHub's analysis of 2,500+ AGENTS.md files in the wild.
+
+## Length
+
+**Anthropic's own guidance for CLAUDE.md is "under ~200 lines."** The same ergonomic ceiling applies to AGENTS.md — instruction quality drops as count rises. Long files are skimmed, ignored, or contradicted by their own later sections.
+
+If you have more than 200 lines of relevant content, push detail into linked subfolders (`ARCHITECTURE.md`, `.brain/adrs/`, `.brain/runbooks/`). The entry file should *navigate to* depth, not *contain* depth.
+
+## What to include (per GitHub's 2,500-repo study)
+
+The most-effective AGENTS.md files share these sections:
+
+1. **Project overview** — one paragraph, what + who + why.
+2. **Build / test / run commands** — exact shell commands, no prose. Wrong commands are worse than missing commands.
+3. **Coding conventions** — short bullets. Style, types, formatting.
+4. **Trust boundaries** — what to modify, what not to. Critical for preventing destructive edits.
+5. **Where to find things** — pointers to subfolders. The skill's load-bearing recommendation.
+6. **Memory primitives** — when to read ADRs, when to check post-mortems.
+
+Sections that don't help LLM agents (move elsewhere):
+
+- Long history / motivation / vision (move to `README.md` or `ARCHITECTURE.md`).
+- Detailed architecture diagrams (move to `ARCHITECTURE.md`; reference from AGENTS.md).
+- Personal preferences (move to `CLAUDE.local.md` or `~/.claude/CLAUDE.md`, gitignored).
+
+## What to delete
+
+Per Anthropic's best-practices doc and HumanLayer's writeup:
+
+- **Delete instructions Claude already follows correctly without being told.** "Use TypeScript" in a TS-only repo is noise.
+- **Delete instructions that contradict each other.** Diff your own AGENTS.md for self-contradictions.
+- **Delete TODOs, comments, work-in-progress notes.** Use `.brain/PLAN.md` instead.
+- **Delete commands that fail.** A wrong `npm test` is worse than no `npm test`.
+
+## Iteration pattern
+
+Anthropic recommends treating AGENTS.md as **live, not frozen**: when the agent makes a mistake, ask it to add a correction to AGENTS.md itself. Over a few weeks the file converges on what's load-bearing.
+
+Don't write AGENTS.md from scratch in one session — author the skeleton, then iterate by **deleting** as Claude proves it doesn't need a given line.
+
+## Hooks > advisory text (where possible)
+
+Per Anthropic: prefer **hooks** for deterministic behavior, not AGENTS.md text. A hook always executes; advisory text is suggestion.
+
+Examples:
+- "Run `pnpm typecheck` before committing" → write a `pre-commit` hook in `.husky/pre-commit`.
+- "Don't edit `db/migrations/`" → enforce via CODEOWNERS or branch protection, not AGENTS.md prose.
+
+AGENTS.md should explain *why* and reference the hook; the hook does the work.
+
+## The "agent persona + boundaries + commands" pattern
+
+GitHub's empirical study found this three-part shape works well:
+
+```markdown
+# AGENTS.md
+
+## You are
+A senior Rust engineer working on a high-throughput web service.
+Prioritize correctness over cleverness.
+
+## Boundaries
+- DO NOT: modify `migrations/`, generated code under `gen/`, `Cargo.lock`
+- DO: write tests for every public function; run `cargo fmt` and `cargo clippy` before committing
+- ASK: before changing anything in `crates/core/`
+
+## Commands
+build:  `cargo build --release`
+test:   `cargo test --workspace`
+lint:   `cargo clippy --all-targets -- -D warnings`
+fmt:    `cargo fmt --all -- --check`
+run:    `cargo run --bin server`
+
+## Where to find things
+- Architecture overview: `ARCHITECTURE.md`
+- ADRs: `.brain/adrs/`
+- Postmortems: `.brain/postmortems/`
+- Runbooks: `.brain/runbooks/`
+- Active plan: `.brain/PLAN.md`
+
+_Last reviewed: 2026-04-27_
+```
+
+50-60 lines. Sufficient for most repos.
+
+## Anti-patterns (what shows up in stale AGENTS.md / CLAUDE.md)
+
+1. **The 800-line dump.** Nobody reads it; the agent doesn't either.
+2. **The "we use TypeScript" file.** Noise — it's already in `tsconfig.json`.
+3. **Stale build commands.** Repo migrated to pnpm a year ago; AGENTS.md still says `npm`. The audit catches this by comparing to the lockfile.
+4. **The duplicated CLAUDE.md.** AGENTS.md and CLAUDE.md both fat, drifted apart.
+5. **No "Where to find things."** Naked entry; agent has nothing to navigate to.
+6. **Personal preferences in the committed file.** "I like 2-space indents" → move to `CLAUDE.local.md` (gitignored).
+7. **TODOs that never got done.** "// TODO: document the auth flow" sitting in AGENTS.md for a year.
+
+## Cross-references
+
+- AGENTS.md spec: `../standards/agents-md-spec.md`
+- CLAUDE.md as thin pointer / symlink: `../standards/claude-md-convention.md`
+- Audit checks: `../audit-patterns/entry-file-coverage.md`
+- Staleness detection tooling: `../audit-patterns/staleness-tooling.md`