fix: resolve merge conflict with main, bump to v0.9.6.0

Main landed v0.9.5.0 (Builder Ethos) while this branch also used v0.9.5.0. Bumped to v0.9.6.0 and kept both CHANGELOG entries in chronological order. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-08-09 15:56:02 +02:00 · 2026-03-21 11:58:23 -07:00
parent c0964d2f89 f075cb757f
commit 0dd92d877b
50 changed files with 1370 additions and 12 deletions
@@ -17,6 +17,7 @@ allowed-tools:
  - Glob
  - Bash
  - AskUserQuestion
+  - WebSearch
 ---
 <!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
 <!-- Regenerate: bun run gen:skill-docs -->
@@ -135,6 +136,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.
@@ -332,6 +353,21 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head
 ```
 If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.

+**Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above):
+```bash
+HANDOFF=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null | head -1)
+[ -n "$HANDOFF" ] && echo "HANDOFF_FOUND: $HANDOFF" || echo "NO_HANDOFF"
+```
+If this block runs in a separate shell from the design doc check, recompute $SLUG and $BRANCH first using the same commands from that block.
+If a handoff note is found: read it. This contains system audit findings and discussion
+from a prior CEO review session that paused so the user could run `/office-hours`. Use it
+as additional context alongside the design doc. The handoff note helps you avoid re-asking
+questions the user already answered. Do NOT skip any steps — run the full review, but use
+the handoff note to inform your analysis and avoid redundant questions.
+
+Tell the user: "Found a handoff note from your prior CEO review session. I'll use that
+context to pick up where we left off."
+
 ## Prerequisite Skill Offer

 When the design doc check above prints "No design doc found," offer the prerequisite
@@ -351,6 +387,39 @@ Options:
 If they skip: "No worries — standard review. If you ever want sharper input, try
 /office-hours first next time." Then proceed normally. Do not re-offer later in the session.

+**Handoff note save (BENEFITS_FROM):** If the user chose A (run /office-hours first),
+save a handoff context note before they leave. Reuse $SLUG and $BRANCH from the
+design doc check block above (they use the same `remote-slug || basename` fallback
+that handles repos without an origin remote). Then run:
+```bash
+mkdir -p ~/.gstack/projects/$SLUG
+USER=$(whoami)
+DATETIME=$(date +%Y%m%d-%H%M%S)
+```
+Write to `~/.gstack/projects/$SLUG/$USER-$BRANCH-ceo-handoff-$DATETIME.md`:
+```markdown
+# CEO Review Handoff Note
+
+Generated by /plan-ceo-review on {date}
+Branch: {branch}
+Repo: {owner/repo}
+
+## Why I paused
+User chose to run /office-hours first (no design doc found).
+
+## System Audit Summary
+{Summarize what the system audit found — recent git history, diff scope,
+CLAUDE.md key points, TODOS.md relevant items, known pain points}
+
+## Discussion So Far
+{Empty — handoff happened before Step 0. Frontend/UI scope detection has not
+run yet — it will be assessed when the review resumes.}
+```
+
+Tell the user: "Context saved. Run /office-hours in another window. When you come back
+and invoke /plan-ceo-review, I'll pick up the context automatically — including the
+design doc /office-hours produces."
+
 **Mid-session detection:** During Step 0A (Premise Challenge), if the user can't
 articulate the problem, keeps changing the problem statement, answers with "I'm not
 sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
@@ -363,6 +432,15 @@ sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
 Options: A) Yes, run /office-hours first. B) No, keep going.
 If they keep going, proceed normally — no guilt, no re-asking.

+**Handoff note save (mid-session):** If the user chose A (run /office-hours first from
+mid-session detection), save a handoff context note with the same format above, but
+include any Step 0A progress in the "Discussion So Far" section — premises discussed,
+problem framing attempts, user answers so far. Use the same bash block to generate the
+file path.
+
+Tell the user: "Context saved with your discussion so far. Run /office-hours, then
+come back to /plan-ceo-review."
+
 When reading TODOS.md, specifically:
 * Note any TODOs this plan touches, blocks, or unlocks
 * Check if deferred work from prior reviews relates to this plan
@@ -385,6 +463,22 @@ Analyze the plan. If it involves ANY of: new UI screens/pages, changes to existi
 Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating.
 Report findings before proceeding to Step 0.

+### Landscape Check
+
+Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for:
+- "[product category] landscape {current year}"
+- "[key feature] alternatives"
+- "why [incumbent/conventional approach] [succeeds/fails]"
+
+If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."
+
+Run the three-layer synthesis:
+- **[Layer 1]** What's the tried-and-true approach in this space?
+- **[Layer 2]** What are the search results saying?
+- **[Layer 3]** First-principles reasoning — where might the conventional wisdom be wrong?
+
+Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a eureka moment, surface it during the Expansion opt-in ceremony as a differentiation opportunity. Log it (see preamble).
+
 ## Step 0: Nuclear Scope Challenge + Mode Selection

 ### 0A. Premise Challenge
@@ -950,6 +1044,16 @@ List every ASCII diagram in files this plan touches. Still accurate?
 ### Unresolved Decisions
 If any AskUserQuestion goes unanswered, note it here. Never silently default.

+## Handoff Note Cleanup
+
+After producing the Completion Summary, clean up any handoff notes for this branch —
+the review is complete and the context is no longer needed.
+
+```bash
+source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
+rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
+```
+
 ## Review Log

 After producing the Completion Summary above, persist the review result.
@@ -17,6 +17,7 @@ allowed-tools:
  - Glob
  - Bash
  - AskUserQuestion
+  - WebSearch
 ---

 {{PREAMBLE}}
@@ -111,8 +112,56 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head
 ```
 If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.

