incitaciones 0.13.0 → 0.14.0

package/README.md

@@ -531,3 +531,8 @@ The LLM writes. The human knows what it should say.
 There is a distinction, even if looking at the commit history makes it hard to find. The distinction is that a machine can produce correct code without understanding anything, the same way a calculator can solve an integral without knowing what time is. Understanding what that integral is *for*, whether it actually solves the problem, whether the problem was the right problem to begin with — that remains human territory. For now.
 
 [Leer en español](https://charly-vibes.github.io/charly-vibes/)
+
+## Documentation provenance
+
+Rendered docs are generated artifacts; the repository sources are
+authoritative — edit the repo sources, not the rendered output.

package/content/distilled/documentation/references/implement-documentation/SKILL.md

@@ -17,7 +17,10 @@ Write a high-signal documentation topic using the Unified Frameworks for Technic
 2. EPPO initialization: every topic must stand alone. Start with a clear task- or concept-focused title and a context block ("This topic covers [X]. You should already understand [Y] and have [Z] installed.").
 3. Information mapping: chunk the body into units under 7 items; label headers by result or content (e.g., "Configuring the API" not "Configuration"); convert complex comparisons or steps into tables and lists.
 4. AI-first polish: ensure headers are descriptive for RAG indexing and provide a 1-2 sentence TL;DR at the top for LLM ingestion.
-5. If setting up a new docs site or choosing tooling, use `references/tooling-comparison.md` for platform selection and `references/versioning.md` for versioning and changelog strategy. For a full Diátaxis rollout, use `references/diataxis-implementation.md`.
+5. If the topic is a tutorial, quickstart, or introduces user-facing commands, use `references/worked-examples.md`: it defines the worked-example pattern (one evolving example thread, not disconnected snippets), the quickstart rule (every command shows its expected output and exit code; every install path ends with a post-install verification block), and the example coverage matrix (map every user-facing feature to at least one example page).
+6. If setting up a new docs site or choosing tooling, use `references/tooling-comparison.md` for platform selection and `references/versioning.md` for versioning and changelog strategy. For a full Diátaxis rollout, use `references/diataxis-implementation.md`.
+7. If the topic shows user-facing commands or the docs ship generated artifacts, use `references/docs-accuracy.md`: it defines the docs-accuracy gate (CI re-runs documented commands and diffs normalized captured output against the docs), the stamped-artifact rule (`llms.txt`, `release.md`, README version facts are generated per release, with a freshness check that fails on hand-edits), and the live-site smoke (CI curls the deployed URL so a 404 fails in the pipeline, not at the next human visit).
+8. If the topic embeds diagrams or documents a multi-repo ecosystem, use `references/visual-cross-repo.md`: it defines the static-SVG rule (prefer pre-rendered, build-regenerated SVG over runtime mermaid on static-site books), the fleet pattern (one responsibility map per layer linking to each project's docs, a shared setup template, fleet-wide pages living in exactly one hub repo), and the deployed-vs-source smoke (after deploy, verify rendered behavior — JS errors, diagram rendering, search index — on top of the live-site smoke's reachability check).
 
 ## Rules
 

package/content/distilled/documentation/references/implement-documentation/references/docs-accuracy.md

@@ -0,0 +1,111 @@
+# Executable Docs: Accuracy Gate, Stamped Artifacts & Live-Site Smoke
+
+Methodology for making documentation machine-checked instead of read-checked.
+Mined from the 2026-10 specodelic and ddl docs work; evidence in
+`.wai/resources/reflections/docs-skill-survey-2026-10.org` (row `lf4b.10`/`.11`).
+Canonical theory: `content/research-documentation-frameworks.md`.
+
+The 2026-10 evidence: docs that only humans check drift silently. The fixes are
+three CI gates — the docs-accuracy gate re-runs documented commands and diffs
+their real output against the docs; stamped artifacts are regenerated per
+release and lint-checked for hand-edits; a live-site smoke curls the deployed
+URL so a 404'd book fails in CI, not at the next human visit.
+
+## 1. The Docs-Accuracy Gate (CI re-runs the documented commands)
+
+Specodelic `lf4b.10` built a gate that re-runs the quickstart commands and
+diffs captured output against the documented snippets (in `docs/src`). The
+quickstart rule from `worked-examples.md` makes commands claimable; the gate
+makes those claims executable. A doc that says one thing and outputs another
+fails the build instead of embarrassing the maintainer in an issue thread.
+
+Gate shape:
+
+1. Inventory the documented commands (the quickstart and how-to pages are
+   usually enough; every command in the example coverage matrix qualifies).
+2. In CI, run each command, capture stdout/stderr and the exit code.
+3. Normalize the capture (see capture-normalize below).
+4. Diff the normalized capture against the documented snippet. Any drift —
+   including an output the docs no longer show — fails the build.
+
+The capture-normalize technique (specodelic commit `a2108b8`): before diffing,
+normalize tool chatter on **both sides with the same rules**. Real output is
+full of volatility that is not part of the contract:
+
+- tool verbosity lines (`cargo`, `gh`, compilers: progress, timings, emoji)
+- content hashes, digests, object IDs
+- timestamps, durations, download speeds
+- absolute paths (home dir, temp dirs, machine names)
+
+Normalize these to stable placeholders (e.g. `[TIME]`, `[HASH]`, `[PATH]`)
+before the diff. Only normalized output is diffable — raw captures diff-fail
+on every run for reasons the docs never claimed to specify. Document the
+normalization rules in the docs pipeline itself, so a reader comparing their
+terminal to the docs knows what was masked.
+
+Rules:
+
+- The gate runs on every PR touching docs **or** code that changes
+  command output — output drift is a code-change bug as often as a docs bug.
+- The gate checks exit codes too, not just stdout: a command that starts
+  erroring is drift even when stdout looks plausible.
+- Keep the gate fast by scoping it to documented commands only; it is a
+  contract check, not a full test suite.
+
+## 2. Stamped Artifacts (generated per release, never hand-edited)
+
+Specodelic `lf4b.11` made `release.md`, `llms.txt`, and similar release-facing
+artifacts *stamped*: regenerated automatically at release time from the
+repo state, never hand-edited. Facts that a generator can compute (version,
+pack/module counts, release date, changelog digest) must not be maintained by
+hand — hand-maintained facts are exactly the ones that drift (see the
+pack-count drift fixes `lf4b.1`, `d8f97ce`, `fd2fbe0`).
+
+Stamped artifacts include:
+
+- `llms.txt` / `llm.txt` (AI-facing site indexes derived from the docs tree)
+- `release.md` / release notes derived from tags and changelog
+- README facts a generator owns: version numbers, counts, install shas
+
+Freshness check: add a lint step that **regenerates (or re-derives) each
+stamped artifact and fails on any diff**. The regeneration is cheap because
+the stamps are derived from data already in the repo; the diff is the point.
+A hand-edit survives exactly one CI run before it is flagged.
+
+Rules:
+
+- Stamp at release time from the single source the fact lives in — the stamp
+  step copies, it never re-types.
+- Treat a hand-edit to a stamped artifact as a bug: fix the generator (or the
+  underlying source), not the artifact.
+- If a fact is duplicated across stamped artifacts and hand-written pages, fix
+  it with a single source, not a sync script (the cross-surface drift audit is
+  a separate concern; the freshness check here covers machine-derived
+  artifacts only).
+- The freshness lint runs in CI on every push, not only at release — release
+  day is when you can least afford a surprise.
+
+## 3. Live-Site Smoke (CI curls the deployed URL)
+
+The ddl precedent: CI curls the deployed docs URL (GitHub Pages, Netlify,
+etc.) after deploy, so a 404'd book fails the pipeline immediately — not at
+the next human visit, which might be weeks away. Build checks validate the
+source; the smoke validates what readers actually receive.
+
+Smoke shape:
+
+1. After the deploy job succeeds, curl the URL a reader lands on: site root,
+   quickstart, at minimum the newest release page.
+2. Fail on non-2xx (and on obvious error bodies — some hosts return 200 for
+   soft-404 pages; check for the expected content marker).
+3. Run it in the same pipeline as the deploy, so a bad deploy fails before
+   anyone moves on.
+
+Rules:
+
+- Smoke the rendered URL, not the build artifact — the point is the thing a
+  reader's browser gets.
+- Include at least one deep page, not only the index: deploy misconfigs often
+  break path-based routing while the root still resolves.
+- Keep the assertions minimal (status + one content marker); this is a smoke,
+  not a rendering test suite.

package/content/distilled/documentation/references/implement-documentation/references/templates.md

@@ -6,6 +6,11 @@ One template per quadrant. Match the template to the quadrant identified in Step
 
 Goal: build competency through a guided, safe experience. Show, do not lecture.
 
+Quickstart rule (required for install/getting-started paths): every command shows
+its expected output and exit code, and the install path ends with a post-install
+verification block. If a step can fail realistically, show the failure and its
+recovery inline. See `references/worked-examples.md` for the full pattern.
+
 ```markdown
 # [Getting Started with X]
 
@@ -21,9 +26,33 @@ By the end you will have [concrete result]. No prior knowledge of [X] is assumed
 ## Step 1: [Specific Result]
 [Chunked, do-this-now instructions. Each step yields a visible result.]
 
+```bash
+$ [command]
+[expected output]
+```
+
+Exit code 0. If you instead see `[realistic error message]`, the fix is
+`[recovery command/step]`.
+
 ## Step 2: [Specific Result]
 [Chunked instructions.]
 
+```bash
+$ [command]
+[expected output]
+```
+
+## Verify Your Install
+Never end an install path on "it should work". Close with the tool's own
+self-check so the learner confirms success before moving on.
+
+```bash
+$ [tool] --version
+[expected version string]
+$ [tool] [minimal smoke command]
+[expected output]
+```
+
 ## Recap & Next Steps
 You built [X]. Next, try [lateral link 1] or [lateral link 2].
 ```

package/content/distilled/documentation/references/implement-documentation/references/visual-cross-repo.md

@@ -0,0 +1,131 @@
+# Visual Docs & Cross-Repo Ecosystems: Diagrams, Fleet Maps & Rendered-Output Smoke
+
+Methodology for documentation that covers pictures and ecosystems: diagrams
+that survive static-site deploys, responsibility maps for multi-repo fleets,
+and smoke checks that verify what readers' browsers actually render. Mined
+from the 2026-10 ddl and specodelic docs work; evidence in
+`.wai/resources/reflections/docs-skill-survey-2026-10.org` (row `iio`).
+Canonical theory: `content/research-documentation-frameworks.md`.
+
+The 2026-10 evidence: both failure classes are invisible to link checkers.
+Specodelic shipped mermaid graphs that silently rendered as raw text on the
+live site (`graph-views.html`) while passing every source-side check. Ddl
+solved fleet navigation with a single responsibility-map SVG whose blocks
+link into each project's own docs. The fixes are: prefer static pre-rendered
+SVG over runtime mermaid on static sites; give each fleet layer one
+responsibility map and each fleet-wide page exactly one home; after deploy,
+smoke rendered behavior — not just reachability.
+
+## 1. Diagrams: Prefer Static SVG Over Runtime Mermaid on Static-Site Books
+
+The specodelic precedent: mermaid diagrams embedded as code blocks render
+fine in the GitHub web UI (GitHub runs its own mermaid pipeline) but fail on
+a self-hosted static-site book unless the site generator loads the mermaid
+runtime — and that runtime is exactly the kind of third-party JS that breaks
+quietly (CSP blocks, plugin version drift, JS load failures on cache-warm
+pages). The `graph-views.html` incident shipped graphs as raw `graph TD`
+text to every reader while the build stayed green, because nothing in the
+pipeline executes a browser.
+
+Rule: on a static-site book, prefer **pre-rendered SVG committed to the repo**
+over runtime mermaid. SVG needs no JavaScript, renders in every browser and
+PDF pipeline, and fails loudly (missing file → broken image) rather than
+silently. If a diagram must stay in sync with code, close the loop with a
+build step rather than by hoping:
+
+- keep the mermaid (or dot, or similar) **source** in the repo next to the
+  page that embeds its rendered SVG;
+- regenerate the SVG in the docs build (or a stamp step, in the sense of
+  `docs-accuracy.md` §2) and fail the build when the committed SVG is stale;
+- never hand-edit the SVG — it is generated output, exactly like a stamped
+  artifact.
+
+When runtime rendering is unavoidable (e.g. diagrams are author-written
+content), smoke the rendered page (§3) so a dead mermaid runtime fails CI,
+not a reader.
+
+Rules:
+
+- Static SVG first; runtime mermaid only with a rendered-output smoke.
+- Every embedded diagram has a source in the repo and a build step that
+  regenerates it — a diagram no one can regenerate is a liability.
+- Color-coding and clickable regions (see §2) belong in the SVG itself, so
+  they survive without JS.
+- Diagram alt text names what the diagram claims, not what it depicts
+  ("Layers of the X ecosystem and which repo owns each", not "Diagram").
+
+## 2. Cross-Repo (Fleet) Docs: One Responsibility Map, One Home Per Page
+
+The ddl precedent (`cbfa300`): a multi-repo ecosystem is unreadable until
+someone draws it. Ddl built an ecosystem **responsibility map** — an SVG
+with color-coded layers, one block per project, each block a clickable link
+into that project's own docs. A reader landing on any repo's docs can answer
+"what is this part, what is it responsible for, and where is the rest?"
+without reading six READMEs.
+
+The pattern has three pieces:
+
+1. **A responsibility map per layer** (or one map with visible layers):
+   every block names a component, its one-line responsibility, and links to
+   the owning project's docs. Color-code by layer (runtime, tooling,
+   content, infra) so the map is scannable before it is readable. Place the
+   map in the hub repo's ecosystem page and mirror nothing — links, not
+   copies.
+2. **Per-repo setup pages follow one shared template.** Each project's docs
+   cover its own setup with the same section skeleton (install → configure →
+   verify), so a reader moving between repos never re-learns the page
+   shape. The template lives once, referenced by each repo's docs; per-repo
+   pages differ only in content, never in structure.
+3. **Fleet-wide pages live in exactly one repo.** Pages that describe the
+   ecosystem as a whole — the umbrella install page, the architecture
+   overview, the compatibility matrix — live in the hub repo. Duplicating a
+   fleet-wide page into each member repo guarantees staleness in all but
+   one copy; member repos link to the hub page instead. The responsibility
+   map's links are the navigation layer that makes "one home" viable.
+
+Rules:
+
+- One responsibility map, in the hub, linking out — never a fleet diagram
+  copied per repo.
+- If a fact spans repos, either it lives in a hub fleet-wide page or it
+  lives per-repo behind a stable link — never both.
+- Every member repo's docs start by locating themselves: one sentence plus
+  a link to the responsibility map.
+- A shared setup template is enforced by review, not copy-paste: when the
+  template changes, a drift audit (see `review-documentation`) checks the
+  member pages.
+
+## 3. Deployed-vs-Source Smoke: Verify Rendered Behavior, Not Just Links
+
+The reachability layer is `docs-accuracy.md` §3 (live-site smoke: curl the
+deployed URL, fail on non-2xx and soft-404s). This smoke builds **on** that
+one: reachability is necessary but not sufficient, because the two 2026-10
+incidents were fully reachable pages rendering wrong. Smoke what readers'
+browsers actually receive and execute.
+
+Smoke shape (runs after the reachability smoke, in the same pipeline):
+
+1. **JS executes without errors.** Fetch the deployed page the way a browser
+   would (a headless browser or a smoke script that asserts no console
+   errors) on at least one page that loads JavaScript. A site whose search
+   widget throws on load is broken in a way `curl -f` cannot see.
+2. **Diagrams and graphs render.** For pages embedding diagrams, assert the
+   rendered output, not the source: either the generated SVG is fetched and
+   non-empty, or the JS-rendered graph container holds rendered nodes (not
+   the raw mermaid text). This is the check the `graph-views.html` incident
+   would have failed.
+3. **The search index builds and serves.** Fetch the search index artifact
+   the client would fetch, assert non-empty and parseable, and query it for
+   a term from the newest page. A stale or empty index ships green through
+   every link checker.
+
+Rules:
+
+- Smoke the rendered URL, not the build artifact — the point is the thing a
+  reader's browser gets.
+- Assertions stay minimal per check (one marker per failure mode); this is a
+  smoke, not an end-to-end test suite.
+- Run it in the deploy pipeline, after reachability, so a bad deploy fails
+  before anyone moves on.
+- Any content class that needs a JS runtime to be correct (diagrams, search,
+  widgets) must appear in at least one rendered-behavior assertion.

