docs(vol-1): ch04 prose review — advance to voice-check

[ctwoodwa]

Summary

• Prose review pass (Stage 5): active voice, no scaffolding, no hedging, no restatement
• Trimmed from 5,051 words to 3,770 words (target: 3,150–3,850)
• Advanced ICM marker from icm/prose-review to icm/voice-check

What was cut

• Full regulatory-atlas paragraph in Filter 3 (deferred to Appendix F reference)
• Restatement sentences throughout all five filter sections
• Hedging phrases ("could potentially", "may", "might" as default register)
• The standalone "Practical Shortcut" section header and framing paragraph; three questions folded directly into "What the Analysis Produces"
• Repeated parenthetical disclaimers in Zone B/C descriptions
• Academic scaffolding remnants

Test plan

• Word count: 3,770 (within 3,150–3,850 target)
• ICM marker updated to icm/voice-check
• All five filters, three zones, compliance table, and worked example preserved
• Mermaid diagram unchanged
• No <!-- CLAIM: source? --> markers introduced

Summary by CodeRabbit

• Documentation
  • Enhanced architectural decision guidance with clarified explanations of consistency requirements, data ownership considerations, connectivity criteria, business model alignment, and team capability assessments.
  • Updated decision framework tables and worked examples to provide more structured guidance for architectural migrations and implementation choices.

[coderabbitai]

📝 Walkthrough

Walkthrough

This revision tightens an architectural decision chapter by reframing the central "one question," sharpening five sequential decision filters (consistency, ownership, connectivity, business model, team capability), and rewriting the Three Outcome Zones section with updated descriptions, compliance table, worked example, and conclusion.

Changes

Architectural Decision Framework Revision

Layer / File(s)	Summary
Core question and filter introduction vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md	The "one question" framing is rewritten to clarify how primary user-owned vs. aggregated state value maps to local-node vs. centralized infrastructure choice, and the introduction to the ordered filter model is refreshed. A minor review directive comment is updated.
Five decision filters (1–5) vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md	Filter 1 is rephrased to distinguish atomic cross-user transactional needs from eventual-consistency-tolerant domains and clarify financial-data scope. Filters 2–3 redefine natural ownership by meaningful creation/meaningful loss and revise environment-to-model mapping with updated regulatory discussion. Filters 4–5 add business-model mismatch framing and refine timeline/capability narrative with skill breakdown examples.
Three Outcome Zones, compliance posture, and worked example vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md	Zone A/B/C descriptions are rewritten; the per-zone compliance posture table wording is updated; the construction-industry migration worked example is rewritten; and the concluding "analysis produces" framing is refreshed in more concise terms.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

A bunny hops through prose so tight,
Where filters guide the choice aright,
From question clear to zones well-drawn,
The architectural path shines on. ✨
— A happy rabbit, revising with care

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: a prose review pass that advances the chapter's stage marker from prose-review to voice-check, which is the primary objective of this changeset.
Description check	✅ Passed	The description covers all required template sections: Summary (what the PR does), Type (Editorial—prose/voice), and a detailed Checklist with specific verification items aligned to the PR's stated objectives.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch prose/review-ch04

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md (2)

231-233: ⚡ Quick win

Open the section with purpose before mechanism.

“Three questions produce…” starts with mechanics. Recast the opener to lead with why this section exists (decision velocity / risk reduction), then present the three-question method.

As per coding guidelines, “Write book chapters using purpose-first structure: every section opens with why it exists, not what it does” and “Lead with the punchline: decision before reasoning, constraint before implementation detail.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md` around lines
231 - 233, Rewrite the "## What the Analysis Produces" section to open with the
purpose and benefit (e.g., decision velocity, risk reduction, when to use this
method) before introducing the method itself; replace the current opener "Three
questions produce a fast first-pass answer for most cases." with a purpose-first
lead that states why the reader should care (the decision outcome), then follow
with the three-question technique as the mechanism and a brief transition
sentence tying the method to that purpose.

---

14-14: ⚡ Quick win

Normalize architecture terminology to one canonical name.

The chapter alternates between “local-node architecture,” “local node,” “local-first,” and “local-first node.” Pick one canonical term for the core concept and use it consistently throughout this chapter.

As per coding guidelines, “Use consistent naming for concepts throughout the book. Do not cycle through synonyms; name once and use that name everywhere.”

Also applies to: 24-24, 41-43, 64-64, 176-176, 188-188

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md` at line 14,
Choose a single canonical term for the concept (e.g., "local-first") and use it
consistently across this chapter: replace all occurrences of "local-node
architecture", "local node", "local-first node", and any other synonyms in the
sentence shown and at the other flagged locations (24-24, 41-43, 64-64, 176-176,
188-188) with the chosen term, and adjust surrounding grammar if needed so the
sentence reads naturally with the unified name.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md`:
- Line 247: Update the implementation-bridge paragraph to explicitly state the
architecture is engine-agnostic by naming the current engine (YDotNet used in
Sunfish) and the aspirational target (Loro) and explaining they are
interchangeable via the ICrdtEngine abstraction; keep the existing references to
Zone A and Zone C accelerators and Sunfish, but append a concise sentence such
as “Sunfish’s current implementations use YDotNet, but the architecture is
engine-agnostic and supports replacement with Loro through the ICrdtEngine
interface,” ensuring ICrdtEngine is mentioned exactly to signal the abstraction
layer.
- Around line 66-67: The paragraph beginning "When a regulatory custodian must
hold the authoritative copy..." in ch04-choosing-your-architecture.md must
include inline IEEE numeric citations ([1], [2], ...) in first-appearance order
for each legal/factual claim and a matching bibliographic entry assembled per
vol-1/appendices/appendix-e-citation-style.md; update the sentence(s)
referencing HIPAA, 45 CFR §164.312, FINRA Rule 4511, and SEC Rule 17a-4 to add
the appropriate bracketed citations and include section-level sourcing (e.g.,
v13 §X, v5 §Y, R1/R2) as required by the guidelines, then add the new references
to the references list in the appendix format; apply the same fixes to the other
flagged blocks (lines 87-92 and 200-209) ensuring citation numbering follows
first appearance throughout the file.

---

Nitpick comments:
In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md`:
- Around line 231-233: Rewrite the "## What the Analysis Produces" section to
open with the purpose and benefit (e.g., decision velocity, risk reduction, when
to use this method) before introducing the method itself; replace the current
opener "Three questions produce a fast first-pass answer for most cases." with a
purpose-first lead that states why the reader should care (the decision
outcome), then follow with the three-question technique as the mechanism and a
brief transition sentence tying the method to that purpose.
- Line 14: Choose a single canonical term for the concept (e.g., "local-first")
and use it consistently across this chapter: replace all occurrences of
"local-node architecture", "local node", "local-first node", and any other
synonyms in the sentence shown and at the other flagged locations (24-24, 41-43,
64-64, 176-176, 188-188) with the chosen term, and adjust surrounding grammar if
needed so the sentence reads naturally with the unified name.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7f58338b-c162-40b3-a062-e394da352aba

📥 Commits

Reviewing files that changed from the base of the PR and between 5eca771 and a15514e.

📒 Files selected for processing (1)

• vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | 🏗️ Heavy lift

Add IEEE citations for legal and factual claims.

These regulatory and jurisdictional assertions need inline IEEE numeric citations ([1], [2], …) in first-appearance order, with references assembled per the appendix style. Right now the claims are unsourced in-body.

As per coding guidelines, “vol-1/**/*.md: Use IEEE numeric citation style (in-text: [1], [2], [3] in order of first appearance) and follow all rules in vol-1/appendices/appendix-e-citation-style.md exactly” and “Source sections inline by citing v13 §X, v5 §Y, R1/R2 where applicable.”

Also applies to: 87-92, 200-209

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md` around lines
66 - 67, The paragraph beginning "When a regulatory custodian must hold the
authoritative copy..." in ch04-choosing-your-architecture.md must include inline
IEEE numeric citations ([1], [2], ...) in first-appearance order for each
legal/factual claim and a matching bibliographic entry assembled per
vol-1/appendices/appendix-e-citation-style.md; update the sentence(s)
referencing HIPAA, 45 CFR §164.312, FINRA Rule 4511, and SEC Rule 17a-4 to add
the appropriate bracketed citations and include section-level sourcing (e.g.,
v13 §X, v5 §Y, R1/R2) as required by the guidelines, then add the new references
to the references list in the appendix format; apply the same fixes to the other
flagged blocks (lines 87-92 and 200-209) ensuring citation numbering follows
first appearance throughout the file.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add engine-agnostic framing with YDotNet, Loro, and ICrdtEngine.

This implementation bridge paragraph references Sunfish but omits the required engine-agnostic statement connecting current (YDotNet) and target (Loro) through ICrdtEngine.

As per coding guidelines, “Mention both YDotNet (current Sunfish implementation) and Loro (aspirational target) where relevant, emphasizing that the architecture is engine-agnostic via ICrdtEngine.”

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@vol-1/part-1-thesis-and-pain/ch04-choosing-your-architecture.md` at line 247,
Update the implementation-bridge paragraph to explicitly state the architecture
is engine-agnostic by naming the current engine (YDotNet used in Sunfish) and
the aspirational target (Loro) and explaining they are interchangeable via the
ICrdtEngine abstraction; keep the existing references to Zone A and Zone C
accelerators and Sunfish, but append a concise sentence such as “Sunfish’s
current implementations use YDotNet, but the architecture is engine-agnostic and
supports replacement with Loro through the ICrdtEngine interface,” ensuring
ICrdtEngine is mentioned exactly to signal the abstraction layer.