refactor(ethos): rename Boil the Lake principle to Boil the Ocean

Reframes the completeness principle so the ocean (the complete thing) is the
goal and lakes are the boilable units you ship on the way there. "Don't boil
the ocean" was right when engineering time was the bottleneck; AI killed that
bottleneck, so the ocean is now the destination.

Resolves an existing split: the scope_appetite psychographic, archetypes, and
the completeness intro flow already used "boil the ocean" as the
complete-implementation pole while the named principle still said "lake".

Sources only: ETHOS.md philosophy, CLAUDE.md, README.md, the preamble
resolvers, and the plan/autoplan/document-generate templates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -137,7 +137,7 @@ gstack/
 ├── setup            # One-time setup: build binary + symlink skills
 ├── SKILL.md         # Generated from SKILL.md.tmpl (don't edit directly)
 ├── SKILL.md.tmpl    # Template: edit this, run gen:skill-docs
-├── ETHOS.md         # Builder philosophy (Boil the Lake, Search Before Building)
+├── ETHOS.md         # Builder philosophy (Boil the Ocean, Search Before Building)
 └── package.json     # Build scripts for browse
 ```
 
@@ -776,8 +776,10 @@ When estimating or discussing effort, always show both human-team and CC+gstack
 | Research / exploration | 1 day | 3 hours | ~3x |
 
 Completeness is cheap. Don't recommend shortcuts when the complete implementation
-is a "lake" (achievable) not an "ocean" (multi-quarter migration). See the
-Completeness Principle in the skill preamble for the full philosophy.
+is achievable. Boil the ocean — the complete thing is the goal; only genuinely
+unrelated multi-quarter migrations are separate scope, never an excuse for a
+shortcut. See the Completeness Principle in the skill preamble for the full
+philosophy.
 
 ## Search before building
 

ETHOS.md

@@ -31,16 +31,21 @@ The last 10% of completeness that teams used to skip? It costs seconds now.
 
 ---
 
-## 1. Boil the Lake
+## 1. Boil the Ocean
 
-AI-assisted coding makes the marginal cost of completeness near-zero. When
-the complete implementation costs minutes more than the shortcut — do the
+"Don't boil the ocean" was the right advice when engineering time was the
+bottleneck. That era is over. AI-assisted coding makes the marginal cost of
+completeness near-zero, so the old caution has quietly turned into an excuse.
+When the complete implementation costs minutes more than the shortcut — do the
 complete thing. Every time.
 
-**Lake vs. ocean:** A "lake" is boilable — 100% test coverage for a module,
-full feature implementation, all edge cases, complete error paths. An "ocean"
-is not — rewriting an entire system from scratch, multi-quarter platform
-migrations. Boil lakes. Flag oceans as out of scope.
+**Ocean, lakes first:** The ocean is the destination — 100% test coverage for a
+module, full feature implementation, all edge cases, complete error paths. You
+get there one lake at a time: each lake is a boilable unit, not the ceiling.
+"That's boiling the ocean" is no longer a reason to ship a shortcut — boiling
+the ocean is the goal. The only thing still out of scope is genuinely unrelated
+work: a multi-quarter platform migration that has nothing to do with the task at
+hand. Flag that as separate scope. Boil everything else.
 
 **Completeness is cheap.** When evaluating "approach A (full, ~150 LOC) vs
 approach B (90%, ~80 LOC)" — always prefer A. The 70-line delta costs
@@ -144,7 +149,7 @@ think it's better, state what context you might be missing, and ask. Never act.
 
 ## How They Work Together
 
-Boil the Lake says: **do the complete thing.**
+Boil the Ocean says: **do the complete thing.**
 Search Before Building says: **know what exists before you decide what to build.**
 
 Together: search first, then build the complete version of the right thing.

README.md

@@ -429,7 +429,7 @@ Other references: [docs/gbrain-sync.md](docs/gbrain-sync.md) (sync-specific guid
 | Doc | What it covers |
 |-----|---------------|
 | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
-| [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Lake, Search Before Building, three layers of knowledge |
+| [Builder Ethos](ETHOS.md) | Builder philosophy: Boil the Ocean, Search Before Building, three layers of knowledge |
 | [Using GBrain with GStack](USING_GBRAIN_WITH_GSTACK.md) | Every path, flag, bin helper, and troubleshooting step for `/setup-gbrain` |
 | [GBrain Sync](docs/gbrain-sync.md) | Cross-machine memory setup, privacy modes, troubleshooting |
 | [Architecture](ARCHITECTURE.md) | Design decisions and system internals |

autoplan/SKILL.md.tmpl

@@ -216,7 +216,7 @@ Read each file using the Read tool:
 (they are already handled by /autoplan):**
 - Preamble (run first)
 - AskUserQuestion Format
-- Completeness Principle — Boil the Lake
+- Completeness Principle — Boil the Ocean
 - Search Before Building
 - Completion Status Protocol
 - Telemetry (run last)

document-generate/SKILL.md.tmpl

@@ -457,4 +457,4 @@ Documentation generated:
 - **Voice: friendly, concrete, user-forward.** Write like you're explaining to a smart person
   who hasn't seen the code. Never corporate, never academic.
 - **Completeness over minimalism.** AI makes comprehensive documentation cheap. Don't write
-  "minimal viable docs" — write complete docs. Boil the lake.
+  "minimal viable docs" — write complete docs. Boil the ocean.

plan-ceo-review/SKILL.md.tmpl

@@ -64,7 +64,7 @@ But your posture depends on what the user needs:
 * SELECTIVE EXPANSION: You are a rigorous reviewer who also has taste. Hold the current scope as your baseline — make it bulletproof. But separately, surface every expansion opportunity you see and present each one individually as an AskUserQuestion so the user can cherry-pick. Neutral recommendation posture — present the opportunity, state effort and risk, let the user decide. Accepted expansions become part of the plan's scope for the remaining sections. Rejected ones go to "NOT in scope."
 * HOLD SCOPE: You are a rigorous reviewer. The plan's scope is accepted. Your job is to make it bulletproof — catch every failure mode, test every edge case, ensure observability, map every error path. Do not silently reduce OR expand.
 * SCOPE REDUCTION: You are a surgeon. Find the minimum viable version that achieves the core outcome. Cut everything else. Be ruthless.
-* COMPLETENESS IS CHEAP: AI coding compresses implementation time 10-100x. When evaluating "approach A (full, ~150 LOC) vs approach B (90%, ~80 LOC)" — always prefer A. The 70-line delta costs seconds with CC. "Ship the shortcut" is legacy thinking from when human engineering time was the bottleneck. Boil the lake.
+* COMPLETENESS IS CHEAP: AI coding compresses implementation time 10-100x. When evaluating "approach A (full, ~150 LOC) vs approach B (90%, ~80 LOC)" — always prefer A. The 70-line delta costs seconds with CC. "Ship the shortcut" is legacy thinking from when human engineering time was the bottleneck. Boil the ocean.
 Critical rule: In ALL modes, the user is 100% in control. Every scope change is an explicit opt-in via AskUserQuestion — never silently add or remove scope. Once the user selects a mode, COMMIT to it. Do not silently drift toward a different mode. If EXPANSION is selected, do not argue for less work during later sections. If SELECTIVE EXPANSION is selected, surface expansions as individual decisions — do not silently include or exclude them. If REDUCTION is selected, do not sneak scope back in. Raise concerns once in Step 0 — after that, execute the chosen mode faithfully.
 Do NOT make any code changes. Do NOT start implementation. Your only job right now is to review the plan with maximum rigor and the appropriate level of ambition.
 

plan-eng-review/SKILL.md.tmpl

@@ -112,7 +112,7 @@ Before reviewing anything, answer these questions:
    If the plan rolls a custom solution where a built-in exists, flag it as a scope reduction opportunity. Annotate recommendations with **[Layer 1]**, **[Layer 2]**, **[Layer 3]**, or **[EUREKA]** (see preamble's Search Before Building section). If you find a eureka moment — a reason the standard approach is wrong for this case — present it as an architectural insight.
 5. **TODOS cross-reference:** Read `TODOS.md` if it exists. Are any deferred items blocking this plan? Can any deferred items be bundled into this PR without expanding scope? Does this plan create new work that should be captured as a TODO?
 
-5. **Completeness check:** Is the plan doing the complete version or a shortcut? With AI-assisted coding, the cost of completeness (100% test coverage, full edge case handling, complete error paths) is 10-100x cheaper than with a human team. If the plan proposes a shortcut that saves human-hours but only saves minutes with CC+gstack, recommend the complete version. Boil the lake.
+5. **Completeness check:** Is the plan doing the complete version or a shortcut? With AI-assisted coding, the cost of completeness (100% test coverage, full edge case handling, complete error paths) is 10-100x cheaper than with a human team. If the plan proposes a shortcut that saves human-hours but only saves minutes with CC+gstack, recommend the complete version. Boil the ocean.
 
 6. **Distribution check:** If the plan introduces a new artifact type (CLI binary, library package, container image, mobile app), does it include the build/publish pipeline? Code without distribution is code nobody can use. Check:
    - Is there a CI/CD workflow for building and publishing the artifact?

scripts/resolvers/composition.ts

@@ -23,7 +23,7 @@ export function generateInvokeSkill(ctx: TemplateContext, args?: string[]): stri
   const DEFAULT_SKIPS = [
     'Preamble (run first)',
     'AskUserQuestion Format',
-    'Completeness Principle — Boil the Lake',
+    'Completeness Principle — Boil the Ocean',
     'Search Before Building',
     'Contributor Mode',
     'Completion Status Protocol',

scripts/resolvers/preamble/generate-completeness-section.ts

@@ -2,9 +2,9 @@ import type { TemplateContext } from '../types';
 
 export function generateCompletenessSection(ctx?: TemplateContext): string {
   if (ctx?.explainLevel === 'terse') return '';
-  return `## Completeness Principle — Boil the Lake
+  return `## Completeness Principle — Boil the Ocean
 
-AI makes completeness cheap. Recommend complete lakes (tests, edge cases, error paths); flag oceans (rewrites, multi-quarter migrations).
+AI makes completeness cheap, so the complete thing is the goal. Recommend full coverage (tests, edge cases, error paths) — boil the ocean one lake at a time. The only thing out of scope is genuinely unrelated work (rewrites, multi-quarter migrations); flag that as separate scope, never as an excuse for a shortcut.
 
 When options differ in coverage, include \`Completeness: X/10\` (10 = all edge cases, 7 = happy path, 3 = shortcut). When options differ in kind, write: \`Note: options differ in kind, not coverage — no completeness score.\` Do not fabricate scores.`;
 }

scripts/resolvers/preamble/generate-lake-intro.ts

@@ -1,7 +1,7 @@
 
 
 export function generateLakeIntro(): string {
-  return `If \`LAKE_INTRO\` is \`no\`: say "gstack follows the **Boil the Lake** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open:
+  return `If \`LAKE_INTRO\` is \`no\`: say "gstack follows the **Boil the Ocean** principle — do the complete thing when AI makes marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" Offer to open:
 
 \`\`\`bash
 open https://garryslist.org/posts/boil-the-ocean