package/content/distilled/documentation/references/implement-documentation/references/worked-examples.md

@@ -0,0 +1,83 @@
+# Worked Examples & Expected Output
+
+Methodology for tutorial, quickstart, and example-page content. Mined from the
+2026-10 docs work (specodelic packs: `data.lineage`, `numeric.predicates`,
+`empirical.registry`); evidence in `.wai/resources/reflections/docs-skill-survey-2026-10.org`.
+Canonical theory: `content/research-documentation-frameworks.md`.
+
+## 1. The Worked-Example Pattern (one thread, not N snippets)
+
+Examples were the #1 documentation gap in the 2026-10 survey. The failure mode
+was not "too few examples" but **disconnected examples**: N one-off snippets that
+each demonstrate a feature in isolation. Learners cannot see how features
+compose, and maintainers cannot tell which examples are stale.
+
+The fix is a single **evolving example thread**: one project that grows across
+every example page, each page building on the previous state.
+
+Thread shape (adapt per product):
+
+1. **Install** — prerequisites, install command, expected output.
+2. **First command** — smallest useful action, expected output, exit code.
+3. **Verification** — post-install verification block (see §2).
+4. **Realistic failure** — a failure a real first-time user hits, shown verbatim, with recovery.
+5. **Recovery + next feature** — fix it, then extend the same project with the next feature.
+
+Rules:
+
+- **One continuous project.** Page N+1 imports or extends the artifact built on page N. Name it explicitly ("in the `inventory` project from the previous example…").
+- **Each page stands alone in *task*, not in *state*.** A reader can jump in if they follow a one-line "start from" pointer, but never re-explains earlier steps.
+- **Realistic failure over toy failure.** Mine real user conversations or support logs for the failure to show; a fabricated typo error teaches nothing.
+- **Show the failure verbatim** — the actual error text, not a paraphrase — so learners can match it against their own terminal.
+
+## 2. The Quickstart Rule (expected output everywhere)
+
+Every command shown in a tutorial, quickstart, or how-to must show its expected
+output and exit code. Two components:
+
+**a. Expected output per command.**
+
+```bash
+$ spk explain data.lineage
+lineage: tracks how records flow between datasets
+```
+
+Exit code 0. If the command can fail realistically, the recovery goes inline
+right after (see the Tutorial template in `references/templates.md`).
+
+**b. Post-install verification block.** Every install path ends with the
+tool's own self-check — never "it should now work":
+
+```bash
+$ spk --version
+spk 0.4.1
+$ spk explain --list
+data.lineage  numeric.predicates  empirical.registry  ...
+```
+
+Rules:
+
+- Output shown must be **actual captured output**, not invented prose. If the docs are executable, the gate re-runs the commands and diffs against what you wrote — invented output fails.
+- Prefer the tool's self-check (`--version`, `explain`, `--list`) over existence checks (`which`, `ls`) — a binary can exist and still be broken.
+- Normalize volatile output (versions, timestamps, hashes) only if the docs pipeline documents the normalization.
+- Exit codes: show them when a command is known to fail in realistic conditions, so learners can grep their terminal against the doc.
+
+## 3. The Example Coverage Matrix (checklist, not tooling)
+
+After writing example pages, produce a coverage matrix mapping every
+user-facing feature (pack, command, module, endpoint) to at least one example
+page. Keep it a plain table or checklist in the docs or the tracker — do not
+build tooling for it; the audit is the point.
+
+| Feature | Example page | Thread position |
+| :--- | :--- | :--- |
+| [feature/command 1] | [path to example] | 1 (install) |
+| [feature/command 2] | [path to example] | 3 (first command) |
+| [feature/command 3] | *(uncovered)* | — |
+
+Rules:
+
+- **Every row needs ≥1 example page or an explicit "(uncovered)".** Uncovered rows become follow-up tickets immediately — do not let them linger as implicit debt.
+- **One row per user-facing feature**, from the user's vocabulary, not the internal module graph.
+- **Thread position** records where the feature appears in the evolving example, exposing which pages are doing double duty and which features are stranded outside the thread.
+- Re-run the matrix check after each release; new features enter with a row, not an apology.

