Skip to content

docs: professional-voice pass and CI voice gate (S11) - #69

Merged
patterncatalyst merged 13 commits into
mainfrom
docs/professional-voice
Oct 12, 2026
Merged

patterncatalyst merged 13 commits into
mainfrom
docs/professional-voice

Conversation

@patterncatalyst

Copy link
Copy Markdown
Owner

Section S11 of the modernization plan: a professional-voice pass over every reader-facing page, README and diagram label, and a CI gate that keeps ban-tier phrasing out.

What changes

  • Rewrites across all chapters and appendices, the example pages, READMEs and 16 diagram labels (each changed in the SVG, both text and originalText of the .excalidraw, and any alt text or caption that repeats it). Code, commands, recorded output and link targets are byte-identical to main.
  • Ban tier 95 -> 0 and watch tier 239 -> 108 over the gated scope; every remaining watch hit is kept with a reason (literal minikube/OpenShift subjects, machine-subject "silently", result tables, idioms, identifiers, planned-stage "deliberate").
  • scripts/voice/ vendors the lgtm-professional-voice scanner byte-identical from lgtm-skills a335007 (PRs fix: embed diagrams in advisory DOCX #48 and feat(demo-01): add Quarkus implementation for cloud-native principles #49 fixed a scratch-file bug and added missing patterns), with a provenance README.
  • scripts/voice-scan.sh defines the gated scope and runs as a step in content.yml, so content-ok fails on any ban-tier phrase; CLAUDE.md documents it.
  • Plans: S10 marked done; S11 plan, per-file evidence table and ledgers.

Verification

  • Opus validation, one repair round, final recheck (merge verdict): code-identity and edit-locality scripts, full word-diff read for meaning drift, Jekyll builds of main and HEAD (same pages and links; ids changed only for six reworded headings with no inbound anchors), diagram render and label checks, gate injection proofs (page, README, SVG fail; inline code and fenced blocks pass), mawk/gawk parity, actionlint and shellcheck clean.

Adds scripts/voice/{scan.sh,patterns.tsv} byte-identical from lgtm-skills 50b4c08 with a provenance README, the scope wrapper scripts/voice-scan.sh, and the S11 plan. Marks S10 done (PR #68).
…MEs (S11)

ALL-CAPS lowercased in two headings and one README; README points at internal planning notes. Kept hits are literal minikube/OpenShift subjects, result tables, counts and identifiers.
16 ban-tier phrases rewritten (genuinely, deliberately, on purpose, for free, honest, load-bearing, earns its keep, the rest of this chapter); ALL-CAPS labels lowercased in 05-sourcing-vs-streaming; 05-checkpoint-recovery label and alt kept in step.
Ban-tier phrases rewritten in Appendices I, J and K (earn its place, genuinely, deliberately, candid, for free, arguably); diagram labels for 22-hop-cost, 22-east-west, 22-l7-layers and 24-monolith-unit kept in step with their alt text; heading 'What the .NET cloud-native story lacks' (no inbound anchors).
Ban-tier phrases rewritten across chapters 00-13; watch-tier hits fixed except one chapter opener. Headings 'How the book is ordered' and 'How correlation works' (no inbound anchors). Labels in 04-cqrs, 04-db-per-service, 08-four-planes, 12-claim-check and 13-antipatterns-grid kept in step with their alt text.
Ban-tier phrases rewritten in Appendices L-P; headings "When not to cache" and "what dotnet build produces" (no inbound anchors). Labels in 25-gray-failure, 25-istio-resilience and 27-ci-gate updated; the 27-ci-gate generator string kept in step.
Ban-tier phrases rewritten in Appendices A-H; heading "Three paradigms and their mental models" (no inbound anchors). Labels in 17-saga-state, 18-rest-errors, 19-strategic-ddd, 20-cynefin-coupling and 21-shutdown-sequence kept in step with their alt text.
content.yml runs scripts/voice-scan.sh (fails on any ban-tier phrase) and logs all-tier totals; CLAUDE.md documents the gate and its scope; plan records the per-batch ledgers.
Validator findings: grammar fix in Appendix K, 'rest of the appendix' and summary markers rewritten, 'deliberate' triaged (kept where it names a planned stage), claims restored to their original strength (caching payoff, random eviction, Minimal built-in DI), 'quietly fails' restored on the 04-db-per-service label, 27-ci-gate label 'in CI as they do locally', positional alt in chapter 04.
@patterncatalyst
patterncatalyst merged commit 2d8c2a8 into main Oct 12, 2026
16 checks passed
@patterncatalyst
patterncatalyst deleted the docs/professional-voice branch October 12, 2026 03:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant