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

[ctwoodwa]

Summary

• Prose review pass (Stage 5) on Chapter 8: The Product & Economic Lens
• Trimmed from 4,697 to 3,801 words (target 3,500 ±10%; range 3,150–3,850)
• Advanced ICM marker from icm/prose-review to icm/voice-check

What was cut

• Redundant restatement sentences throughout (e.g., the "Commending the strategic framing" bridge sentence that restated the paragraph above it)
• The 400-word regional go-to-market deep-dive paragraph (GCC/India/Japan/Sub-Saharan Africa/Latin America/CIS detail); the checklist section already covers the principle — the expanded detail belongs in an appendix, not inline
• The 250-word regulatory compliance list in Moat 3; condensed to representative examples with pointer to Appendix F
• Hedging phrases and filler ("it is worth noting", "in a specific way that")
• The "What Changed Between Rounds" section was tightened by ~30% — scaffolding sentences removed, causal logic preserved

Test plan

• Word count within ±10% of 3,500 (result: 3,801)
• ICM marker updated to icm/voice-check
• Two-act structure preserved (R1 blocks → revision arc → R2 conditions)
• No <word>#<digit> patterns in commit body
• commit type is docs

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Rewrote and clarified four foundational chapters with tighter, more focused prose: simplified explanations of common SaaS failure modes, sharpened local-first architecture principles and ideals, expanded technical stack layer descriptions with enhanced implementation details, and strengthened business model and economic strategy sections for clearer strategic guidance and improved narrative flow.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

Four chapters of the inverted-stack book are substantially rewritten for clarity and argument flow. The SaaS problem statement and failure modes are streamlined, local-first ideals and full-node architecture are redefined, the inverted stack core framing and five layers are reauthored with technical detail, failure modes and canonical deployment shapes are restructured, and the commercial model with business-development checklist is expanded.

Changes

Book Narrative and Architecture Rewrite

Layer / File(s)	Summary
SaaS problem statement and failure modes in the field vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Tightened and streamlined the Pune hospital scenario opening and rewrote the "Seven Ways SaaS Breaks" section with condensed outage narratives, cloud concentration impacts, vendor shutdown, offline-connectivity, data access limits, pricing changes, silent drift, and third-party veto subsections.
Structural dependence and user acceptance of SaaS vol-1/part-1-thesis-and-pain/ch01-when-saas-fights-reality.md	Rewrote closing argument sections: tightened ransomware/resilience anecdotes, compressed regulatory/market-leverage discussion, and reframed why users accept SaaS dependence while preserving the local-first/CRDT causal explanation.
Local-first seven ideals and existing architecture attempts vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Reworked definitions of the seven ideals with sharpened wording, adjusted examples in "the long now," revised the taxonomy of Obsidian, Notion, Linear, Actual Budget, and Automerge, and condensed the "what each gets right" transition to emphasize missing authority and full-node composition.
Full-node architecture and enterprise deployment model vol-1/part-1-thesis-and-pain/ch02-local-first-serious-stack.md	Defined full-node as locally running all layers (presentation, logic, sync daemon, storage, security) with cloud confined to ciphertext-only relay/backup. Rewrote "What This Book Adds" to emphasize enterprise procurement, legal/compliance constraints, stable microkernel with plugins, per-record CAP positioning, CRDT GC policy, key hierarchy/rotation, schema migration strategy, and managed-relay self-hostability.
Inverted stack core framing and five-layer architecture vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Rewrote the inversion of priority (local-node authoritative, relay optional for sync/discovery), clarified relay's role across NAT and offline fallback behavior, and reauthored all five layers: presentation as local-store rendering with Blazor Hybrid/Harborline and accessibility semantics; application logic operating offline against CRDT with CP-class lease-coordination exception; sync daemon as OS-managed process with discovery/gossip/delta-streaming/lease-coordination/write-buffering; storage with encryption/key-derivation/CRDT-document-store/event-log/projections; relay as ciphertext-only routing with explicit trust levels.
Failure modes, resolved failures, and canonical deployment zones vol-1/part-1-thesis-and-pain/ch03-inverted-stack-one-diagram.md	Restructured "How This Changes Failure Modes" to contrast resolved failures with introduced failures (endpoint compromise, schema migration complexity, CRDT GC debt), redefined Zone A and Zone C with deployment/sync/tenancy details, and rewrote developer habits stressing local-first writes, network-independent correctness, and explicit failure-mode signaling.
Commercial model, customer development, and business-model checklist vol-1/part-2-council-reads-the-paper/ch08-product-economic-lens.md	Expanded Round 1 and Round 2 critique by Kelsey: clarified missing first-customer archetype and OSS-to-paid conversion trigger, added Round 2 acquisition-channel detail, scale economics, dual-license/CLA timing, named year-two failure modes and mitigations, and added consolidated business-model checklist with explicit commercialization sequencing tied to community and procurement calendars.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Harborline-Software/the-inverted-stack#145: Both PRs modify Chapter 3 markdown—this PR reauthors the layer and canonical-shape framing while the related PR applies the relay terminology rebrand (Anchor/Bridge-to-Zone A/Zone C).

Suggested labels

icm/draft

Poem

🐰 Pages flip, prose flows true,
Five layers laid, and failures few,
From SaaS woes to full-node grace,
The inverted stack finds its place!
Business models dance and align—
A rabbit's blessing on each line. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description follows the template structure with Summary and Type sections completed, but the Checklist section is missing entirely—the required confirmation items are not present.	Add the Checklist section from the template with explicit checkboxes confirming conformance to repo voice/conventions, spoiler prevention, and any applicable updates to canon sheets.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically summarizes the main change: a prose review pass (Stage 5) advancing Chapter 8 to voice-check stage, using the repo's established commit convention format.
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-ch08

---

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