package/content/distilled/documentation/references/review-documentation/SKILL.md

@@ -8,7 +8,7 @@ Perform a Rule of 5 review of the documentation using the Unified Frameworks for
 
 ## Procedure
 
-Perform 5 iterative passes. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged.
+Perform 5 iterative passes — 6 when the subject spans multiple surfaces (README, docs index, installation page): Pass 6 is the cross-surface consistency pass — 7 when the subject is user-facing documentation (for README, quickstart, and tool docs that is effectively always): Pass 7 is the cold-reader & positioning pass. Check for convergence after each pass starting with Pass 2: report new CRITICAL issues, total new issues, the change vs. the previous pass, and status (CONVERGED or CONTINUE). Converge when no new CRITICAL issues are found and the new-issue rate drops below 10% versus the previous pass. Stop early if converged.
 
 ### Pass 1: Diátaxis & Intent
 
@@ -24,12 +24,20 @@ Goal: can the reader scan the page in under 10 seconds and find the key answer?
 
 ### Pass 4: Accuracy, "Whole Game" & Fail-States
 
-Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? If the subject is a runnable tool/API: spot-check documented claims against the artifact itself (the method statement goes in the Final Report provenance block). For entry-point pages (README / landing / quickstart): is there a quickstart reaching a first verified success in minutes (time-to-first-success; see `../research-documentation/references/metrics.md`)? Issue prefix: [ACC-001].
+Goal: is the content technically sound and resilient? Checks: are code snippets verified? Does it show the complete result? Are common errors documented? In tutorials, is the Martini Glass pattern followed (guided context then open exploration)? If the subject is a runnable tool/API: spot-check documented claims against the artifact itself (the method statement goes in the Final Report provenance block). For entry-point pages (README / landing / quickstart): is there a quickstart reaching a first verified success in minutes (time-to-first-success; see `../research-documentation/references/metrics.md`)? For repos with executable docs: does CI re-run the documented commands and diff their captured output against the docs (accuracy gate), are stamped artifacts (`llms.txt`, `release.md`, README version facts) generated rather than hand-edited (freshness check), and does CI smoke the live deployed URL? Flag the absence of any of these as an [ACC-] finding — the methodology lives in `../implement-documentation/references/docs-accuracy.md`; cross-reference it, do not duplicate it here. Issue prefix: [ACC-001].
 
 ### Pass 5: Excellence & AI-Readiness
 
 Goal: is it production-ready and optimized for AI agents? Checks: is there a TL;DR for LLMs? Are headers semantically unique for RAG? Is the Answer First (Pyramid Principle) in the TL;DR and first paragraph? Use `references/ai-readiness-criteria.md` for the deep AI-readiness checks (`llms.txt`, RAG chunking, dual-audience, schema sync). Are claims marked by status — documented / interpreted / proposed / unknown — with unverified claims not stated as fact? Issue prefix: [EXCL-001].
 
