|
| 1 | +# Docs Voice Pass — Beyond Getting-Started Implementation Plan |
| 2 | + |
| 3 | +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. |
| 4 | +
|
| 5 | +**Goal:** Apply Brian's technical-register voice pass to the remaining docs prose (guides/concepts/reference/components/api `.mdx` across all 7 libs, ~78 pages), prose-only, shipped as one per-lib PR each (7 PRs). |
| 6 | + |
| 7 | +**Architecture:** Per-lib PRs. Within each PR, implementer work is grouped by section so no agent edits too much at once; each group is gated by a prose-only diff guard → voice review → render-200. Reference/api/component pages get YAGNI-hard treatment (prose-only; tables/signatures/props untouched; near-empty diffs are correct). Reuses the rubric + guardrails proven on the getting-started passes (#583, #585). |
| 8 | + |
| 9 | +**Tech Stack:** MDX docs (Next.js App Router), `git diff` heading/fence guard as the accuracy gate, independent voice-review subagent, dev-server/curl for render checks. `docs/gtm/voice.md` = the register. |
| 10 | + |
| 11 | +**Reference spec:** `docs/superpowers/specs/2026-06-07-docs-voice-beyond-gs-design.md` |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## Voice rubric (apply surgically — don't churn in-voice prose) |
| 16 | +- Title-as-lede (keep existing H1); contractions; one thought per line; short paragraphs. |
| 17 | +- Guides: "Let's" lead-ins where a step intro reads flatly; a brief next-steps close where natural (reuse existing links; verify routes in `docs-config.ts`). |
| 18 | +- Flag opinions ("For me", "In my experience") + a tradeoff — only where the page already recommends something. Don't invent opinions. |
| 19 | +- Trim corporate stiffness/filler; concrete verbs. |
| 20 | +- NO emojis, anecdotes, hype, or lecturing. |
| 21 | + |
| 22 | +## Hard guardrails (NON-NEGOTIABLE) |
| 23 | +1. Never change anything inside a fenced ``` code block, nor any inline `code`, command, API name, type, version, or link/href. |
| 24 | +2. Never change heading text (`#`/`##`/`###`) — rehype-slug anchors + TOC depend on it. H1 titles stay exactly. |
| 25 | +3. Preserve all MDX components + props, incl. every `<Step title="...">`. Use only supported `Callout` types (`tip`/`info`/`warning`/`danger` — never `note`). |
| 26 | +4. YAGNI — leave already-in-voice passages alone. |
| 27 | +5. NO technical corrections folded in. Flag any real error for a separate follow-up. |
| 28 | + |
| 29 | +## Reference/api/component pages — YAGNI HARD |
| 30 | +For `reference/*`, `api/*`, `chat/components/*`: voice ONLY the page intro + explanatory prose between code/tables. NEVER touch tables/rows, signatures, code, inline API tokens, selectors/props, `<Step title>`. A near-empty or empty diff on these pages is a SUCCESS. |
| 31 | + |
| 32 | +## Shared per-section gate (run after each section's edits, before committing) |
| 33 | + |
| 34 | +```bash |
| 35 | +cd /Users/blove/repos/angular-agent-framework |
| 36 | +# $FILES = the edited .mdx paths for this section |
| 37 | +for p in $FILES; do |
| 38 | + echo "== $p ==" |
| 39 | + echo "headings changed:"; git --no-pager diff "$p" | grep -E "^[+-]\s*#{1,6} " || echo " (none — good)" |
| 40 | + echo "fences changed:"; git --no-pager diff "$p" | grep -E "^[+-]\s*\`\`\`" || echo " (none — good)" |
| 41 | + echo "Step titles changed:"; git --no-pager diff "$p" | grep -E "^[+-].*<Step " || echo " (none — good)" |
| 42 | + echo "note callout:"; git --no-pager diff "$p" | grep -E "^\+.*type=\"note\"" && echo " BAD" || echo " (none — good)" |
| 43 | +done |
| 44 | +``` |
| 45 | +Every line must print "(none — good)". Then eyeball the full diff: every `+`/`-` pair is prose. Revert any code/heading/link/`<Step>`/component change. |
| 46 | + |
| 47 | +Then dispatch an independent **voice-review subagent** for the section: confirm each page reads in Brian's technical register (contractions, one-thought-per-line; guides have "Let's" + next-steps where natural), no emojis/hype/anecdotes/lecturing, and the guardrails held. Loop until clean. |
| 48 | + |
| 49 | +--- |
| 50 | + |
| 51 | +## Per-PR procedure (applies to every lib Task below) |
| 52 | + |
| 53 | +Each lib Task follows the SAME shape: |
| 54 | + |
| 55 | +- [ ] **Step A — branch:** `git fetch origin main`; create `claude/voice-<lib>-docs` off `origin/main` (stale-source guard). |
| 56 | +- [ ] **Step B — read + edit by section:** dispatch implementer subagent(s), one per section group (the Task lists the groups). The implementer reads each page + `docs/gtm/voice.md`, applies the rubric surgically, and respects the guardrails + YAGNI-hard rule for reference/api/component pages. |
| 57 | +- [ ] **Step C — section gate:** run the shared per-section gate (heading/fence/`<Step>`/note guard) on the edited files; fix violations. |
| 58 | +- [ ] **Step D — voice review:** independent voice-review subagent per section group; loop until clean. |
| 59 | +- [ ] **Step E — commit per section** (`docs(<lib>): voice pass on <section>`), grouped for clean history. |
| 60 | +- [ ] **Step F — render check:** serve website on :3000; each edited route returns 200; `diff` headings of each edited page vs `origin/main` shows identical heading lines. |
| 61 | +- [ ] **Step G — PR + auto-merge:** push, open PR (`docs(<lib>): voice pass on guides/concepts/reference`), enable squash auto-merge; monitor (`gh pr update-branch` if BEHIND). |
| 62 | + |
| 63 | +--- |
| 64 | + |
| 65 | +## Task 1 — langgraph voice PR (18 pages) |
| 66 | + |
| 67 | +**Branch:** `claude/voice-langgraph-docs`. |
| 68 | +**Section groups (implementer per group):** |
| 69 | +- **guides (9):** `lifecycle, streaming, subgraphs, time-travel, persistence, deployment, memory, interrupts, testing` — `apps/website/content/docs/langgraph/guides/*.mdx`. Tutorial/how-to register. |
| 70 | +- **concepts (5):** `agent-contract, langgraph-basics, angular-signals, state-management, agent-architecture` — prose-dense; highest voice value; apply rubric to explanatory prose, leave code/diagrams. |
| 71 | +- **api (4):** `inject-agent, provide-agent, fetch-stream-transport, mock-stream-transport` — YAGNI HARD (intros only; leave signatures/tables). |
| 72 | + |
| 73 | +Run Steps A–G. Render routes: all 18 under `/docs/langgraph/{guides,concepts,api}/<slug>`. |
| 74 | + |
| 75 | +## Task 2 — chat voice PR (30 pages) |
| 76 | + |
| 77 | +**Branch:** `claude/voice-chat-docs`. |
| 78 | +**Section groups:** |
| 79 | +- **guides (9):** `layout-modes, theming, markdown, generative-ui, custom-catalogs, streaming, configuration, writing-an-adapter, lifecycle`. |
| 80 | +- **concepts (2):** `primitives-vs-compositions, message-model`. |
| 81 | +- **components A (7):** `chat, chat-popup, chat-sidebar, chat-message-list, chat-trace, chat-input, chat-reasoning` — YAGNI HARD (intro prose only; never the input/output tables, selectors, slots). |
| 82 | +- **components B (7):** `chat-interrupt-panel, chat-tool-calls, chat-tool-call-template, chat-tool-call-card, chat-subagent-card, chat-debug, chat-select` — YAGNI HARD. |
| 83 | +- **api (5):** `provide-chat, chat-config, mock-agent, content-classifier, parse-tree-store` — YAGNI HARD. |
| 84 | +- (Skip `getting-started/changelog.mdx`; the `chat/a2ui/*` pages voice only if narrative — YAGNI HARD.) |
| 85 | + |
| 86 | +Run Steps A–G. |
| 87 | + |
| 88 | +## Task 3 — render voice PR (11 pages) |
| 89 | + |
| 90 | +**Branch:** `claude/voice-render-docs`. |
| 91 | +**Section groups:** |
| 92 | +- **guides (5):** `registry, state-store, specs, events, lifecycle`. |
| 93 | +- **concepts (1):** `json-render-vs-a2ui`. |
| 94 | +- **api (5):** `render-spec-component, define-angular-registry, views, signal-state-store, provide-render` — YAGNI HARD. |
| 95 | + |
| 96 | +Run Steps A–G. |
| 97 | + |
| 98 | +## Task 4 — ag-ui voice PR (7 pages) |
| 99 | + |
| 100 | +**Branch:** `claude/voice-ag-ui-docs`. |
| 101 | +**Section groups:** |
| 102 | +- **guides (5):** `fake-agent, citations, interrupts, testing, troubleshooting`. |
| 103 | +- **concepts (1):** `architecture`. |
| 104 | +- **reference (1):** `event-mapping` — YAGNI HARD (intro prose only; never the event→signal table). |
| 105 | + |
| 106 | +Run Steps A–G. |
| 107 | + |
| 108 | +## Task 5 — a2ui voice PR (5 pages) |
| 109 | + |
| 110 | +**Branch:** `claude/voice-a2ui-docs`. |
| 111 | +**Section groups:** |
| 112 | +- **guides (3):** `message-protocol, data-model, adapters-and-validation`. |
| 113 | +- **reference (2):** `schema, parser-resolver-guards` — YAGNI HARD (intro prose only; never the type/schema blocks or tables). |
| 114 | + |
| 115 | +Run Steps A–G. |
| 116 | + |
| 117 | +## Task 6 — telemetry voice PR (4 pages) |
| 118 | + |
| 119 | +**Branch:** `claude/voice-telemetry-docs`. |
| 120 | +**Section groups:** |
| 121 | +- **guides (3):** `browser, node, privacy-and-opt-out`. |
| 122 | +- **reference (1):** `events` — YAGNI HARD. |
| 123 | + |
| 124 | +Run Steps A–G. |
| 125 | + |
| 126 | +## Task 7 — licensing voice PR (3 pages) |
| 127 | + |
| 128 | +**Branch:** `claude/voice-licensing-docs`. |
| 129 | +**Section groups:** |
| 130 | +- **guides (2):** `setup, ci-and-offline`. |
| 131 | +- **reference (1):** `api` — YAGNI HARD. |
| 132 | + |
| 133 | +Run Steps A–G. |
| 134 | + |
| 135 | +## Task 8 — Land planning artifacts + close out |
| 136 | + |
| 137 | +- [ ] **Step 1:** After all 7 lib PRs are merged, land the spec + plan to main via a small doc-only PR from `claude/docs-voice-beyond-gs` (rebased on up-to-date main), enable auto-merge. |
| 138 | +- [ ] **Step 2:** Confirm all PRs merged (monitor; `gh pr update-branch` any BEHIND; serialize); sync local main; delete merged branches. |
| 139 | +- [ ] **Step 3:** Spawn a follow-up for any real technical error a voice-review surfaced (do NOT fold corrections into voice PRs). |
| 140 | + |
| 141 | +--- |
| 142 | + |
| 143 | +## Manual verification (per lib PR, before merge) |
| 144 | +- [ ] Heading/fence/`<Step>`/note guard prints "(none — good)" for every edited file; headings byte-identical to `origin/main`. |
| 145 | +- [ ] Voice review confirms the technical register; reference/api/component pages show prose-only (often near-empty) diffs. |
| 146 | +- [ ] All edited routes render HTTP 200. |
| 147 | + |
| 148 | +## Self-Review (completed during planning) |
| 149 | + |
| 150 | +- **Spec coverage:** all 78 pages across 7 libs covered by per-lib Tasks 1–7 with section groups matching the spec's page counts (langgraph 18, chat 30, render 11, ag-ui 7, a2ui 5, telemetry 4, licensing 3) ✓; rubric + guardrails carried verbatim from the proven passes ✓; YAGNI-hard reference/api/component handling stated in the plan header + each relevant group ✓; per-section gate (heading/fence/`<Step>`/note) + voice review + render-200 ✓; per-lib PRs with stale-source guard + auto-merge + monitor ✓; planning-artifact landing + follow-up spawning (Task 8) ✓; order (langgraph→chat→render→ag-ui→a2ui→telemetry→licensing) matches the spec. |
| 151 | +- **Placeholder scan:** No TBD/TODO. Voice edits are author-judgment (a voice pass) — bounded by the rubric, the off-limits guardrails, the automated heading/fence/`<Step>`/note guard, and the independent voice review; commands have expected output ("(none — good)"). |
| 152 | +- **Consistency:** the shared per-section gate + per-PR procedure (Steps A–G) are defined once and referenced by every lib Task; section group page lists match the spec; the supported-Callout-type guard (`note` 500'd a page in the langgraph review) is in the gate; `claude/docs-voice-beyond-gs` holds the spec/plan, with per-lib `claude/voice-<lib>-docs` branches off `origin/main`. |
0 commit comments