From f74f274253455d8e3aedf7e890f3e1abef53b9c4 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sun, 7 Jun 2026 19:50:20 -0700 Subject: [PATCH] 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) --- CLAUDE.md | 8 ++++--- ETHOS.md | 21 ++++++++++++------- README.md | 2 +- autoplan/SKILL.md.tmpl | 2 +- document-generate/SKILL.md.tmpl | 2 +- plan-ceo-review/SKILL.md.tmpl | 2 +- plan-eng-review/SKILL.md.tmpl | 2 +- scripts/resolvers/composition.ts | 2 +- .../preamble/generate-completeness-section.ts | 4 ++-- .../resolvers/preamble/generate-lake-intro.ts | 2 +- 10 files changed, 27 insertions(+), 20 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dc62ad561..93c6c2c2d 100644 --- a/CLAUDE.md +++ b/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 diff --git a/ETHOS.md b/ETHOS.md index a04cd9d1c..3dbd5e570 100644 --- a/ETHOS.md +++ b/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. diff --git a/README.md b/README.md index a0d9c40e3..c8b20b308 100644 --- a/README.md +++ b/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 | diff --git a/autoplan/SKILL.md.tmpl b/autoplan/SKILL.md.tmpl index 888cddabb..2e67eb9e1 100644 --- a/autoplan/SKILL.md.tmpl +++ b/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) diff --git a/document-generate/SKILL.md.tmpl b/document-generate/SKILL.md.tmpl index e4ac067ad..d3ef0cbc3 100644 --- a/document-generate/SKILL.md.tmpl +++ b/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. diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index fd95b5d13..c43cfe641 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/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. diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 73953afe4..89fc5eee5 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/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? diff --git a/scripts/resolvers/composition.ts b/scripts/resolvers/composition.ts index bf9812f44..b8d3483d9 100644 --- a/scripts/resolvers/composition.ts +++ b/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', diff --git a/scripts/resolvers/preamble/generate-completeness-section.ts b/scripts/resolvers/preamble/generate-completeness-section.ts index ba9a874bd..3a8665812 100644 --- a/scripts/resolvers/preamble/generate-completeness-section.ts +++ b/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.`; } diff --git a/scripts/resolvers/preamble/generate-lake-intro.ts b/scripts/resolvers/preamble/generate-lake-intro.ts index 3de5fbf15..b6cca9e13 100644 --- a/scripts/resolvers/preamble/generate-lake-intro.ts +++ b/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