+### Pass 6: Cross-Surface Consistency (multi-surface subjects only)
+
+Goal: do all user-facing surfaces tell one story with one set of facts? Applies when the subject spans multiple surfaces (README, docs index, installation page — any fact published in more than one place). Checks: run the drift audit — enumerate the facts repeated across surfaces (pack/module counts, command names, install steps, links, version claims) and verify every copy agrees; flag copies that should be generated/stamped instead of hand-written. Then check topic alignment: README, docs index, and installation page must tell one consistent story (same audience, same promise, same next step), not drift into different framings. The methodology lives in `references/drift-audit.md`; cross-reference it, do not duplicate it here. Issue prefix: [DRIFT-001].
+
+### Pass 7: Cold-Reader & Positioning
+
+Goal: would a confused first-time human succeed — not just an AI agent scoring structure (`references/ai-readiness-criteria.md` scores ingestion; it never asks the human question)? Applies when the subject is user-facing documentation. Checks: (1) cold-reader question mining — collect real user questions from support conversations, session logs, and issue titles, and verify each has a doc answer; unanswered ones become FAQ entries or tickets; (2) first-run funnel — can a cold reader reach first success in under 10 minutes (time-to-first-success; see `../research-documentation/references/metrics.md`)? (3) positioning — does every tool/format doc carry an explicit "when NOT to use this" section, and is there a decision guide where entry points overlap? The methodology lives in `references/cold-reader.md`; cross-reference it, do not duplicate it here. Issue prefix: [COLD-001].
+
 ## Final Report
 
 - Total Issues by Severity (Critical, High, Medium, Low).

