feat: Search Before Building — builder ethos + skill integrations (v0.9.5.0) (#298)

* feat: ETHOS.md — gstack builder philosophy

Standalone document capturing the four principles: The Golden Age,
Boil the Lake, Search Before Building, and Build for Yourself.

Introduces the three-layer knowledge framework (tried-and-true,
new-and-popular, first-principles) and the Eureka Moment concept —
when first-principles reasoning reveals conventional wisdom is wrong.

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

* feat: Search Before Building preamble section + CLAUDE.md

Add generateSearchBeforeBuildingSection(ctx) to gen-skill-docs.ts.
Every workflow skill now gets a compact router section covering:
- Three layers of knowledge (tried-and-true, new-and-popular, first-principles)
- Eureka moment format and jq-based JSONL logging
- WebSearch fallback clause
- ETHOS.md reference via ctx.paths.skillRoot resolver

Also adds compact "Search before building" section to CLAUDE.md.

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

* feat: skill-specific Search Before Building integrations

8 template changes:
- /office-hours: Phase 2.75 Landscape Awareness (WebSearch + three-layer synthesis)
- /plan-eng-review: Step 0 search check with layer provenance annotations
- /investigate: external pattern search + search escalation on hypothesis failure
- /plan-ceo-review: Landscape Check before scope challenge
- /review: search-before-recommending for fix patterns
- /qa-only: WebSearch in allowed-tools
- /design-consultation: three-layer synthesis backport in Phase 2 Step 3
- /retro: eureka moment tracking from ~/.gstack/analytics/eureka.jsonl

All search steps include WebSearch fallback clause.

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

* feat: v0.9.5.0 — Builder Ethos (CHANGELOG + VERSION + TODOS)

ETHOS.md + Search Before Building across all workflow skills.
Deferred: first-time intro flow (blocked on blog post).

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

* fix: address Codex review — sanitize search, privacy gate, ETHOS.md sidecar

Three fixes from adversarial Codex review:
- /investigate: sanitize error messages before searching (strip hostnames,
  IPs, file paths, SQL, customer data). Skip search if unsanitizable.
- /office-hours: add privacy gate before landscape search. Use generalized
  category terms, never the user's specific product name or stealth idea.
- setup: link ETHOS.md into .agents/skills/gstack/ sidecar so workspace-
  local Codex sessions can find the builder philosophy.

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

* fix: sanitize Phase 2 external pattern search in /investigate

The Phase 2 external search also sent raw error messages to WebSearch.
Apply same sanitization rule as Phase 3 search escalation.

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

* docs: sync documentation with shipped changes

- ARCHITECTURE.md: preamble now handles 5 things (add Search Before Building)
- CLAUDE.md: add ETHOS.md to project structure tree
- README.md: add ETHOS.md to docs table

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

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

review/SKILL.md

@@ -14,6 +14,7 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
 ---
 <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
 <!-- Regenerate: bun run gen:skill-docs -->
@@ -132,6 +133,26 @@ AI-assisted coding makes the marginal cost of completeness near-zero. When you p
 - BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
 - BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")
 
+## Search Before Building
+
+Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — **search first.** Read `~/.claude/skills/gstack/ETHOS.md` for the full philosophy.
+
+**Three layers of knowledge:**
+- **Layer 1** (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
+- **Layer 2** (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
+- **Layer 3** (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.
+
+**Eureka moment:** When first-principles reasoning reveals conventional wisdom is wrong, name it:
+"EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
+
+Log eureka moments:
+```bash
+jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
+```
+Replace SKILL_NAME and ONE_LINE_SUMMARY. Runs inline — don't stop the workflow.
+
+**WebSearch fallback:** If WebSearch is unavailable, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."
+
 ## Contributor Mode
 
 If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
@@ -328,6 +349,13 @@ Apply the checklist against the diff in two passes:
 
 **Enum & Value Completeness requires reading code OUTSIDE the diff.** When the diff introduces a new enum value, status, tier, or type constant, use Grep to find all files that reference sibling values, then Read those files to check if the new value is handled. This is the one category where within-diff review is insufficient.
 
+**Search-before-recommending:** When recommending a fix pattern (especially for concurrency, caching, auth, or framework-specific behavior):
+- Verify the pattern is current best practice for the framework version in use
+- Check if a built-in solution exists in newer versions before recommending a workaround
+- Verify API signatures against current docs (APIs change between versions)
+
+Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge.
+
 Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.
 
 ---

review/SKILL.md.tmpl

@@ -14,6 +14,7 @@ allowed-tools:
   - Grep
   - Glob
   - AskUserQuestion
+  - WebSearch
 ---
 
 {{PREAMBLE}}
@@ -107,6 +108,13 @@ Apply the checklist against the diff in two passes:
 
 **Enum & Value Completeness requires reading code OUTSIDE the diff.** When the diff introduces a new enum value, status, tier, or type constant, use Grep to find all files that reference sibling values, then Read those files to check if the new value is handled. This is the one category where within-diff review is insufficient.
 
+**Search-before-recommending:** When recommending a fix pattern (especially for concurrency, caching, auth, or framework-specific behavior):
+- Verify the pattern is current best practice for the framework version in use
+- Check if a built-in solution exists in newer versions before recommending a workaround
+- Verify API signatures against current docs (APIs change between versions)
+
+Takes seconds, prevents recommending outdated patterns. If WebSearch is unavailable, note it and proceed with in-distribution knowledge.
+
 Follow the output format specified in the checklist. Respect the suppressions — do NOT flag items listed in the "DO NOT flag" section.
 
 ---