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

package/skills/adia-ui-ops/references/audit-patterns/spec-dating-sweep.md

@@ -1,91 +0,0 @@
-# Spec dating sweep (git-mtime batch)
-
-**Added:** 2026-05-02 after F-A7 finding identified ~25 spec files
-lacking date markers.
-
-## The drift class
-
-Files in `docs/specs/` (or the project's spec dir) should have a
-`date:` frontmatter or `_Last reviewed: YYYY-MM-DD_` line. Without
-this, future readers can't tell if the spec is current, when it was
-last reviewed, or whether to cross-check against more recent
-journal entries.
-
-The standard fix is "add a `_Last reviewed: <date>_` line." But
-hard-coding today's date is wrong — it asserts a review that didn't
-happen for files you haven't read.
-
-## Detection
-
-```bash
-for f in docs/specs/*.md; do
-  if ! grep -qE "^date:|Last reviewed|_Date:_" "$f"; then
-    echo "  $(basename "$f")"
-  fi
-done
-```
-
-## Fix recipe (mechanical Python batch using git-mtime)
-
-Use git's last-modification date as the proxy for content freshness:
-
-```python
-import pathlib, re, subprocess
-
-ROOT = pathlib.Path("/path/to/repo")
-SPECS = ROOT / "docs/specs"
-
-def has_date_marker(text):
-    head = text[:1500]
-    return bool(re.search(r"^date:\s*\d{4}-\d{2}-\d{2}", head, re.MULTILINE)) or \
-           "Last reviewed:" in head or "_Date:_" in head
-
-def git_mtime(p):
-    try:
-        out = subprocess.check_output(
-            ["git", "log", "-1", "--format=%cs", "--", str(p)],
-            cwd=ROOT, text=True, stderr=subprocess.DEVNULL
-        ).strip()
-        return out if out else "TODAY"
-    except subprocess.CalledProcessError:
-        return "TODAY"
-
-count = 0
-for p in sorted(SPECS.glob("*.md")):
-    if p.name == "INDEX.md":
-        continue
-    text = p.read_text()
-    if has_date_marker(text):
-        continue
-    mtime = git_mtime(p)
-    lines = text.splitlines()
-    h1_idx = next((i for i, l in enumerate(lines) if l.startswith("# ")), None)
-    if h1_idx is None:
-        continue
-    new_lines = lines[:h1_idx+1] + [""] + [f"_Last reviewed: {mtime}_"] + lines[h1_idx+1:]
-    p.write_text("\n".join(new_lines) + "\n")
-    count += 1
-    print(f"  {p.name} → _Last reviewed: {mtime}_")
-
-print(f"\nDated {count} files")
-```
-
-## Why git-mtime, not today's date
-
-- **Accurate:** the file genuinely was reviewed when it was last
-  edited; using that date doesn't lie.
-- **Stable:** running the script idempotently doesn't push every
-  spec's "Last reviewed" forward to today.
-- **Surface-able:** `find docs/specs -name '*.md' -mtime +180` plus
-  the dated content tells you which specs need an actual review.
-
-## Prevention
-
-The `format-hygiene` audit category catches new undated files. The
-batch sweep runs once on a backlog; ongoing prevention is via the
-audit's per-PR check.
-
-## Related
-
-- `format-hygiene` audit pattern (sibling).
-- `stale-audit` skill check #5.

package/skills/adia-ui-ops/references/audit-patterns/stale-content.md

@@ -1,182 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - staleness-tooling.md
-  - pointer-validation.md
-  - orphan-detection.md
-  - redundancy-detection.md
-  - ../recipes/self-healing-hooks.md
-  - ../recipes/continuous-learning-loop.md
-primary_sources:
-  - https://djw.fyi/portfolio/preventing-drift/ — Daryl White, "Avoiding the Silent Stale Doc Problem"
-  - https://git-scm.com/docs/git-log — git log committer-date semantics
-  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
-status: research-verified
----
-
-# Stale-content detection (delivers Promise 3, "less-prone-to-staleness")
-
-> **The premise.** A doc can have intact links, no orphans, and a clean structure — and still be wrong. *Stale content* is the case where the prose, examples, or commands no longer match the code they describe. This is the hardest staleness class to detect because there's no broken pointer to grep for; the rot is semantic. Three heuristics catch most of it cheaply. The rest needs LLM-on-diff (covered in `staleness-tooling.md`).
-
-## Where this fits
-
-`staleness-tooling.md` covers the *tools* (lychee, Vale, markdownlint, LLM-on-diff). This file covers the *patterns* — the heuristic checks the audit runs against the repo. Pair them: the tool tells you *what to run*, the pattern tells you *what to look for*.
-
-## Three heuristics
-
-| # | Heuristic | What it catches | Cost |
-|---|---|---|---|
-| 1 | **Git-mtime + missing dated frontmatter** | Docs nobody has touched in 6+ months that also nobody has explicitly re-affirmed | Cheap (one `find` + one `grep`) |
-| 2 | **Symbol/path references in prose vs `git ls-files`** | Docs that mention class/function/file names that no longer exist in the codebase | Cheap (grep + set diff) |
-| 3 | **Commands in docs vs current package manifest** | AGENTS.md says `npm install` but `pnpm-lock.yaml` is the only lockfile; or `python setup.py` but the project moved to `uv` | Medium (a few `jq` / file-existence checks) |
-
-These three together catch the bulk of stale content. The long tail (semantic rot in prose) needs LLM-on-diff per `staleness-tooling.md`.
-
-## Heuristic 1 — git-mtime + missing dated frontmatter
-
-A doc unmodified for >6 months *and* without a `_Last reviewed: YYYY-MM-DD_` line is probably stale. The "AND" is critical: a 4-year-old `docs/architecture.md` re-reviewed quarterly is not stale.
-
-```bash
-#!/usr/bin/env bash
-# scripts/find-stale-by-age.sh
-set -euo pipefail
-threshold_days=180
-now=$(date +%s)
-find .brain docs -type f -name '*.md' \
-    -not -path '.brain/archive/*' -not -path '.brain/adrs/*' -not -path '.brain/postmortems/*' \
-    -not -path 'docs/archive/*' -not -path 'docs/adrs/*' -not -path 'docs/postmortems/*' \
-    | while read -r f; do
-        last=$(git log -1 --format=%ct -- "$f" 2>/dev/null || echo 0)
-        [ "$last" -eq 0 ] && continue
-        age=$(( (now - last) / 86400 ))
-        [ "$age" -le "$threshold_days" ] && continue
-        if rev=$(grep -oE '_Last reviewed:[[:space:]]*[0-9]{4}-[0-9]{2}-[0-9]{2}' "$f" \
-                 | grep -oE '[0-9]{4}-[0-9]{2}-[0-9]{2}' | head -1); then
-            ru=$(date -j -f '%Y-%m-%d' "$rev" +%s 2>/dev/null \
-                 || date -d "$rev" +%s 2>/dev/null || echo 0)
-            [ $(( (now - ru) / 86400 )) -le "$threshold_days" ] && continue
-            echo "STALE-AGE: $f (commit ${age}d ago; review $(( (now - ru) / 86400 ))d ago)"
-        else
-            echo "STALE-AGE: $f (commit ${age}d ago; no _Last reviewed:_ line)"
-        fi
-    done
-```
-
-Excluded folders: ADRs (immutable — see `../doc-types/adr-pattern.md`) and post-mortems (describe a fixed past event). Use `git log` committer-date, not filesystem mtime — `clone`/`rebase`/`worktree` clobber filesystem mtime.
-
-## Heuristic 2 — symbol/path references vs `git ls-files`
-
-A doc *names* something (class, function, file path) that the code no longer contains. Catches the canonical class-renamed-doc-not-updated case.
-
-```bash
-#!/usr/bin/env bash
-# scripts/find-stale-symbols.sh
-set -euo pipefail
-all_paths=$(git ls-files | sort -u)
-find .brain docs -type f -name '*.md' \
-    -not -path '.brain/archive/*' -not -path '.brain/adrs/*' -not -path '.brain/postmortems/*' \
-    -not -path 'docs/archive/*' -not -path 'docs/adrs/*' -not -path 'docs/postmortems/*' \
-    | while read -r f; do
-        # Backticked file paths.
-        grep -oE '`[a-zA-Z0-9_./-]+\.(ts|tsx|js|jsx|py|go|rs|java|rb|json|toml|yaml|yml)`' "$f" \
-            | tr -d '`' | sort -u | while read -r ref; do
-                grep -qxF "$ref" <<<"$all_paths" || echo "STALE-PATH: $f -> $ref"
-            done
-        # Backticked PascalCase identifiers (cheap class-name proxy).
-        grep -oE '`[A-Z][a-zA-Z0-9_]{3,}`' "$f" \
-            | tr -d '`' | sort -u | while read -r sym; do
-                git grep -q -wF "$sym" -- ':!*.md' ':!.brain/**' ':!docs/**' 2>/dev/null \
-                    || echo "STALE-SYMBOL: $f -> $sym"
-            done
-    done
-```
-
-False-positive sources: symbols inside before/after code blocks; aliased symbols (`Foo = Bar`); test-only definitions. Emit as **advisory** — human reviews before acting.
-
-## Heuristic 3 — commands vs package manifest
-
-AGENTS.md says `npm install` but only `pnpm-lock.yaml` exists; the agent runs npm and pollutes the repo with `package-lock.json`. Precise enough to gate as a pre-commit check.
-
-```bash
-#!/usr/bin/env bash
-# scripts/check-commands-vs-manifest.sh
-set -euo pipefail
-fail=0
-pm=""
-if   [ -f pnpm-lock.yaml ];                      then pm=pnpm
-elif [ -f yarn.lock ];                           then pm=yarn
-elif [ -f bun.lockb ] || [ -f bun.lock ];        then pm=bun
-elif [ -f package-lock.json ];                   then pm=npm
-fi
-for f in AGENTS.md CLAUDE.md README.md CONTRIBUTING.md; do
-    [ -f "$f" ] && [ ! -L "$f" ] || continue
-    if [ -n "$pm" ]; then
-        awk '/^```(bash|sh|shell|console)/,/^```$/' "$f" \
-            | grep -oE '\b(npm|pnpm|yarn|bun)\b' | sort -u | while read -r p; do
-                [ "$p" != "$pm" ] && { echo "STALE-CMD: $f uses '$p'; lockfile is '$pm'"; fail=1; }
-            done
-    fi
-    if [ -f uv.lock ]; then
-        awk '/^```(bash|sh|shell|console)/,/^```$/' "$f" \
-            | grep -qE '\b(pip install|python setup\.py)\b' \
-            && { echo "STALE-CMD: $f uses pip/setup.py; uv.lock present"; fail=1; }
-    fi
-done
-exit $fail
-```
-
-Extend per ecosystem: Cargo, Go modules, Bundler. Same pattern — canonical manifest vs command-block PM/runner mismatch.
-
-## Putting the three together
-
-The full stale-content pass:
-
-```bash
-echo "=== Heuristic 1: age ==="
-bash scripts/find-stale-by-age.sh
-
-echo "=== Heuristic 2: symbols ==="
-bash scripts/find-stale-symbols.sh
-
-echo "=== Heuristic 3: commands ==="
-bash scripts/check-commands-vs-manifest.sh
-```
-
-Run weekly per `../recipes/self-healing-hooks.md`'s scheduled cron. Findings are filed as a single weekly issue, not as commit-blocking errors — these heuristics produce false positives and shouldn't gate merges.
-
-The exception: heuristic 3 is precise enough to gate. If `pnpm-lock.yaml` exists and AGENTS.md says `npm install`, that's an unambiguous bug — wire it as a pre-commit check.
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| Heuristic 3 — command mismatch (AGENTS.md says `npm` + `pnpm-lock.yaml`) | High | Agent will run wrong PM and pollute repo |
-| Heuristic 2 — symbol referenced in AGENTS.md no longer exists | High | Canonical doc misleads agent on every session |
-| Heuristic 2 — symbol referenced in `.brain/**` or `docs/**` no longer exists | Medium | Lower visibility but still wrong |
-| Heuristic 1 — doc >6mo old, no review line | Medium | Likely-but-not-certainly stale; advisory |
-| Heuristic 1 — doc >12mo old, no review line | High | Almost certainly stale |
-
-## What this pattern is NOT for
-
-- **Broken intra-repo links** — that's `pointer-validation.md`. Stale content is about *correct prose about wrong code*, not about links.
-- **External link rot** — `staleness-tooling.md`'s lychee.
-- **Live external links pointing at outdated content** — that's a separate concern. `lychee` confirms the URL responds; it doesn't check whether the *fetched content still matches what the doc claims*. For that, see `../recipes/external-reference-verification.md` (WebFetch-powered, autoresearch-DNA).
-- **Outdated dependency versions in lockfiles** — out of doc-audit scope; that's a Dependabot / Renovate problem.
-- **Generic "the doc is too short / shallow"** — quality issues, not staleness; covered by `../guidance/llm-doc-writing.md`.
-
-## Companion: when these heuristics aren't enough
-
-For semantic rot the heuristics miss ("the doc says we use Postgres but actually we migrated to PlanetScale six months ago" — no symbol-name overlap, no command-block giveaway), the answer is **LLM-on-diff** per `staleness-tooling.md`. On every PR, an LLM compares the code diff against `AGENTS.md` and `.brain/**` + `docs/**` and flags doc sections that should have changed. It's the most expensive layer (API calls per PR) and it's gated on `vars.LLM_DOC_DRIFT_ENABLED` per `../recipes/self-healing-hooks.md`.
-
-The three heuristics in this file are the cheap baseline; LLM-on-diff is the deeper-but-pricier complement.
-
-## Cross-references
-
-- Tooling for staleness (lychee, Vale, markdownlint, LLM-on-diff): `staleness-tooling.md`
-- Pointer validation (link-level rot): `pointer-validation.md`
-- Orphan detection (unreachable docs): `orphan-detection.md`
-- Redundancy detection (drift between fat files): `redundancy-detection.md`
-- Self-healing hooks (where the cron runs): `../recipes/self-healing-hooks.md`
-- Continuous-learning loop (how AGENTS.md *stops* going stale): `../recipes/continuous-learning-loop.md`
-- External-reference verification (WebFetch-powered; catches the gap above): `../recipes/external-reference-verification.md`

package/skills/adia-ui-ops/references/audit-patterns/staleness-tooling.md

@@ -1,156 +0,0 @@
----
-date: 2026-04-27
-coverage: extended
-peers:
-  - stale-content.md
-  - pointer-validation.md
-  - ../guidance/llm-doc-writing.md
-primary_sources:
-  - https://github.com/lycheeverse/lychee — fast Markdown/HTML link checker (Rust)
-  - https://github.com/lycheeverse/lychee-action — GitHub Action
-  - https://vale.sh/ — markup-aware prose linter
-  - https://github.com/DavidAnson/markdownlint — Markdown structure linter
-  - https://djw.fyi/portfolio/preventing-drift/ — Daryl White, "Avoiding the Silent Stale Doc Problem"
-  - https://docuwriter.ai/ — commercial code-doc-drift product
-status: research-verified
----
-
-# Tooling for staleness detection
-
-> **What to actually run** when the audit needs help finding stale links, broken references, prose smells, and code/doc drift. The skill itself implements the simplest checks (existence, last-modified, broken pointers); for deeper coverage, reach for these tools.
-
-## Link checking — `lychee`
-
-**`lychee`** ([lycheeverse/lychee](https://github.com/lycheeverse/lychee)) is a fast Markdown/HTML/RST/text link checker written in Rust. It's the de-facto standard.
-
-Run locally:
-
-```bash
-lychee --offline --no-progress '.brain/**/*.md' 'docs/**/*.md' '*.md' '*.MD'
-# --offline skips network; useful for fast intra-repo link audit
-# drop --offline to also check external URLs
-```
-
-GitHub Actions:
-
-```yaml
-# .github/workflows/links.yml
-name: Links
-on:
-  pull_request: { paths: ['**.md'] }
-  schedule: [{ cron: '0 0 * * 1' }]  # Mondays
-jobs:
-  links:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: lycheeverse/lychee-action@v2
-        with:
-          args: --cache --max-cache-age=1d --no-progress '.brain/**/*.md' 'docs/**/*.md' '*.md'
-          fail: true
-```
-
-The cache is essential — without it, GitHub rate-limits external link checks quickly.
-
-Older alternative: `markdown-link-check` (Node). Slower; lychee is preferred.
-
-## Prose linting — `Vale`
-
-**`Vale`** ([vale.sh](https://vale.sh/)) is a markup-aware prose linter — used by Datadog, Grafana, Elastic, Microsoft, and others. Custom rule packs let you enforce a style guide (sentence length, weasel words, branding terms, Markdown conventions).
-
-Useful for the audit only when the project has a content style guide. If not, skip.
-
-```bash
-vale .brain/ docs/
-```
-
-## Markdown structure linting — `markdownlint`
-
-**`markdownlint`** ([DavidAnson/markdownlint](https://github.com/DavidAnson/markdownlint)) checks Markdown structure (heading levels, list indentation, blank lines, etc.). Doesn't check freshness; complements lychee.
-
-```bash
-markdownlint .brain/ docs/ *.md
-```
-
-## Code/doc drift detection — the genuinely hard one
-
-There's no canonical OSS tool for "this code change should have updated this doc." Two pragmatic approaches in 2026:
-
-### LLM-on-diff (the popular DIY)
-
-Per [Daryl White's "Avoiding the Silent Stale Doc Problem"](https://djw.fyi/portfolio/preventing-drift/): a GitHub Action that, on each PR, asks an LLM whether the code diff requires doc updates and which docs.
-
-Sketch:
-
-```yaml
-# .github/workflows/doc-drift.yml
-name: Doc drift
-on: pull_request
-jobs:
-  drift:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }
-      - run: |
-          git diff origin/${{ github.base_ref }}...HEAD --stat > /tmp/diff.txt
-          # Pipe /tmp/diff.txt + AGENTS.md + .brain/ + docs/ index into an LLM that
-          # returns "no doc changes needed" or "consider updating: <list>".
-          # Post as a PR comment.
-```
-
-This is bespoke per project but cheap to maintain.
-
-### DocuWriter.ai (commercial)
-
-[docuwriter.ai](https://docuwriter.ai/) — uses git diff webhooks + LLM analysis to flag doc-relevant code changes. Useful for large repos where the DIY pattern is too noisy.
-
-## Git-heuristic staleness (DIY, baseline)
-
-The simplest staleness signal: file last-modified date. The skill itself can implement this directly:
-
-```bash
-# Files in .brain/ + docs/ older than 6 months without a "Last reviewed" line:
-find .brain docs -name '*.md' -mtime +180 | while read f; do
-  if ! grep -q '_Last reviewed:' "$f"; then
-    echo "STALE: $f (last modified: $(git log -1 --format=%cs -- "$f"))"
-  fi
-done
-```
-
-Use `git log` mtime rather than filesystem mtime — filesystem mtime can be misleading after `git clone` or rebase.
-
-## Composing the staleness pass
-
-Recommended order:
-
-1. **Existence + entry-file pointers** (skill internal) — what does the entry say, what's actually there
-2. **lychee** — flag broken intra-repo and external links
-3. **markdownlint** — flag structural issues
-4. **Git-heuristic mtime check** — flag undated docs older than threshold
-5. **Vale** (if project has style guide) — flag prose smells
-6. **LLM-on-diff** (in CI, ongoing) — flag PRs that should have updated docs
-
-The first four are fast; run them on every audit. The last two are slower / more bespoke; run them in CI.
-
-## What to put in the audit report
-
-For each stale finding:
-
-```markdown
-- **STALE — `docs/architecture.md`** (severity: medium)
-  - Last modified: 2024-09-12 (583 days ago).
-  - No `_Last reviewed:_` line.
-  - References `class FooHandler` which was renamed to `RequestHandler` in commit `abc123` (2025-03-15).
-  - **Tools that flagged this:**
-    - mtime-heuristic (older than 6mo, undated)
-    - intra-repo grep (referenced symbol no longer exists)
-  - **Recommendation:** review and re-date, OR archive to `.brain/archive/architecture-2024.md`.
-```
-
-## Cross-references
-
-- General staleness audit pattern: `stale-content.md`
-- Pointer validation: `pointer-validation.md`
-- LLM-doc-writing guidance: `../guidance/llm-doc-writing.md`
-- Full audit recipe: `../recipes/audit-existing-repo.md`

package/skills/adia-ui-ops/references/audit-patterns/token-waste-detection.md

@@ -1,196 +0,0 @@
----
-date: 2026-04-27
-coverage: canonical
-peers:
-  - redundancy-detection.md
-  - ../guidance/context-budget.md
-  - ../guidance/llm-doc-writing.md
-  - ../recipes/self-healing-hooks.md
-primary_sources:
-  - https://code.claude.com/docs/en/best-practices
-  - https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/
-status: research-verified
----
-
-# Token-waste detection (delivers Promise 2, "token-and-context-optimized")
-
-> **The premise.** A token loaded into context is a token not available for the work being done. Every byte of AGENTS.md / CLAUDE.md / loaded docs has to *earn its place* — by changing agent behavior in a way no other doc does. This audit catches the bytes that aren't earning.
-
-## The five token-waste smells
-
-| # | Smell | What it looks like | Severity |
-|---|---|---|---|
-| 1 | **Bloated entry file** | AGENTS.md or CLAUDE.md > 200 lines | High |
-| 2 | **Bloated subfolder doc** | `docs/<not-adrs-or-postmortems>/<file>.md` > 500 lines | Medium |
-| 3 | **Verbose prose** | Long paragraphs where bullets / tables work | Low |
-| 4 | **Cross-doc repetition** | Same content in 3+ files | Medium (handled in `redundancy-detection.md`) |
-| 5 | **Redundant frontmatter / boilerplate** | Long YAML frontmatter, license headers, generated tables of contents in every file | Low |
-
-## Smell 1 — bloated entry files (the critical one)
-
-**The check:** `wc -l AGENTS.md CLAUDE.md`. Anthropic's published guidance is `<200 lines`; we warn at 150 and fail at 200.
-
-**Why it matters:** entry files are loaded *every session*. A 400-line AGENTS.md costs ~5K tokens *every time the agent starts work*. Across a hundred sessions in a year, that's 500K tokens spent on metadata — a meaningful chunk of any per-developer LLM budget, before doing any work.
-
-**Auto-detection:**
-
-```bash
-# Pre-commit hook (also in self-healing-hooks.md)
-for f in AGENTS.md CLAUDE.md; do
-    [ -f "$f" ] && [ ! -L "$f" ] || continue
-    n=$(wc -l < "$f")
-    if [ "$n" -gt 200 ]; then
-        echo "ERROR: $f is $n lines (>200). See guidance/context-budget.md."
-        exit 1
-    elif [ "$n" -gt 150 ]; then
-        echo "WARN: $f is $n lines (>150). Consider compression."
-    fi
-done
-```
-
-**Fix recipe:** see `../guidance/context-budget.md` "How to reduce a bloated AGENTS.md (the recipe)" — the 8-step compression pass typically takes a 600-line entry file to 150 without losing instructional value.
-
-## Smell 2 — bloated subfolder docs
-
-**The check:** `find .brain docs -name '*.md' -not -path '.brain/adrs/*' -not -path '.brain/postmortems/*' -not -path '.brain/architecture/*'` and any file with `wc -l > 500`.
-
-**Why it matters:** unlike entry files, subfolder docs aren't loaded every session — but a bloated `docs/setup.md` (1200 lines) is a sign the doc has become a dumping ground rather than a focused unit. Split into a folder.
-
-**Exceptions:**
-
-- `.brain/adrs/<one>.md` can be any length — one ADR captures one decision in full.
-- `.brain/postmortems/<one>.md` can be any length — incidents need depth.
-- `.brain/architecture/<one>.md` may be long; consider splitting into multiple files in the folder if so.
-- `CHANGELOG.md` is append-only; it grows without bound.
-
-**Auto-detection:**
-
-```bash
-find .brain docs -name '*.md' -type f \
-    -not -path '.brain/adrs/*' \
-    -not -path '.brain/postmortems/*' \
-    -not -path '.brain/architecture/*' \
-    -not -path '.brain/archive/*' \
-    | while read f; do
-        n=$(wc -l < "$f")
-        if [ "$n" -gt 500 ]; then
-            echo "$f: $n lines (consider splitting into a folder)"
-        fi
-    done
-```
-
-**Fix recipe:** if `docs/setup.md` is 1200 lines covering "first-time setup", "deployment", "troubleshooting", "FAQ" — split:
-
-```
-docs/setup/
-├── README.md           (~30 lines: index)
-├── first-time.md       (~150)
-├── deployment.md       (~200)
-├── troubleshooting.md  (~300)
-└── faq.md              (~150)
-```
-
-Update entry-file pointers from `docs/setup.md` → `docs/setup/`.
-
-## Smell 3 — verbose prose
-
-**The check:** prose-vs-bullet ratio. A heuristic: paragraphs longer than 4 sentences, especially in the `Conventions` or `Build` sections of AGENTS.md, are usually compressible.
-
-**Why it matters:** the agent doesn't need narrative — it needs constraints. "We use TypeScript with strict mode enabled because we value type safety and prefer to catch errors at compile time rather than runtime" is twice the tokens of "TypeScript: strict" and worse for the agent.
-
-**Auto-detection:** hard to automate cleanly. Practical approach: a script that flags any AGENTS.md / CLAUDE.md paragraph >300 characters as a review candidate.
-
-```bash
-# Find long paragraphs (>300 chars between blank lines) in AGENTS.md
-awk -v RS='' -v ORS='\n\n' '{ if (length($0) > 300 && !/^#/) print NR": "$0 }' AGENTS.md
-```
-
-**Fix recipe:** convert prose to bullets or tables. Test: can you read it as instructions to follow? If yes, bullets. If no (it's actually motivation/context), move to a different file.
-
-## Smell 4 — cross-doc repetition
-
-Detailed in `redundancy-detection.md`. Token cost is 2× / 3× / Nx of the same content loaded N times.
-
-## Smell 5 — redundant frontmatter / boilerplate
-
-**The check:** YAML frontmatter that's longer than 5-10 lines per file, or boilerplate (license headers, "this file is auto-generated", boilerplate ToCs) that adds bytes without information.
-
-**Why it matters:** small per-file but it adds up. A 50-line license header in every doc, across 80 docs, is 4000 lines of pure tax.
-
-**Auto-detection:**
-
-```bash
-# Find files with YAML frontmatter >10 lines
-for f in .brain/**/*.md docs/**/*.md *.md; do
-    [ -f "$f" ] || continue
-    if head -1 "$f" | grep -q '^---'; then
-        end=$(awk '/^---/{i++; if(i==2) print NR}' "$f")
-        [ -n "$end" ] && [ "$end" -gt 12 ] && echo "$f: frontmatter is $end lines"
-    fi
-done
-```
-
-**Fix recipe:**
-- Trim YAML frontmatter to: `date`, `coverage`, `peers`, `primary_sources`, `status`. That's it.
-- Move license headers into a single `LICENSE` file at the root (which is the convention anyway).
-- Generate ToCs at render time, not commit time. (For GitHub-rendered docs, the GitHub UI renders the ToC; don't commit one.)
-
-## What does NOT count as token waste
-
-- **Long ADRs** — one architectural decision captured in full is the right shape; don't compress for its own sake.
-- **Long post-mortems** — incidents with complex root causes need depth.
-- **Long CHANGELOG.md** — append-only history.
-- **Long ARCHITECTURE.md (within reason)** — under ~1500 lines, the depth is earning its tokens. Past that, split.
-- **Code examples** — if an example illustrates a non-obvious pattern, it's earning its place. If it's restating something obvious, cut it.
-
-## The full audit pass
-
-```bash
-# 1. Entry file length
-for f in AGENTS.md CLAUDE.md; do
-    [ -f "$f" ] && [ ! -L "$f" ] || continue
-    n=$(wc -l < "$f")
-    [ "$n" -gt 150 ] && echo "ENTRY-FILE-LENGTH: $f = $n lines"
-done
-
-# 2. Subfolder bloat
-find .brain docs -name '*.md' -type f \
-    -not -path '.brain/adrs/*' \
-    -not -path '.brain/postmortems/*' \
-    -not -path '.brain/architecture/*' \
-    -not -path '.brain/archive/*' \
-    | while read f; do
-        n=$(wc -l < "$f")
-        [ "$n" -gt 500 ] && echo "SUBFOLDER-BLOAT: $f = $n lines"
-    done
-
-# 3. Verbose prose in entry files
-for f in AGENTS.md CLAUDE.md; do
-    [ -f "$f" ] && [ ! -L "$f" ] || continue
-    awk -v f="$f" -v RS='' '{ if (length($0) > 300 && !/^#/) print "VERBOSE-PARA: "f": "substr($0,1,80)"..." }' "$f"
-done
-
-# 4. Frontmatter bloat
-for f in $(find . -name '*.md' -type f -not -path '*/node_modules/*'); do
-    head -1 "$f" 2>/dev/null | grep -q '^---' || continue
-    end=$(awk '/^---/{i++; if(i==2){ print NR; exit }}' "$f")
-    [ -n "$end" ] && [ "$end" -gt 12 ] && echo "FRONTMATTER-BLOAT: $f = $end lines"
-done
-```
-
-## Severity rubric
-
-| Finding | Severity | Why |
-|---|---|---|
-| Entry file >200 lines | High | Loaded every session; per-session waste |
-| Entry file 150-200 | Medium | Approaching ceiling |
-| Subfolder doc >500 (non-ADR/postmortem) | Medium | One-off cost when loaded; structural smell |
-| Verbose prose in entry file | Low | Per-session waste, individually small |
-| Frontmatter bloat | Low | Per-file waste, individually small |
-
-## Cross-references
-
-- Context budget (the math behind these limits): `../guidance/context-budget.md`
-- Redundancy detection (cross-doc repetition): `redundancy-detection.md`
-- LLM-doc-writing (content-quality companion): `../guidance/llm-doc-writing.md`
-- Self-healing hooks (where these checks run automatically): `../recipes/self-healing-hooks.md`