package/content/distilled/documentation/references/review-documentation/references/cold-reader.md

@@ -0,0 +1,130 @@
+# Cold-Reader & Positioning Review (Pass 7)
+
+Methodology for Pass 7 of the review-documentation skill. Mined from the
+2026-10 evidence: two separate cold-read exercises drove the specodelic docs
+work — one reviewed real user conversations and turned the actual questions
+into FAQ, decision-guide, and glossary pages (commit `2e52854`, beads `7gh`);
+the other produced the "what the format assumes / when NOT to use it"
+positioning page (commit `427bf9a`). Evidence:
+`.wai/resources/reflections/docs-skill-survey-2026-10.org`.
+
+The gap Pass 7 closes: `ai-readiness-criteria.md` scores structure for LLM
+ingestion — chunking, unique headers, dual-audience — and never asks the
+human question: *would a confused first-time reader succeed?* Structure that
+scores perfectly for RAG can still strand a human at the front door.
+
+## 1. The Question Mine (enumerate real questions, don't invent them)
+
+Before reading the docs at all, collect the questions real users actually
+asked. The evidence is already sitting in three places:
+
+- **Support conversations** — chat logs, email threads, community channels.
+  Copy the user's question *verbatim*; paraphrase erases the exact
+  vocabulary gap that made the docs hard to find.
+- **Session logs / agent transcripts** — where a human or agent worked with
+  the tool, the points where they stopped to re-read, backtracked, or asked
+  a clarifying question are the confusion map.
+- **Issue titles and discussion threads** — a question filed as an issue is
+  a question the docs failed to answer in the most discoverable place.
+
+For each question, grep the docs for an answer: not the topic, the actual
+answer a cold reader could act on. Classify each question:
+
+- **Answered but undiscoverable** — the answer exists on a page the reader
+  would never reach from the entry point. Finding: add the missing link or
+  FAQ entry pointing at it.
+- **Answered but unclear** — the answer exists and is findable, yet the
+  user still asked. Finding: the page's wording failed; cite the exact
+  sentence that did not transfer.
+- **Unanswered** — no page answers it. Finding: becomes a FAQ entry or an
+  implementation ticket (`implement-documentation`), not a silent gap.
+
+Rules:
+
+- Mine at least the last 10 real user questions before judging any page —
+  a review built on imagined questions flags what authors fear, not what
+  readers hit.
+- Every unanswered question produces an artifact: a FAQ entry with the
+  user's own wording, or a filed ticket. A mined question that changes
+  nothing was decoration.
+- Record each finding with the question's source (conversation, log, issue
+  URL) — evidence-mined findings outrank reviewer intuition.
+
+## 2. The First-Run Funnel (time-to-first-success under 10 minutes)
+
+Walk the entry path exactly as a cold first-time reader would: land on the
+README or quickstart, follow the first action it names, and do not use any
+knowledge the page does not state. Time it end to end.
+
+The 2026-10 prompt was a user's own words: *"we have a presentation today,
+it should be clear and easy to onboard"* — onboarding time is a user-visible
+requirement, not an internal quality goal. The metric is
+time-to-first-success: first page view to first successful, verified use.
+
+Checks along the funnel walk:
+
+- **Zero-to-install**: does the first page state the prerequisites up front,
+  or does the reader discover them by failing? Each discovered-late
+  prerequisite is a restart.
+- **Decision count**: count the forks where the reader must choose without
+  guidance (package managers, install methods, "advanced vs. simple" paths).
+  More than a couple of unguided forks before first success is drift between
+  the docs and a cold reader's context.
+- **Verified success**: does the quickstart end with an output the reader
+  can check ("you should see…") rather than an unverified "it works"? An
+  unverifiable success is indistinguishable from a failure.
+- **Cross-reference, don't re-derive**: the metric definitions (TTFS,
+  support-ticket deflection, search analytics) live in
+  `../../research-documentation/references/metrics.md` — Pass 4 already uses
+  that file for entry-point pages. Read it for the measurement playbook;
+  this pass only runs the walk and reports where the clock exceeded 10
+  minutes or the reader stalled.
+
+Rules:
+
+- Time the funnel with a stopwatch or by counting steps, and report the
+  number — "it felt long" is not a finding; "install-to-first-success took
+  23 steps across 4 pages" is.
+- Walk the path as written, including the parts that are wrong; fixing the
+  docs in your head during the walk erases exactly the findings the pass
+  exists to produce.
+- If the funnel cannot be completed at all, that is the top-severity
+  finding, not a pass failure.
+
+## 3. Positioning: "When NOT to Use This" and the Decision Guide
+
+The `427bf9a` evidence: a format that explained itself well still needed a
+page stating what the format *assumes* and when NOT to use it — because
+readers who pick the wrong tool blame the tool, and no amount of positive
+documentation prevents the wrong first choice. Positioning is the part of
+the docs written for the reader who should walk away.
+
+Checks:
+
+- **"When NOT to use" section**: every tool or format doc needs an explicit
+  section naming the situations where this tool is the wrong choice, with
+  the reason and — where one exists — the alternative to use instead. A
+  good section is concrete ("do not use X when your data exceeds memory;
+  use Y instead"), not hedged ("X may not be suitable for all use cases" —
+  a hedge that answers nothing).
+- **Decision guide for overlapping entry points**: where two pages
+  (README vs. docs index, tutorial vs. how-to, tool A vs. tool B) could
+  both be a reader's first stop, there must be a stated rule for choosing
+  — a short comparison table or "start here if / use instead if" list at
+  the top of each overlapping page. Overlapping entry points without a
+  decision guide fork the reader at the moment they have no context to
+  choose.
+- **Assumptions stated**: the "what the format assumes" list belongs near
+  the top of the positioning page — readers invalidated by an unstated
+  assumption lose the most time.
+
+Rules:
+
+- Flag every tool/format doc missing the "when NOT to use" section as a
+  finding, not a suggestion — the evidence case shipped one after a real
+  user picked the format for a job it was never meant for.
+- Test each "when NOT to use" claim against the artifact where possible
+  (same stance as the Pass 4 spot-check); a wrong negative sends readers
+  away from a tool that would have worked.
+- The decision guide goes where the overlap is — at the entry points, not
+  buried on a comparison page nobody reaches before choosing.