+**Handoff note check** (reuses $SLUG and $BRANCH from the design doc check above):
+```bash
+HANDOFF=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null | head -1)
+[ -n "$HANDOFF" ] && echo "HANDOFF_FOUND: $HANDOFF" || echo "NO_HANDOFF"
+```
+If this block runs in a separate shell from the design doc check, recompute $SLUG and $BRANCH first using the same commands from that block.
+If a handoff note is found: read it. This contains system audit findings and discussion
+from a prior CEO review session that paused so the user could run `/office-hours`. Use it
+as additional context alongside the design doc. The handoff note helps you avoid re-asking
+questions the user already answered. Do NOT skip any steps — run the full review, but use
+the handoff note to inform your analysis and avoid redundant questions.
+
+Tell the user: "Found a handoff note from your prior CEO review session. I'll use that
+context to pick up where we left off."
+
 {{BENEFITS_FROM}}

+**Handoff note save (BENEFITS_FROM):** If the user chose A (run /office-hours first),
+save a handoff context note before they leave. Reuse $SLUG and $BRANCH from the
+design doc check block above (they use the same `remote-slug || basename` fallback
+that handles repos without an origin remote). Then run:
+```bash
+mkdir -p ~/.gstack/projects/$SLUG
+USER=$(whoami)
+DATETIME=$(date +%Y%m%d-%H%M%S)
+```
+Write to `~/.gstack/projects/$SLUG/$USER-$BRANCH-ceo-handoff-$DATETIME.md`:
+```markdown
+# CEO Review Handoff Note
+
+Generated by /plan-ceo-review on {date}
+Branch: {branch}
+Repo: {owner/repo}
+
+## Why I paused
+User chose to run /office-hours first (no design doc found).
+
+## System Audit Summary
+{Summarize what the system audit found — recent git history, diff scope,
+CLAUDE.md key points, TODOS.md relevant items, known pain points}
+
+## Discussion So Far
+{Empty — handoff happened before Step 0. Frontend/UI scope detection has not
+run yet — it will be assessed when the review resumes.}
+```
+
+Tell the user: "Context saved. Run /office-hours in another window. When you come back
+and invoke /plan-ceo-review, I'll pick up the context automatically — including the
+design doc /office-hours produces."
+
 **Mid-session detection:** During Step 0A (Premise Challenge), if the user can't
 articulate the problem, keeps changing the problem statement, answers with "I'm not
 sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
@@ -125,6 +174,15 @@ sure," or is clearly exploring rather than reviewing — offer `/office-hours`:
 Options: A) Yes, run /office-hours first. B) No, keep going.
 If they keep going, proceed normally — no guilt, no re-asking.

+**Handoff note save (mid-session):** If the user chose A (run /office-hours first from
+mid-session detection), save a handoff context note with the same format above, but
+include any Step 0A progress in the "Discussion So Far" section — premises discussed,
+problem framing attempts, user answers so far. Use the same bash block to generate the
+file path.
+
+Tell the user: "Context saved with your discussion so far. Run /office-hours, then
+come back to /plan-ceo-review."
+
 When reading TODOS.md, specifically:
 * Note any TODOs this plan touches, blocks, or unlocks
 * Check if deferred work from prior reviews relates to this plan
@@ -147,6 +205,22 @@ Analyze the plan. If it involves ANY of: new UI screens/pages, changes to existi
 Identify 2-3 files or patterns in the existing codebase that are particularly well-designed. Note them as style references for the review. Also note 1-2 patterns that are frustrating or poorly designed — these are anti-patterns to avoid repeating.
 Report findings before proceeding to Step 0.

+### Landscape Check
+
+Read ETHOS.md for the Search Before Building framework (the preamble's Search Before Building section has the path). Before challenging scope, understand the landscape. WebSearch for:
+- "[product category] landscape {current year}"
+- "[key feature] alternatives"
+- "why [incumbent/conventional approach] [succeeds/fails]"
+
+If WebSearch is unavailable, skip this check and note: "Search unavailable — proceeding with in-distribution knowledge only."
+
+Run the three-layer synthesis:
+- **[Layer 1]** What's the tried-and-true approach in this space?
+- **[Layer 2]** What are the search results saying?
+- **[Layer 3]** First-principles reasoning — where might the conventional wisdom be wrong?
+
+Feed into the Premise Challenge (0A) and Dream State Mapping (0C). If you find a eureka moment, surface it during the Expansion opt-in ceremony as a differentiation opportunity. Log it (see preamble).
+
 ## Step 0: Nuclear Scope Challenge + Mode Selection

 ### 0A. Premise Challenge
@@ -652,6 +726,16 @@ List every ASCII diagram in files this plan touches. Still accurate?
 ### Unresolved Decisions
 If any AskUserQuestion goes unanswered, note it here. Never silently default.

+## Handoff Note Cleanup
+
+After producing the Completion Summary, clean up any handoff notes for this branch —
+the review is complete and the context is no longer needed.
+
+```bash
+source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
+rm -f ~/.gstack/projects/$SLUG/*-$BRANCH-ceo-handoff-*.md 2>/dev/null || true
+```
+
 ## Review Log

 After producing the Completion Summary above, persist the review result.