From 6cf424fb4907a3e2dea3ebd68308af5dbe94c858 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:09:32 -0500 Subject: [PATCH 01/12] =?UTF-8?q?feat:=20add=20escalation=20protocol=20to?= =?UTF-8?q?=20preamble=20=E2=80=94=20all=20skills=20get=20DONE/BLOCKED/NEE?= =?UTF-8?q?DS=5FCONTEXT?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every skill now reports completion status (DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT) and has escalation rules: 3 failed attempts → STOP, security uncertainty → STOP, scope exceeds verification → STOP. "It is always OK to stop and say 'this is too hard for me.'" Co-Authored-By: Claude Opus 4.6 (1M context) --- SKILL.md | 25 +++++++++++++++++++++++++ browse/SKILL.md | 25 +++++++++++++++++++++++++ qa-only/SKILL.md | 25 +++++++++++++++++++++++++ qa/SKILL.md | 25 +++++++++++++++++++++++++ retro/SKILL.md | 25 +++++++++++++++++++++++++ scripts/gen-skill-docs.ts | 29 ++++++++++++++++++++++++++++- setup-browser-cookies/SKILL.md | 25 +++++++++++++++++++++++++ 7 files changed, 178 insertions(+), 1 deletion(-) diff --git a/SKILL.md b/SKILL.md index b362e824..67bb6a41 100644 --- a/SKILL.md +++ b/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # gstack browse: QA Testing & Dogfooding Persistent headless Chromium. First call auto-starts (~3s), then ~100-200ms per command. diff --git a/browse/SKILL.md b/browse/SKILL.md index 28e976df..22e464bb 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # browse: QA Testing & Dogfooding Persistent headless Chromium. First call auto-starts (~3s), then ~100ms per command. diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 438b7826..fb4d89e8 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -72,6 +72,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # /qa-only: Report-Only QA Testing You are a QA engineer. Test web applications like a real user — click everything, fill every form, check every state. Produce a structured report with evidence. **NEVER fix anything.** diff --git a/qa/SKILL.md b/qa/SKILL.md index c11f8a66..7a982353 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -77,6 +77,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # /qa: Test → Fix → Verify You are a QA engineer AND a bug-fix engineer. Test web applications like a real user — click everything, fill every form, check every state. When you find bugs, fix them in source code with atomic commits, then re-verify. Produce a structured report with before/after evidence. diff --git a/retro/SKILL.md b/retro/SKILL.md index 28280c94..1ff5cb18 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -72,6 +72,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # /retro — Weekly Engineering Retrospective Generates a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics. Team-aware: identifies the user running the command, then analyzes every contributor with per-person praise and growth opportunities. Designed for a senior IC/CTO-level builder using Claude Code as a force multiplier. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index bafed642..45ca4fbb 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -150,7 +150,32 @@ Hey gstack team — ran into this while using /{skill-name}: Then run: \`mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-logs/{slug}.md\` -Slug: lowercase, hyphens, max 60 chars (e.g. \`browse-snapshot-ref-gap\`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"`; +Slug: lowercase, hyphens, max 60 chars (e.g. \`browse-snapshot-ref-gap\`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +\`\`\` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +\`\`\``; } function generateBrowseSetup(): string { @@ -508,6 +533,8 @@ function findTemplates(): string[] { path.join(ROOT, 'plan-ceo-review', 'SKILL.md.tmpl'), path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'), path.join(ROOT, 'retro', 'SKILL.md.tmpl'), + path.join(ROOT, 'brainstorm', 'SKILL.md.tmpl'), + path.join(ROOT, 'debug', 'SKILL.md.tmpl'), path.join(ROOT, 'gstack-upgrade', 'SKILL.md.tmpl'), ]; for (const p of candidates) { diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index 06230249..3d9cfcd1 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -70,6 +70,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Setup Browser Cookies Import logged-in sessions from your real Chromium browser into the headless browse session. From e3d36b645f921714a51f495f1308340606b2bf16 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:09:48 -0500 Subject: [PATCH 02/12] =?UTF-8?q?feat:=20add=20verification=20gate=20to=20?= =?UTF-8?q?/ship=20(Step=206.5)=20=E2=80=94=20no=20push=20without=20fresh?= =?UTF-8?q?=20evidence?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before pushing, re-verify tests if code changed during review fixes. Rationalization prevention: "Should work now" → RUN IT. "I'm confident" → Confidence is not evidence. Co-Authored-By: Claude Opus 4.6 (1M context) --- ship/SKILL.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++ ship/SKILL.md.tmpl | 23 ++++++++++++++++++++++ 2 files changed, 71 insertions(+) diff --git a/ship/SKILL.md b/ship/SKILL.md index e023816d..14d3aa1b 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -72,6 +72,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Ship: Fully Automated Ship Workflow You are running the `/ship` workflow. This is a **non-interactive, fully automated** workflow. Do NOT ask for confirmation at any step. The user said `/ship` which means DO IT. Run straight through and output the PR URL at the end. @@ -407,6 +432,28 @@ EOF --- +## Step 6.5: Verification Gate + +**IRON LAW: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.** + +Before pushing, re-verify if code changed during Steps 4-6: + +1. **Test verification:** If ANY code changed after Step 3's test run (fixes from review findings, CHANGELOG edits don't count), re-run the test suite. Paste fresh output. Stale output from Step 3 is NOT acceptable. + +2. **Build verification:** If the project has a build step, run it. Paste output. + +3. **Rationalization prevention:** + - "Should work now" → RUN IT. + - "I'm confident" → Confidence is not evidence. + - "I already tested earlier" → Code changed since then. Test again. + - "It's a trivial change" → Trivial changes break production. + +**If tests fail here:** STOP. Do not push. Fix the issue and return to Step 3. + +Claiming work is complete without verification is dishonesty, not efficiency. + +--- + ## Step 7: Push Push to the remote with upstream tracking: @@ -467,4 +514,5 @@ EOF - **Split commits for bisectability** — each commit = one logical change. - **TODOS.md completion detection must be conservative.** Only mark items as completed when the diff clearly shows the work is done. - **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence (inline diff, code references, re-rank suggestion). Never post vague replies. +- **Never push without fresh verification evidence.** If code changed after Step 3 tests, re-run before pushing. - **The goal is: user says `/ship`, next thing they see is the review + PR URL.** diff --git a/ship/SKILL.md.tmpl b/ship/SKILL.md.tmpl index 06ff5a07..9c1b1649 100644 --- a/ship/SKILL.md.tmpl +++ b/ship/SKILL.md.tmpl @@ -350,6 +350,28 @@ EOF --- +## Step 6.5: Verification Gate + +**IRON LAW: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE.** + +Before pushing, re-verify if code changed during Steps 4-6: + +1. **Test verification:** If ANY code changed after Step 3's test run (fixes from review findings, CHANGELOG edits don't count), re-run the test suite. Paste fresh output. Stale output from Step 3 is NOT acceptable. + +2. **Build verification:** If the project has a build step, run it. Paste output. + +3. **Rationalization prevention:** + - "Should work now" → RUN IT. + - "I'm confident" → Confidence is not evidence. + - "I already tested earlier" → Code changed since then. Test again. + - "It's a trivial change" → Trivial changes break production. + +**If tests fail here:** STOP. Do not push. Fix the issue and return to Step 3. + +Claiming work is complete without verification is dishonesty, not efficiency. + +--- + ## Step 7: Push Push to the remote with upstream tracking: @@ -410,4 +432,5 @@ EOF - **Split commits for bisectability** — each commit = one logical change. - **TODOS.md completion detection must be conservative.** Only mark items as completed when the diff clearly shows the work is done. - **Use Greptile reply templates from greptile-triage.md.** Every reply includes evidence (inline diff, code references, re-rank suggestion). Never post vague replies. +- **Never push without fresh verification evidence.** If code changed after Step 3 tests, re-run before pushing. - **The goal is: user says `/ship`, next thing they see is the review + PR URL.** From b4c33261c725a23f75d75a94ab672874e13e0e36 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:10:00 -0500 Subject: [PATCH 03/12] feat: add scope drift detection + verification of claims to /review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 1.5: Before reviewing code quality, check if the diff matches stated intent. Flags scope creep and missing requirements (INFORMATIONAL). Step 5 addition: Every review claim must cite evidence — "this pattern is safe" needs a line reference, "tests cover this" needs a test name. Co-Authored-By: Claude Opus 4.6 (1M context) --- review/SKILL.md | 69 ++++++++++++++++++++++++++++++++++++++++++++ review/SKILL.md.tmpl | 44 ++++++++++++++++++++++++++++ 2 files changed, 113 insertions(+) diff --git a/review/SKILL.md b/review/SKILL.md index 32c597a3..c05e68aa 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Pre-Landing PR Review You are running the `/review` workflow. Analyze the current branch's diff against main for structural issues that tests don't catch. @@ -87,6 +112,40 @@ You are running the `/review` workflow. Analyze the current branch's diff agains --- +## Step 1.5: Scope Drift Detection + +Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?** + +1. Read `TODOS.md` (if it exists). Read PR description (`gh pr view --json body --jq .body 2>/dev/null || true`). + Read commit messages (`git log origin/main..HEAD --oneline`). + **If no PR exists:** rely on commit messages and TODOS.md for stated intent — this is the common case since /review runs before /ship creates the PR. +2. Identify the **stated intent** — what was this branch supposed to accomplish? +3. Run `git diff origin/main --stat` and compare the files changed against the stated intent. +4. Evaluate with skepticism: + + **SCOPE CREEP detection:** + - Files changed that are unrelated to the stated intent + - New features or refactors not mentioned in the plan + - "While I was in there..." changes that expand blast radius + + **MISSING REQUIREMENTS detection:** + - Requirements from TODOS.md/PR description not addressed in the diff + - Test coverage gaps for stated requirements + - Partial implementations (started but not finished) + +5. Output (before the main review begins): + ``` + Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING] + Intent: <1-line summary of what was requested> + Delivered: <1-line summary of what the diff actually does> + [If drift: list each out-of-scope change] + [If missing: list each unaddressed requirement] + ``` + +6. This is **INFORMATIONAL** — does not block the review. Proceed to Step 2. + +--- + ## Step 2: Read the checklist Read `.claude/skills/review/checklist.md`. @@ -139,6 +198,16 @@ Follow the output format specified in the checklist. Respect the suppressions - If only non-critical issues found: output findings. No further action needed. - If no issues found: output `Pre-Landing Review: No issues found.` +### Verification of claims + +Before producing the final review output: +- If you claim "this pattern is safe" → cite the specific line proving safety +- If you claim "this is handled elsewhere" → read and cite the handling code +- If you claim "tests cover this" → name the test file and method +- Never say "likely handled" or "probably tested" — verify or flag as unknown + +**Rationalization prevention:** "This looks fine" is not a finding. Either cite evidence it IS fine, or flag it as unverified. + ### Greptile comment resolution After outputting your own findings, if Greptile comments were classified in Step 2.5: diff --git a/review/SKILL.md.tmpl b/review/SKILL.md.tmpl index 124a5393..14afe6f7 100644 --- a/review/SKILL.md.tmpl +++ b/review/SKILL.md.tmpl @@ -30,6 +30,40 @@ You are running the `/review` workflow. Analyze the current branch's diff agains --- +## Step 1.5: Scope Drift Detection + +Before reviewing code quality, check: **did they build what was requested — nothing more, nothing less?** + +1. Read `TODOS.md` (if it exists). Read PR description (`gh pr view --json body --jq .body 2>/dev/null || true`). + Read commit messages (`git log origin/main..HEAD --oneline`). + **If no PR exists:** rely on commit messages and TODOS.md for stated intent — this is the common case since /review runs before /ship creates the PR. +2. Identify the **stated intent** — what was this branch supposed to accomplish? +3. Run `git diff origin/main --stat` and compare the files changed against the stated intent. +4. Evaluate with skepticism: + + **SCOPE CREEP detection:** + - Files changed that are unrelated to the stated intent + - New features or refactors not mentioned in the plan + - "While I was in there..." changes that expand blast radius + + **MISSING REQUIREMENTS detection:** + - Requirements from TODOS.md/PR description not addressed in the diff + - Test coverage gaps for stated requirements + - Partial implementations (started but not finished) + +5. Output (before the main review begins): + ``` + Scope Check: [CLEAN / DRIFT DETECTED / REQUIREMENTS MISSING] + Intent: <1-line summary of what was requested> + Delivered: <1-line summary of what the diff actually does> + [If drift: list each out-of-scope change] + [If missing: list each unaddressed requirement] + ``` + +6. This is **INFORMATIONAL** — does not block the review. Proceed to Step 2. + +--- + ## Step 2: Read the checklist Read `.claude/skills/review/checklist.md`. @@ -82,6 +116,16 @@ Follow the output format specified in the checklist. Respect the suppressions - If only non-critical issues found: output findings. No further action needed. - If no issues found: output `Pre-Landing Review: No issues found.` +### Verification of claims + +Before producing the final review output: +- If you claim "this pattern is safe" → cite the specific line proving safety +- If you claim "this is handled elsewhere" → read and cite the handling code +- If you claim "tests cover this" → name the test file and method +- Never say "likely handled" or "probably tested" — verify or flag as unknown + +**Rationalization prevention:** "This looks fine" is not a finding. Either cite evidence it IS fine, or flag it as unverified. + ### Greptile comment resolution After outputting your own findings, if Greptile comments were classified in Step 2.5: From e716363916c4d6a91479d92de1d6a8c6498a3855 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:10:12 -0500 Subject: [PATCH 04/12] feat: mandatory implementation alternatives + design doc lookup in /plan-ceo-review Step 0C-bis: Every plan must consider 2-3 approaches (minimal viable vs ideal architecture) before mode selection. RECOMMENDATION required. Pre-Review System Audit now checks ~/.gstack/projects/ for /brainstorm design docs (branch-filtered with fallback). Co-Authored-By: Claude Opus 4.6 (1M context) --- plan-ceo-review/SKILL.md | 71 ++++++++++++++++++++++++++++++++++- plan-ceo-review/SKILL.md.tmpl | 46 ++++++++++++++++++++++- 2 files changed, 115 insertions(+), 2 deletions(-) diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index c82753a2..c3c9428e 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Mega Plan Review Mode ## Philosophy @@ -122,7 +147,19 @@ git stash list # Any stashed work grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files ``` -Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically: +Then read CLAUDE.md, TODOS.md, and any existing architecture docs. + +**Design doc check:** +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists (from `/brainstorm`), 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. + +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 * Flag dependencies: does this plan enable or depend on deferred items? @@ -159,6 +196,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m [describe] ---> [describe delta] ---> [describe target] ``` +### 0C-bis. Implementation Alternatives (MANDATORY) + +Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences]. + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial plans. +- One approach must be the "minimal viable" (fewest files, smallest diff). +- One approach must be the "ideal architecture" (best long-term trajectory). +- If only one approach exists, explain concretely why alternatives were eliminated. +- Do NOT proceed to mode selection (0F) without user approval of the chosen approach. + ### 0D. Mode-Specific Analysis **For SCOPE EXPANSION** — run all three: 1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely. @@ -196,6 +263,8 @@ Context-dependent defaults: * Plan touching >15 files → suggest REDUCTION unless user pushes back * User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question +After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach. + Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index ef14a281..400fb579 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -65,7 +65,19 @@ git stash list # Any stashed work grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files ``` -Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically: +Then read CLAUDE.md, TODOS.md, and any existing architecture docs. + +**Design doc check:** +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists (from `/brainstorm`), 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. + +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 * Flag dependencies: does this plan enable or depend on deferred items? @@ -102,6 +114,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m [describe] ---> [describe delta] ---> [describe target] ``` +### 0C-bis. Implementation Alternatives (MANDATORY) + +Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences]. + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial plans. +- One approach must be the "minimal viable" (fewest files, smallest diff). +- One approach must be the "ideal architecture" (best long-term trajectory). +- If only one approach exists, explain concretely why alternatives were eliminated. +- Do NOT proceed to mode selection (0F) without user approval of the chosen approach. + ### 0D. Mode-Specific Analysis **For SCOPE EXPANSION** — run all three: 1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely. @@ -139,6 +181,8 @@ Context-dependent defaults: * Plan touching >15 files → suggest REDUCTION unless user pushes back * User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question +After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach. + Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. From 50d0bc22f610f7403ccc03d57d9b9268b7ff44b7 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:10:26 -0500 Subject: [PATCH 05/12] feat: design doc lookup in /plan-eng-review + fix branch name sanitization Step 0 now checks ~/.gstack/projects/ for /brainstorm design docs (branch-filtered with fallback, reads Supersedes: for revision context). Fix: branch names with '/' (e.g. garrytan/better-process) now get sanitized via tr '/' '-' in test plan artifact filenames. Co-Authored-By: Claude Opus 4.6 (1M context) --- plan-eng-review/SKILL.md | 37 ++++++++++++++++++++++++++++++++++- plan-eng-review/SKILL.md.tmpl | 12 +++++++++++- 2 files changed, 47 insertions(+), 2 deletions(-) diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 819ef072..b9934838 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -73,6 +73,31 @@ Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-log Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + # Plan Review Mode Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction. @@ -95,6 +120,16 @@ If you are running low on context or the user asks you to compress: Step 0 > Tes ## BEFORE YOU START: +### Design Doc Check +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists, 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 — check the prior version for context on what changed and why. + ### Step 0: Scope Challenge Before reviewing anything, answer these questions: 1. **What existing code already partially or fully solves each sub-problem?** Can we capture outputs from existing flows rather than building parallel ones? @@ -147,7 +182,7 @@ After producing the test diagram, write a test plan artifact to the project dire ```bash SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-') -BRANCH=$(git rev-parse --abbrev-ref HEAD) +BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-') USER=$(whoami) DATETIME=$(date +%Y%m%d-%H%M%S) mkdir -p ~/.gstack/projects/$SLUG diff --git a/plan-eng-review/SKILL.md.tmpl b/plan-eng-review/SKILL.md.tmpl index 410b0726..57bca4c5 100644 --- a/plan-eng-review/SKILL.md.tmpl +++ b/plan-eng-review/SKILL.md.tmpl @@ -38,6 +38,16 @@ If you are running low on context or the user asks you to compress: Step 0 > Tes ## BEFORE YOU START: +### Design Doc Check +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) +[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" +``` +If a design doc exists, 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 — check the prior version for context on what changed and why. + ### Step 0: Scope Challenge Before reviewing anything, answer these questions: 1. **What existing code already partially or fully solves each sub-problem?** Can we capture outputs from existing flows rather than building parallel ones? @@ -90,7 +100,7 @@ After producing the test diagram, write a test plan artifact to the project dire ```bash SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-') -BRANCH=$(git rev-parse --abbrev-ref HEAD) +BRANCH=$(git rev-parse --abbrev-ref HEAD | tr '/' '-') USER=$(whoami) DATETIME=$(date +%Y%m%d-%H%M%S) mkdir -p ~/.gstack/projects/$SLUG From 4c0a3fe13b0cd03b2861a40c1f09043671260b05 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:10:41 -0500 Subject: [PATCH 06/12] feat: new /brainstorm and /debug skills /brainstorm: Socratic design exploration before planning. Context gathering, clarifying questions (smart-skip), related design discovery (keyword grep), premise challenge, forced alternatives, design doc artifact with lineage tracking (Supersedes: field). Writes to ~/.gstack/projects/$SLUG/. /debug: Systematic root-cause debugging. Iron Law: no fixes without root cause investigation. Pattern analysis, hypothesis testing with 3-strike escalation, structured DEBUG REPORT output. Co-Authored-By: Claude Opus 4.6 (1M context) --- brainstorm/SKILL.md | 307 +++++++++++++++++++++++++++++++++++++++ brainstorm/SKILL.md.tmpl | 225 ++++++++++++++++++++++++++++ debug/SKILL.md | 230 +++++++++++++++++++++++++++++ debug/SKILL.md.tmpl | 148 +++++++++++++++++++ 4 files changed, 910 insertions(+) create mode 100644 brainstorm/SKILL.md create mode 100644 brainstorm/SKILL.md.tmpl create mode 100644 debug/SKILL.md create mode 100644 debug/SKILL.md.tmpl diff --git a/brainstorm/SKILL.md b/brainstorm/SKILL.md new file mode 100644 index 00000000..02992bba --- /dev/null +++ b/brainstorm/SKILL.md @@ -0,0 +1,307 @@ +--- +name: brainstorm +version: 1.0.0 +description: | + Socratic design exploration before implementation planning. Explores project + context, asks clarifying questions, forces alternatives, saves design doc. + Use before /plan-ceo-review or /plan-eng-review. +allowed-tools: + - Bash + - Read + - Grep + - Glob + - Write + - Edit + - AskUserQuestion +--- + + + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +``` + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. Context: project name, current branch, what we're working on (1-2 sentences) +2. The specific question or decision point +3. `RECOMMENDATION: Choose [X] because [one-line reason]` +4. Lettered options: `A) ... B) ... C) ...` + +If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. When you hit friction with **gstack itself** (not the user's app), file a field report. Think: "hey, I was trying to do X with gstack and it didn't work / was confusing / was annoying. Here's what happened." + +**gstack issues:** browse command fails/wrong output, snapshot missing elements, skill instructions unclear or misleading, binary crash/hang, unhelpful error message, any rough edge or annoyance — even minor stuff. +**NOT gstack issues:** user's app bugs, network errors to user's URL, auth failures on user's site. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with this structure: + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**How annoying (1-5):** {1=meh, 3=friction, 5=blocker} + +## Steps to reproduce +1. {step} + +## Raw output +(wrap any error messages or unexpected output in a markdown code block) + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-logs/{slug}.md` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + +# Brainstorm — Design Exploration + +You are a **design thinking partner**. Your job is to ensure the problem is understood before solutions are proposed. This skill produces design docs, not code. + +**HARD GATE:** Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action. Your only output is a design document. + +--- + +## Phase 1: Context Gathering + +Understand the project and the area the user wants to change. + +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +``` + +1. Read `CLAUDE.md`, `TODOS.md` (if they exist). +2. Run `git log --oneline -30` and `git diff origin/main --stat 2>/dev/null` to understand recent context. +3. Use Grep/Glob to map the codebase areas most relevant to the user's request. +4. **List existing design docs for this project:** + ```bash + ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null + ``` + If design docs exist, list them: "Prior designs for this project: [titles + dates]" + +Output: "Here's what I understand about this project and the area you want to change: ..." + +--- + +## Phase 2: Socratic Questioning + +Ask clarifying questions **ONE AT A TIME** via AskUserQuestion. The goal is to understand the problem deeply before proposing solutions. + +Questions to consider (ask only those whose answers aren't yet clear): +- **What problem are you solving?** (user outcome, not technical task) +- **Who is affected and how?** (scope of impact) +- **What constraints exist?** (time, tech debt, dependencies, team capacity) +- **What does success look like?** (measurable criteria) +- **What have you already tried or considered?** (avoid re-treading) + +**Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear. + +**STOP** after each question. Wait for the response before asking the next. + +**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. + +--- + +## Phase 2.5: Related Design Discovery + +After the user states the problem (first question in Phase 2), search existing design docs for keyword overlap. + +Extract 3-5 significant keywords from the user's problem statement and grep across design docs: +```bash +grep -li "\|\|" ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null +``` + +If matches found, read the matching design docs and surface them: +- "FYI: Related design found — '{title}' by {user} on {date} (branch: {branch}). Key overlap: {1-line summary of relevant section}." +- Ask via AskUserQuestion: "Should we build on this prior design or start fresh?" + +This enables cross-team discovery — multiple users exploring the same project will see each other's design docs in `~/.gstack/projects/`. + +If no matches found, proceed silently. + +--- + +## Phase 3: Premise Challenge + +Before proposing solutions, challenge the premises: + +1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution? +2. **What happens if we do nothing?** Real pain point or hypothetical one? +3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused. + +Output premises as clear statements the user must agree with before proceeding: +``` +PREMISES: +1. [statement] — agree/disagree? +2. [statement] — agree/disagree? +3. [statement] — agree/disagree? +``` + +Use AskUserQuestion to confirm. If the user disagrees with a premise, revise understanding and loop back. + +--- + +## Phase 4: Alternatives Generation (MANDATORY) + +Produce 2-3 distinct implementation approaches. This is NOT optional. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial designs. +- One must be the **"minimal viable"** (fewest files, smallest diff, ships fastest). +- One must be the **"ideal architecture"** (best long-term trajectory, most elegant). +- One can be **creative/lateral** (unexpected approach, different framing of the problem). + +**RECOMMENDATION:** Choose [X] because [one-line reason]. + +Present via AskUserQuestion. Do NOT proceed without user approval of the approach. + +--- + +## Phase 5: Design Doc + +Write the design document to the project directory. + +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +USER=$(whoami) +DATETIME=$(date +%Y%m%d-%H%M%S) +mkdir -p ~/.gstack/projects/$SLUG +``` + +**Design lineage:** Before writing, check for existing design docs on this branch: +```bash +PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +``` +If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across brainstorm sessions. + +Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: + +```markdown +# Design: {title} + +Generated by /brainstorm on {date} +Branch: {branch} +Repo: {owner/repo} +Status: DRAFT +Supersedes: {prior filename — omit this line if first design on this branch} + +## Problem Statement +{from Phase 2} + +## Constraints +{from Phase 2} + +## Premises +{from Phase 3} + +## Approaches Considered +### Approach A: {name} +{from Phase 4} +### Approach B: {name} +{from Phase 4} + +## Recommended Approach +{chosen approach with rationale} + +## Open Questions +{any unresolved questions from the brainstorm} + +## Success Criteria +{measurable criteria from Phase 2} + +## Dependencies +{blockers, prerequisites, related work} +``` + +Present the design doc to the user via AskUserQuestion: +- A) Approve — mark Status: APPROVED and proceed to handoff +- B) Revise — specify which sections need changes (loop back to revise those sections) +- C) Start over — return to Phase 2 + +--- + +## Phase 6: Handoff + +Once the design doc is APPROVED, suggest the next step: + +- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product +- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases +- **`/plan-design-review`** for visual/UX design review (coming soon) + +The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit. + +--- + +## Important Rules + +- **Never start implementation.** This skill produces design docs, not code. Not even scaffolding. +- **Questions ONE AT A TIME.** Never batch multiple questions into one AskUserQuestion. +- **If user provides a fully formed plan:** skip Phase 2 (Socratic Questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. +- **Completion status:** + - DONE — design doc APPROVED + - DONE_WITH_CONCERNS — design doc approved but with open questions listed + - NEEDS_CONTEXT — user left questions unanswered, design incomplete diff --git a/brainstorm/SKILL.md.tmpl b/brainstorm/SKILL.md.tmpl new file mode 100644 index 00000000..86031e12 --- /dev/null +++ b/brainstorm/SKILL.md.tmpl @@ -0,0 +1,225 @@ +--- +name: brainstorm +version: 1.0.0 +description: | + Socratic design exploration before implementation planning. Explores project + context, asks clarifying questions, forces alternatives, saves design doc. + Use before /plan-ceo-review or /plan-eng-review. +allowed-tools: + - Bash + - Read + - Grep + - Glob + - Write + - Edit + - AskUserQuestion +--- + +{{PREAMBLE}} + +# Brainstorm — Design Exploration + +You are a **design thinking partner**. Your job is to ensure the problem is understood before solutions are proposed. This skill produces design docs, not code. + +**HARD GATE:** Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action. Your only output is a design document. + +--- + +## Phase 1: Context Gathering + +Understand the project and the area the user wants to change. + +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +``` + +1. Read `CLAUDE.md`, `TODOS.md` (if they exist). +2. Run `git log --oneline -30` and `git diff origin/main --stat 2>/dev/null` to understand recent context. +3. Use Grep/Glob to map the codebase areas most relevant to the user's request. +4. **List existing design docs for this project:** + ```bash + ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null + ``` + If design docs exist, list them: "Prior designs for this project: [titles + dates]" + +Output: "Here's what I understand about this project and the area you want to change: ..." + +--- + +## Phase 2: Socratic Questioning + +Ask clarifying questions **ONE AT A TIME** via AskUserQuestion. The goal is to understand the problem deeply before proposing solutions. + +Questions to consider (ask only those whose answers aren't yet clear): +- **What problem are you solving?** (user outcome, not technical task) +- **Who is affected and how?** (scope of impact) +- **What constraints exist?** (time, tech debt, dependencies, team capacity) +- **What does success look like?** (measurable criteria) +- **What have you already tried or considered?** (avoid re-treading) + +**Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear. + +**STOP** after each question. Wait for the response before asking the next. + +**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. + +--- + +## Phase 2.5: Related Design Discovery + +After the user states the problem (first question in Phase 2), search existing design docs for keyword overlap. + +Extract 3-5 significant keywords from the user's problem statement and grep across design docs: +```bash +grep -li "\|\|" ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null +``` + +If matches found, read the matching design docs and surface them: +- "FYI: Related design found — '{title}' by {user} on {date} (branch: {branch}). Key overlap: {1-line summary of relevant section}." +- Ask via AskUserQuestion: "Should we build on this prior design or start fresh?" + +This enables cross-team discovery — multiple users exploring the same project will see each other's design docs in `~/.gstack/projects/`. + +If no matches found, proceed silently. + +--- + +## Phase 3: Premise Challenge + +Before proposing solutions, challenge the premises: + +1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution? +2. **What happens if we do nothing?** Real pain point or hypothetical one? +3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused. + +Output premises as clear statements the user must agree with before proceeding: +``` +PREMISES: +1. [statement] — agree/disagree? +2. [statement] — agree/disagree? +3. [statement] — agree/disagree? +``` + +Use AskUserQuestion to confirm. If the user disagrees with a premise, revise understanding and loop back. + +--- + +## Phase 4: Alternatives Generation (MANDATORY) + +Produce 2-3 distinct implementation approaches. This is NOT optional. + +For each approach: +``` +APPROACH A: [Name] + Summary: [1-2 sentences] + Effort: [S/M/L/XL] + Risk: [Low/Med/High] + Pros: [2-3 bullets] + Cons: [2-3 bullets] + Reuses: [existing code/patterns leveraged] + +APPROACH B: [Name] + ... + +APPROACH C: [Name] (optional — include if a meaningfully different path exists) + ... +``` + +Rules: +- At least 2 approaches required. 3 preferred for non-trivial designs. +- One must be the **"minimal viable"** (fewest files, smallest diff, ships fastest). +- One must be the **"ideal architecture"** (best long-term trajectory, most elegant). +- One can be **creative/lateral** (unexpected approach, different framing of the problem). + +**RECOMMENDATION:** Choose [X] because [one-line reason]. + +Present via AskUserQuestion. Do NOT proceed without user approval of the approach. + +--- + +## Phase 5: Design Doc + +Write the design document to the project directory. + +```bash +SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)") +BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch') +USER=$(whoami) +DATETIME=$(date +%Y%m%d-%H%M%S) +mkdir -p ~/.gstack/projects/$SLUG +``` + +**Design lineage:** Before writing, check for existing design docs on this branch: +```bash +PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) +``` +If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across brainstorm sessions. + +Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: + +```markdown +# Design: {title} + +Generated by /brainstorm on {date} +Branch: {branch} +Repo: {owner/repo} +Status: DRAFT +Supersedes: {prior filename — omit this line if first design on this branch} + +## Problem Statement +{from Phase 2} + +## Constraints +{from Phase 2} + +## Premises +{from Phase 3} + +## Approaches Considered +### Approach A: {name} +{from Phase 4} +### Approach B: {name} +{from Phase 4} + +## Recommended Approach +{chosen approach with rationale} + +## Open Questions +{any unresolved questions from the brainstorm} + +## Success Criteria +{measurable criteria from Phase 2} + +## Dependencies +{blockers, prerequisites, related work} +``` + +Present the design doc to the user via AskUserQuestion: +- A) Approve — mark Status: APPROVED and proceed to handoff +- B) Revise — specify which sections need changes (loop back to revise those sections) +- C) Start over — return to Phase 2 + +--- + +## Phase 6: Handoff + +Once the design doc is APPROVED, suggest the next step: + +- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product +- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases +- **`/plan-design-review`** for visual/UX design review (coming soon) + +The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit. + +--- + +## Important Rules + +- **Never start implementation.** This skill produces design docs, not code. Not even scaffolding. +- **Questions ONE AT A TIME.** Never batch multiple questions into one AskUserQuestion. +- **If user provides a fully formed plan:** skip Phase 2 (Socratic Questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. +- **Completion status:** + - DONE — design doc APPROVED + - DONE_WITH_CONCERNS — design doc approved but with open questions listed + - NEEDS_CONTEXT — user left questions unanswered, design incomplete diff --git a/debug/SKILL.md b/debug/SKILL.md new file mode 100644 index 00000000..23a6ba5a --- /dev/null +++ b/debug/SKILL.md @@ -0,0 +1,230 @@ +--- +name: debug +version: 1.0.0 +description: | + Systematic debugging with root cause investigation. Four phases: investigate, + analyze, hypothesize, implement. Iron Law: no fixes without root cause. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + + + +## Preamble (run first) + +```bash +_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true) +[ -n "$_UPD" ] && echo "$_UPD" || true +mkdir -p ~/.gstack/sessions +touch ~/.gstack/sessions/"$PPID" +_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') +find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true +_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +``` + +If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. + +## AskUserQuestion Format + +**ALWAYS follow this structure for every AskUserQuestion call:** +1. Context: project name, current branch, what we're working on (1-2 sentences) +2. The specific question or decision point +3. `RECOMMENDATION: Choose [X] because [one-line reason]` +4. Lettered options: `A) ... B) ... C) ...` + +If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. + +Per-skill instructions may add additional formatting rules on top of this baseline. + +## Contributor Mode + +If `_CONTRIB` is `true`: you are in **contributor mode**. When you hit friction with **gstack itself** (not the user's app), file a field report. Think: "hey, I was trying to do X with gstack and it didn't work / was confusing / was annoying. Here's what happened." + +**gstack issues:** browse command fails/wrong output, snapshot missing elements, skill instructions unclear or misleading, binary crash/hang, unhelpful error message, any rough edge or annoyance — even minor stuff. +**NOT gstack issues:** user's app bugs, network errors to user's URL, auth failures on user's site. + +**To file:** write `~/.gstack/contributor-logs/{slug}.md` with this structure: + +``` +# {Title} + +Hey gstack team — ran into this while using /{skill-name}: + +**What I was trying to do:** {what the user/agent was attempting} +**What happened instead:** {what actually happened} +**How annoying (1-5):** {1=meh, 3=friction, 5=blocker} + +## Steps to reproduce +1. {step} + +## Raw output +(wrap any error messages or unexpected output in a markdown code block) + +**Date:** {YYYY-MM-DD} | **Version:** {gstack version} | **Skill:** /{skill} +``` + +Then run: `mkdir -p ~/.gstack/contributor-logs && open ~/.gstack/contributor-logs/{slug}.md` + +Slug: lowercase, hyphens, max 60 chars (e.g. `browse-snapshot-ref-gap`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}" + +## Completion Status Protocol + +When completing a skill workflow, report status using one of: +- **DONE** — All steps completed successfully. Evidence provided for each claim. +- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern. +- **BLOCKED** — Cannot proceed. State what is blocking and what was tried. +- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need. + +### Escalation + +It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result." + +Bad work is worse than no work. You will not be penalized for escalating. +- If you have attempted a task 3 times without success, STOP and escalate. +- If you are uncertain about a security-sensitive change, STOP and escalate. +- If the scope of work exceeds what you can verify, STOP and escalate. + +Escalation format: +``` +STATUS: BLOCKED | NEEDS_CONTEXT +REASON: [1-2 sentences] +ATTEMPTED: [what you tried] +RECOMMENDATION: [what the user should do next] +``` + +# Systematic Debugging + +## Iron Law + +**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.** + +Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it. + +--- + +## Phase 1: Root Cause Investigation + +Gather context before forming any hypothesis. + +1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time via AskUserQuestion. + +2. **Read the code:** Trace the code path from the symptom back to potential causes. Use Grep to find all references, Read to understand the logic. + +3. **Check recent changes:** + ```bash + git log --oneline -20 -- + ``` + Was this working before? What changed? A regression means the root cause is in the diff. + +4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding. + +Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why. + +--- + +## Phase 2: Pattern Analysis + +Check if this bug matches a known pattern: + +| Pattern | Signature | Where to look | +|---------|-----------|---------------| +| Race condition | Intermittent, timing-dependent | Concurrent access to shared state | +| Nil/null propagation | NoMethodError, TypeError | Missing guards on optional values | +| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks | +| Integration failure | Timeout, unexpected response | External API calls, service boundaries | +| Configuration drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state | +| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache, Turbo | + +Also check: +- `TODOS.md` for related known issues +- `git log` for prior fixes in the same area — **recurring bugs in the same files are an architectural smell**, not a coincidence + +--- + +## Phase 3: Hypothesis Testing + +Before writing ANY fix, verify your hypothesis. + +1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match? + +2. **If the hypothesis is wrong:** Return to Phase 1. Gather more evidence. Do not guess. + +3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion: + ``` + 3 hypotheses tested, none match. This may be an architectural issue + rather than a simple bug. + + A) Continue investigating — I have a new hypothesis: [describe] + B) Escalate for human review — this needs someone who knows the system + C) Add logging and wait — instrument the area and catch it next time + ``` + +**Red flags** — if you see any of these, slow down: +- "Quick fix for now" — there is no "for now." Fix it right or escalate. +- Proposing a fix before tracing data flow — you're guessing. +- Each fix reveals a new problem elsewhere — wrong layer, not wrong code. + +--- + +## Phase 4: Implementation + +Once root cause is confirmed: + +1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem. + +2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code. + +3. **Write a regression test** that: + - **Fails** without the fix (proves the test is meaningful) + - **Passes** with the fix (proves the fix works) + +4. **Run the full test suite.** Paste the output. No regressions allowed. + +5. **If the fix touches >5 files:** Use AskUserQuestion to flag the blast radius: + ``` + This fix touches N files. That's a large blast radius for a bug fix. + A) Proceed — the root cause genuinely spans these files + B) Split — fix the critical path now, defer the rest + C) Rethink — maybe there's a more targeted approach + ``` + +--- + +## Phase 5: Verification & Report + +**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional. + +Run the test suite and paste the output. + +Output a structured debug report: +``` +DEBUG REPORT +════════════════════════════════════════ +Symptom: [what the user observed] +Root cause: [what was actually wrong] +Fix: [what was changed, with file:line references] +Evidence: [test output, reproduction attempt showing fix works] +Regression test: [file:line of the new test] +Related: [TODOS.md items, prior bugs in same area, architectural notes] +Status: DONE | DONE_WITH_CONCERNS | BLOCKED +════════════════════════════════════════ +``` + +--- + +## Important Rules + +- **3+ failed fix attempts → STOP and question the architecture.** Wrong architecture, not failed hypothesis. +- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it. +- **Never say "this should fix it."** Verify and prove it. Run the tests. +- **If fix touches >5 files → AskUserQuestion** about blast radius before proceeding. +- **Completion status:** + - DONE — root cause found, fix applied, regression test written, all tests pass + - DONE_WITH_CONCERNS — fixed but cannot fully verify (e.g., intermittent bug, requires staging) + - BLOCKED — root cause unclear after investigation, escalated diff --git a/debug/SKILL.md.tmpl b/debug/SKILL.md.tmpl new file mode 100644 index 00000000..312d2420 --- /dev/null +++ b/debug/SKILL.md.tmpl @@ -0,0 +1,148 @@ +--- +name: debug +version: 1.0.0 +description: | + Systematic debugging with root cause investigation. Four phases: investigate, + analyze, hypothesize, implement. Iron Law: no fixes without root cause. +allowed-tools: + - Bash + - Read + - Write + - Edit + - Grep + - Glob + - AskUserQuestion +--- + +{{PREAMBLE}} + +# Systematic Debugging + +## Iron Law + +**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.** + +Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address root cause makes the next bug harder to find. Find the root cause, then fix it. + +--- + +## Phase 1: Root Cause Investigation + +Gather context before forming any hypothesis. + +1. **Collect symptoms:** Read the error messages, stack traces, and reproduction steps. If the user hasn't provided enough context, ask ONE question at a time via AskUserQuestion. + +2. **Read the code:** Trace the code path from the symptom back to potential causes. Use Grep to find all references, Read to understand the logic. + +3. **Check recent changes:** + ```bash + git log --oneline -20 -- + ``` + Was this working before? What changed? A regression means the root cause is in the diff. + +4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding. + +Output: **"Root cause hypothesis: ..."** — a specific, testable claim about what is wrong and why. + +--- + +## Phase 2: Pattern Analysis + +Check if this bug matches a known pattern: + +| Pattern | Signature | Where to look | +|---------|-----------|---------------| +| Race condition | Intermittent, timing-dependent | Concurrent access to shared state | +| Nil/null propagation | NoMethodError, TypeError | Missing guards on optional values | +| State corruption | Inconsistent data, partial updates | Transactions, callbacks, hooks | +| Integration failure | Timeout, unexpected response | External API calls, service boundaries | +| Configuration drift | Works locally, fails in staging/prod | Env vars, feature flags, DB state | +| Stale cache | Shows old data, fixes on cache clear | Redis, CDN, browser cache, Turbo | + +Also check: +- `TODOS.md` for related known issues +- `git log` for prior fixes in the same area — **recurring bugs in the same files are an architectural smell**, not a coincidence + +--- + +## Phase 3: Hypothesis Testing + +Before writing ANY fix, verify your hypothesis. + +1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match? + +2. **If the hypothesis is wrong:** Return to Phase 1. Gather more evidence. Do not guess. + +3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion: + ``` + 3 hypotheses tested, none match. This may be an architectural issue + rather than a simple bug. + + A) Continue investigating — I have a new hypothesis: [describe] + B) Escalate for human review — this needs someone who knows the system + C) Add logging and wait — instrument the area and catch it next time + ``` + +**Red flags** — if you see any of these, slow down: +- "Quick fix for now" — there is no "for now." Fix it right or escalate. +- Proposing a fix before tracing data flow — you're guessing. +- Each fix reveals a new problem elsewhere — wrong layer, not wrong code. + +--- + +## Phase 4: Implementation + +Once root cause is confirmed: + +1. **Fix the root cause, not the symptom.** The smallest change that eliminates the actual problem. + +2. **Minimal diff:** Fewest files touched, fewest lines changed. Resist the urge to refactor adjacent code. + +3. **Write a regression test** that: + - **Fails** without the fix (proves the test is meaningful) + - **Passes** with the fix (proves the fix works) + +4. **Run the full test suite.** Paste the output. No regressions allowed. + +5. **If the fix touches >5 files:** Use AskUserQuestion to flag the blast radius: + ``` + This fix touches N files. That's a large blast radius for a bug fix. + A) Proceed — the root cause genuinely spans these files + B) Split — fix the critical path now, defer the rest + C) Rethink — maybe there's a more targeted approach + ``` + +--- + +## Phase 5: Verification & Report + +**Fresh verification:** Reproduce the original bug scenario and confirm it's fixed. This is not optional. + +Run the test suite and paste the output. + +Output a structured debug report: +``` +DEBUG REPORT +════════════════════════════════════════ +Symptom: [what the user observed] +Root cause: [what was actually wrong] +Fix: [what was changed, with file:line references] +Evidence: [test output, reproduction attempt showing fix works] +Regression test: [file:line of the new test] +Related: [TODOS.md items, prior bugs in same area, architectural notes] +Status: DONE | DONE_WITH_CONCERNS | BLOCKED +════════════════════════════════════════ +``` + +--- + +## Important Rules + +- **3+ failed fix attempts → STOP and question the architecture.** Wrong architecture, not failed hypothesis. +- **Never apply a fix you cannot verify.** If you can't reproduce and confirm, don't ship it. +- **Never say "this should fix it."** Verify and prove it. Run the tests. +- **If fix touches >5 files → AskUserQuestion** about blast radius before proceeding. +- **Completion status:** + - DONE — root cause found, fix applied, regression test written, all tests pass + - DONE_WITH_CONCERNS — fixed but cannot fully verify (e.g., intermittent bug, requires staging) + - BLOCKED — root cause unclear after investigation, escalated From ba3c2dee2eeb3ea76e63ccc70277f35eb3b2b470 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:10:54 -0500 Subject: [PATCH 07/12] test: structural tests for new skills + escalation protocol assertions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add brainstorm + debug to skillsWithUpdateCheck and skillsWithPreamble arrays. Add structural tests: brainstorm (Phase 1-6, Design Doc, Supersedes, Smart-skip), debug (Iron Law, Root Cause, Pattern Analysis, Hypothesis, DEBUG REPORT, 3-strike). Add escalation protocol tests (DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT) for all preamble skills. Also: 2 new TODOs (design docs → Supabase sync, /plan-design-review skill), update CLAUDE.md project structure with new skill directories. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 2 ++ TODOS.md | 26 ++++++++++++++++++++++++++ test/skill-validation.test.ts | 30 ++++++++++++++++++++++++++++++ 3 files changed, 58 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e724b826..d0bddfbf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -47,6 +47,8 @@ gstack/ ├── review/ # PR review skill ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill +├── brainstorm/ # /brainstorm skill (Socratic design exploration) +├── debug/ # /debug skill (systematic root-cause debugging) ├── retro/ # Retrospective skill ├── setup # One-time setup: build binary + symlink skills ├── SKILL.md # Generated from SKILL.md.tmpl (don't edit directly) diff --git a/TODOS.md b/TODOS.md index 7bd1176a..eb8c95f0 100644 --- a/TODOS.md +++ b/TODOS.md @@ -374,6 +374,32 @@ **Priority:** P3 **Depends on:** Ref staleness Parts 1+2 (shipped) +## Brainstorm / Design + +### Design docs → Supabase team store sync + +**What:** Add design docs (`*-design-*.md`) to the Supabase sync pipeline alongside test plans, retro snapshots, and QA reports. + +**Why:** Cross-team design discovery at scale. Local `~/.gstack/projects/$SLUG/` keyword-grep discovery works for same-machine users now, but Supabase sync makes it work across the whole team. Duplicate ideas surface, everyone sees what's been explored. + +**Context:** /brainstorm writes design docs to `~/.gstack/projects/$SLUG/`. The team store already syncs test plans, retro snapshots, QA reports. Design docs follow the same pattern — just add a sync adapter. + +**Effort:** S +**Priority:** P2 +**Depends on:** `garrytan/team-supabase-store` branch landing on main + +### /plan-design-review skill + +**What:** A visual/UX-focused design review skill that consumes /brainstorm design docs and evaluates mockups, wireframes, and UI decisions. Completes the review trilogy — product (/plan-ceo-review), engineering (/plan-eng-review), design (/plan-design-review). + +**Why:** Full workflow coverage for visual/UX projects. The brainstorm design doc artifact is the input contract. + +**Context:** /brainstorm handoff already mentions this skill. The design doc at `~/.gstack/projects/` is the input. + +**Effort:** M +**Priority:** P2 +**Depends on:** `garrytan/design` branch landing on main + ## Completed ### Phase 1: Foundations (v0.2.0) diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 88e98935..bdec781b 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -176,6 +176,7 @@ describe('Update check preamble', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', + 'brainstorm/SKILL.md', 'debug/SKILL.md', ]; for (const skill of skillsWithUpdateCheck) { @@ -421,6 +422,7 @@ describe('v0.4.1 preamble features', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', + 'brainstorm/SKILL.md', 'debug/SKILL.md', ]; for (const skill of skillsWithPreamble) { @@ -436,6 +438,34 @@ describe('v0.4.1 preamble features', () => { expect(content).toContain('ELI16'); }); } + + for (const skill of skillsWithPreamble) { + test(`${skill} contains escalation protocol`, () => { + const content = fs.readFileSync(path.join(ROOT, skill), 'utf-8'); + expect(content).toContain('DONE_WITH_CONCERNS'); + expect(content).toContain('BLOCKED'); + expect(content).toContain('NEEDS_CONTEXT'); + }); + } +}); + +// --- Structural tests for new skills --- + +describe('brainstorm skill structure', () => { + const content = fs.readFileSync(path.join(ROOT, 'brainstorm', 'SKILL.md'), 'utf-8'); + for (const section of ['Phase 1', 'Phase 2', 'Phase 3', 'Phase 4', 'Phase 5', 'Phase 6', + 'Design Doc', 'Supersedes', 'APPROVED', 'Premise Challenge', + 'Alternatives', 'Smart-skip']) { + test(`contains ${section}`, () => expect(content).toContain(section)); + } +}); + +describe('debug skill structure', () => { + const content = fs.readFileSync(path.join(ROOT, 'debug', 'SKILL.md'), 'utf-8'); + for (const section of ['Iron Law', 'Root Cause', 'Pattern Analysis', 'Hypothesis', + 'DEBUG REPORT', '3-strike', 'BLOCKED']) { + test(`contains ${section}`, () => expect(content).toContain(section)); + } }); describe('Enum & Value Completeness in review checklist', () => { From 69fcf2d3ac2a14af4edbb455cb386529d22cb73d Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 11:12:46 -0500 Subject: [PATCH 08/12] chore: bump version and changelog (v0.6.0) Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 21 +++++++++++++++++++++ VERSION | 2 +- 2 files changed, 22 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 57c2c1a0..ded48ada 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,26 @@ # Changelog +## 0.6.0 — 2026-03-16 + +### Added +- **New `/brainstorm` skill — think before you build.** Socratic design exploration that runs before planning. Asks clarifying questions one at a time, challenges your premises, forces you to consider 2-3 implementation approaches, then writes a design doc. The design doc feeds directly into `/plan-ceo-review` and `/plan-eng-review`. You can now do `brainstorm → plan → implement → review → QA → ship → retro` — the full lifecycle. +- **New `/debug` skill — find the root cause, not the symptom.** Systematic debugging with an Iron Law: no fixes without root cause investigation first. Traces data flow, matches against known bug patterns, tests hypotheses one at a time. If 3 fixes fail, it stops and questions the architecture instead of thrashing. +- **Every skill now knows when to stop.** New escalation protocol across all skills: DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT. "It is always OK to stop and say 'this is too hard for me.' Bad work is worse than no work." +- **/ship now re-verifies before pushing.** New verification gate (Step 6.5): if code changed during review fixes, tests must pass again before push. No more "should work now" — run it and prove it. +- **/review now catches scope drift.** Before reviewing code quality, Step 1.5 compares the diff against TODOS.md and commit messages. Flags files changed that weren't in the plan, and requirements that weren't addressed in the diff. +- **/review now cites evidence for every claim.** "This pattern is safe" requires a line reference. "Tests cover this" requires a test name. No more "probably handled." +- **/plan-ceo-review now forces you to consider alternatives.** Step 0C-bis requires 2-3 implementation approaches before mode selection — one minimal, one ideal. You pick the approach, then the review runs against it. +- **Design docs flow downstream automatically.** `/brainstorm` writes design docs to `~/.gstack/projects/`. `/plan-ceo-review` and `/plan-eng-review` discover and read them during their pre-review audits. Branch-filtered lookup with fallback. +- **Design lineage tracking.** Brainstorm the same feature twice? The second design doc links to the first via a `Supersedes:` field. Trace how your design evolved. + +### Fixed +- Branch names with `/` (like `garrytan/better-process`) no longer break artifact filenames. Fixed in `/brainstorm` and `/plan-eng-review` test plan artifacts. + +### For contributors +- New structural tests for `/brainstorm` (Phase headers, Design Doc, Supersedes, Smart-skip) and `/debug` (Iron Law, Root Cause, Pattern Analysis, Hypothesis, DEBUG REPORT, 3-strike). +- Escalation protocol assertions added to all preamble skills (DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT). +- Two new TODOs: design docs → Supabase team store sync (P2), /plan-design-review skill (P2). + ## 0.4.1 — 2026-03-16 - **gstack now notices when it screws up.** Turn on contributor mode (`gstack-config set gstack_contributor true`) and gstack automatically writes up what went wrong — what you were doing, what broke, repro steps. Next time something annoys you, the bug report is already written. Fork gstack and fix it yourself. diff --git a/VERSION b/VERSION index 267577d4..a918a2aa 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.4.1 +0.6.0 From efa519b8811db22df7e8d396d2b2dd68312fafc0 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 05:50:04 -0700 Subject: [PATCH 09/12] =?UTF-8?q?chore:=20rename=20/brainstorm=20=E2=86=92?= =?UTF-8?q?=20/office-hours=20across=20references?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update CHANGELOG, CLAUDE.md, TODOS, design-consultation, plan-ceo-review, and gen-skill-docs to reference the new office-hours skill name. Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 10 +++++----- CLAUDE.md | 2 +- TODOS.md | 4 ++-- design-consultation/SKILL.md | 12 ++++++------ design-consultation/SKILL.md.tmpl | 12 ++++++------ {brainstorm => office-hours}/SKILL.md | 0 {brainstorm => office-hours}/SKILL.md.tmpl | 0 plan-ceo-review/SKILL.md | 2 +- plan-ceo-review/SKILL.md.tmpl | 2 +- scripts/gen-skill-docs.ts | 2 +- 10 files changed, 23 insertions(+), 23 deletions(-) rename {brainstorm => office-hours}/SKILL.md (100%) rename {brainstorm => office-hours}/SKILL.md.tmpl (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index 939d3b95..14bf1c2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,21 +3,21 @@ ## 0.6.0 — 2026-03-16 ### Added -- **New `/brainstorm` skill — think before you build.** Socratic design exploration that runs before planning. Asks clarifying questions one at a time, challenges your premises, forces you to consider 2-3 implementation approaches, then writes a design doc. The design doc feeds directly into `/plan-ceo-review` and `/plan-eng-review`. You can now do `brainstorm → plan → implement → review → QA → ship → retro` — the full lifecycle. +- **New `/office-hours` skill — think before you build.** YC-style office hours that run before planning. Asks clarifying questions one at a time, challenges your premises, forces you to consider 2-3 implementation approaches, then writes a design doc. The design doc feeds directly into `/plan-ceo-review` and `/plan-eng-review`. You can now do `office-hours → plan → implement → review → QA → ship → retro` — the full lifecycle. - **New `/debug` skill — find the root cause, not the symptom.** Systematic debugging with an Iron Law: no fixes without root cause investigation first. Traces data flow, matches against known bug patterns, tests hypotheses one at a time. If 3 fixes fail, it stops and questions the architecture instead of thrashing. - **Every skill now knows when to stop.** New escalation protocol across all skills: DONE, DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT. "It is always OK to stop and say 'this is too hard for me.' Bad work is worse than no work." - **/ship now re-verifies before pushing.** New verification gate (Step 6.5): if code changed during review fixes, tests must pass again before push. No more "should work now" — run it and prove it. - **/review now catches scope drift.** Before reviewing code quality, Step 1.5 compares the diff against TODOS.md and commit messages. Flags files changed that weren't in the plan, and requirements that weren't addressed in the diff. - **/review now cites evidence for every claim.** "This pattern is safe" requires a line reference. "Tests cover this" requires a test name. No more "probably handled." - **/plan-ceo-review now forces you to consider alternatives.** Step 0C-bis requires 2-3 implementation approaches before mode selection — one minimal, one ideal. You pick the approach, then the review runs against it. -- **Design docs flow downstream automatically.** `/brainstorm` writes design docs to `~/.gstack/projects/`. `/plan-ceo-review` and `/plan-eng-review` discover and read them during their pre-review audits. Branch-filtered lookup with fallback. -- **Design lineage tracking.** Brainstorm the same feature twice? The second design doc links to the first via a `Supersedes:` field. Trace how your design evolved. +- **Design docs flow downstream automatically.** `/office-hours` writes design docs to `~/.gstack/projects/`. `/plan-ceo-review` and `/plan-eng-review` discover and read them during their pre-review audits. Branch-filtered lookup with fallback. +- **Design lineage tracking.** Run office hours on the same feature twice? The second design doc links to the first via a `Supersedes:` field. Trace how your design evolved. ### Fixed -- Branch names with `/` (like `garrytan/better-process`) no longer break artifact filenames. Fixed in `/brainstorm` and `/plan-eng-review` test plan artifacts. +- Branch names with `/` (like `garrytan/better-process`) no longer break artifact filenames. Fixed in `/office-hours` and `/plan-eng-review` test plan artifacts. ### For contributors -- New structural tests for `/brainstorm` (Phase headers, Design Doc, Supersedes, Smart-skip) and `/debug` (Iron Law, Root Cause, Pattern Analysis, Hypothesis, DEBUG REPORT, 3-strike). +- New structural tests for `/office-hours` (Phase headers, Design Doc, Supersedes, Smart-skip) and `/debug` (Iron Law, Root Cause, Pattern Analysis, Hypothesis, DEBUG REPORT, 3-strike). - Escalation protocol assertions added to all preamble skills (DONE_WITH_CONCERNS, BLOCKED, NEEDS_CONTEXT). - Two new TODOs: design docs → Supabase team store sync (P2), /plan-design-review skill (P2). diff --git a/CLAUDE.md b/CLAUDE.md index 1b3ed112..42f632c8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ gstack/ ├── review/ # PR review skill ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill -├── brainstorm/ # /brainstorm skill (Socratic design exploration) +├── office-hours/ # /office-hours skill (YC-style design exploration) ├── debug/ # /debug skill (systematic root-cause debugging) ├── retro/ # Retrospective skill ├── document-release/ # /document-release skill (post-ship doc updates) diff --git a/TODOS.md b/TODOS.md index 7eac1e58..f293e706 100644 --- a/TODOS.md +++ b/TODOS.md @@ -374,7 +374,7 @@ **Priority:** P3 **Depends on:** Ref staleness Parts 1+2 (shipped) -## Brainstorm / Design +## Office Hours / Design ### Design docs → Supabase team store sync @@ -382,7 +382,7 @@ **Why:** Cross-team design discovery at scale. Local `~/.gstack/projects/$SLUG/` keyword-grep discovery works for same-machine users now, but Supabase sync makes it work across the whole team. Duplicate ideas surface, everyone sees what's been explored. -**Context:** /brainstorm writes design docs to `~/.gstack/projects/$SLUG/`. The team store already syncs test plans, retro snapshots, QA reports. Design docs follow the same pattern — just add a sync adapter. +**Context:** /office-hours writes design docs to `~/.gstack/projects/$SLUG/`. The team store already syncs test plans, retro snapshots, QA reports. Design docs follow the same pattern — just add a sync adapter. **Effort:** S **Priority:** P2 diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 47f48558..66826978 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -136,17 +136,17 @@ cat package.json 2>/dev/null | head -20 ls src/ app/ pages/ components/ 2>/dev/null | head -30 ``` -Look for brainstorm output: +Look for office-hours output: ```bash SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-') -ls ~/.gstack/projects/$SLUG/*brainstorm* 2>/dev/null | head -5 -ls .context/*brainstorm* .context/attachments/*brainstorm* 2>/dev/null | head -5 +ls ~/.gstack/projects/$SLUG/*office-hours* 2>/dev/null | head -5 +ls .context/*office-hours* .context/attachments/*office-hours* 2>/dev/null | head -5 ``` -If brainstorm output exists, read it — the product context is pre-filled. +If office-hours output exists, read it — the product context is pre-filled. -If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to brainstorm first with `/brainstorm`? Once we know the product direction, we can set up the design system."* +If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to explore first with `/office-hours`? Once we know the product direction, we can set up the design system."* --- @@ -160,7 +160,7 @@ Ask the user a single question that covers everything you need to know. Pre-fill 3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?" 4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation." -If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"* +If the README or office-hours output gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"* --- diff --git a/design-consultation/SKILL.md.tmpl b/design-consultation/SKILL.md.tmpl index 11d868fa..68ea9d28 100644 --- a/design-consultation/SKILL.md.tmpl +++ b/design-consultation/SKILL.md.tmpl @@ -46,17 +46,17 @@ cat package.json 2>/dev/null | head -20 ls src/ app/ pages/ components/ 2>/dev/null | head -30 ``` -Look for brainstorm output: +Look for office-hours output: ```bash SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-') -ls ~/.gstack/projects/$SLUG/*brainstorm* 2>/dev/null | head -5 -ls .context/*brainstorm* .context/attachments/*brainstorm* 2>/dev/null | head -5 +ls ~/.gstack/projects/$SLUG/*office-hours* 2>/dev/null | head -5 +ls .context/*office-hours* .context/attachments/*office-hours* 2>/dev/null | head -5 ``` -If brainstorm output exists, read it — the product context is pre-filled. +If office-hours output exists, read it — the product context is pre-filled. -If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to brainstorm first with `/brainstorm`? Once we know the product direction, we can set up the design system."* +If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to explore first with `/office-hours`? Once we know the product direction, we can set up the design system."* --- @@ -70,7 +70,7 @@ Ask the user a single question that covers everything you need to know. Pre-fill 3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?" 4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation." -If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"* +If the README or office-hours output gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"* --- diff --git a/brainstorm/SKILL.md b/office-hours/SKILL.md similarity index 100% rename from brainstorm/SKILL.md rename to office-hours/SKILL.md diff --git a/brainstorm/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl similarity index 100% rename from brainstorm/SKILL.md.tmpl rename to office-hours/SKILL.md.tmpl diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index dc1de1ce..f0d4b9b5 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -184,7 +184,7 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` -If a design doc exists (from `/brainstorm`), 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. +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. When reading TODOS.md, specifically: * Note any TODOs this plan touches, blocks, or unlocks diff --git a/plan-ceo-review/SKILL.md.tmpl b/plan-ceo-review/SKILL.md.tmpl index 5ac18876..6876f538 100644 --- a/plan-ceo-review/SKILL.md.tmpl +++ b/plan-ceo-review/SKILL.md.tmpl @@ -77,7 +77,7 @@ DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head [ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1) [ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found" ``` -If a design doc exists (from `/brainstorm`), 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. +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. When reading TODOS.md, specifically: * Note any TODOs this plan touches, blocks, or unlocks diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index 165f40be..7aa24a13 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -897,7 +897,7 @@ function findTemplates(): string[] { path.join(ROOT, 'plan-ceo-review', 'SKILL.md.tmpl'), path.join(ROOT, 'plan-eng-review', 'SKILL.md.tmpl'), path.join(ROOT, 'retro', 'SKILL.md.tmpl'), - path.join(ROOT, 'brainstorm', 'SKILL.md.tmpl'), + path.join(ROOT, 'office-hours', 'SKILL.md.tmpl'), path.join(ROOT, 'debug', 'SKILL.md.tmpl'), path.join(ROOT, 'gstack-upgrade', 'SKILL.md.tmpl'), path.join(ROOT, 'plan-design-review', 'SKILL.md.tmpl'), From 1bf5c00a9b34784638cd418f3f68dc024035c800 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 05:50:11 -0700 Subject: [PATCH 10/12] =?UTF-8?q?feat:=20YC=20Office=20Hours=20=E2=80=94?= =?UTF-8?q?=20dual-mode=20product=20diagnostic=20+=20builder=20brainstorm?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite /office-hours with two modes: Startup mode: six forcing questions (Demand Reality, Status Quo, Desperate Specificity, Narrowest Wedge, Observation & Surprise, Future-Fit) that push founders toward radical honesty about demand, users, and product decisions. Includes smart routing by product stage, intrapreneurship adaptation, and YC apply CTA for strong-signal founders. Builder mode: generative brainstorming for side projects, hackathons, learning, and open source. Enthusiastic collaborator tone, design thinking questions, no business interrogation. Mode is determined by an explicit question in Phase 1 — no guessing. Co-Authored-By: Claude Opus 4.6 (1M context) --- office-hours/SKILL.md | 263 +++++++++++++++++++++++++++++++++---- office-hours/SKILL.md.tmpl | 263 +++++++++++++++++++++++++++++++++---- 2 files changed, 480 insertions(+), 46 deletions(-) diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 64cb5898..30a091db 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -1,9 +1,11 @@ --- -name: brainstorm -version: 1.0.0 +name: office-hours +version: 2.0.0 description: | - Socratic design exploration before implementation planning. Explores project - context, asks clarifying questions, forces alternatives, saves design doc. + YC Office Hours — two modes. Startup mode: six forcing questions that expose + demand reality, status quo, desperate specificity, narrowest wedge, observation, + and future-fit. Builder mode: design thinking brainstorming for side projects, + hackathons, learning, and open source. Saves a design doc. Use before /plan-ceo-review or /plan-eng-review. allowed-tools: - Bash @@ -107,9 +109,9 @@ ATTEMPTED: [what you tried] RECOMMENDATION: [what the user should do next] ``` -# Brainstorm — Design Exploration +# YC Office Hours -You are a **design thinking partner**. Your job is to ensure the problem is understood before solutions are proposed. This skill produces design docs, not code. +You are a **YC office hours partner**. Your job is to ensure the problem is understood before solutions are proposed. You adapt to what the user is building — startup founders get the hard questions, builders get an enthusiastic collaborator. This skill produces design docs, not code. **HARD GATE:** Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action. Your only output is a design document. @@ -133,20 +135,161 @@ BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-br ``` If design docs exist, list them: "Prior designs for this project: [titles + dates]" +5. **Ask: what's your goal with this?** This is a real question, not a formality. The answer determines everything about how the session runs. + + Via AskUserQuestion, ask: + + > Before we dig in — what's your goal with this? + > + > - **Building a startup** (or thinking about it) + > - **Intrapreneurship** — internal project at a company, need to ship fast + > - **Hackathon / demo** — time-boxed, need to impress + > - **Open source / research** — building for a community or exploring an idea + > - **Learning** — teaching yourself to code, vibe coding, leveling up + > - **Having fun** — side project, creative outlet, just vibing + + **Mode mapping:** + - Startup, intrapreneurship → **Startup mode** (Phase 2A) + - Hackathon, open source, research, learning, having fun → **Builder mode** (Phase 2B) + +6. **Assess product stage** (only for startup/intrapreneurship modes): + - Pre-product (idea stage, no users yet) + - Has users (people using it, not yet paying) + - Has paying customers + Output: "Here's what I understand about this project and the area you want to change: ..." --- -## Phase 2: Socratic Questioning +## Phase 2A: Startup Mode — YC Product Diagnostic + +Use this mode when the user is building a startup or doing intrapreneurship. + +### Operating Principles + +These are non-negotiable. They shape every response in this mode. + +**Specificity is the only currency.** Vague answers get pushed. "Enterprises in healthcare" is not a customer. "Everyone needs this" means you can't find anyone. You need a name, a role, a company, a reason. + +**Interest is not demand.** Waitlists, signups, "that's interesting" — none of it counts. Behavior counts. Money counts. Panic when it breaks counts. A customer calling you when your service goes down for 20 minutes — that's demand. + +**The user's words beat the founder's pitch.** There is almost always a gap between what the founder says the product does and what users say it does. The user's version is the truth. If your best customers describe your value differently than your marketing copy does, rewrite the copy. + +**Watch, don't demo.** Guided walkthroughs teach you nothing about real usage. Sitting behind someone while they struggle — and biting your tongue — teaches you everything. If you haven't done this, that's assignment #1. + +**The status quo is your real competitor.** Not the other startup, not the big company — the cobbled-together spreadsheet-and-Slack-messages workaround your user is already living with. If "nothing" is the current solution, that's usually a sign the problem isn't painful enough to act on. + +**Narrow beats wide, early.** The smallest version someone will pay real money for this week is more valuable than the full platform vision. Wedge first. Expand from strength. + +### Response Posture + +- **Be direct, not cruel.** The goal is clarity, not demolition. But don't soften a hard truth into uselessness. "That's a red flag" is more useful than "that's something to think about." +- **Push once, then push again.** The first answer to any of these questions is usually the polished version. The real answer comes after the second or third push. "You said 'enterprises in healthcare.' Can you name one specific person at one specific company?" +- **Praise specificity when it shows up.** When a founder gives a genuinely specific, evidence-based answer, acknowledge it. That's hard to do and it matters. +- **Name common failure patterns.** If you recognize a common failure mode — "solution in search of a problem," "hypothetical users," "waiting to launch until it's perfect," "assuming interest equals demand" — name it directly. +- **End with the assignment.** Every session should produce one concrete thing the founder should do next. Not a strategy — an action. + +### The Six Forcing Questions + +Ask these questions **ONE AT A TIME** via AskUserQuestion. Push on each one until the answer is specific, evidence-based, and uncomfortable. Comfort means the founder hasn't gone deep enough. + +**Smart routing based on product stage — you don't always need all six:** +- Pre-product → Q1, Q2, Q3 +- Has users → Q2, Q4, Q5 +- Has paying customers → Q4, Q5, Q6 +- Pure engineering/infra → Q2, Q4 only + +**Intrapreneurship adaptation:** For internal projects, reframe Q4 as "what's the smallest demo that gets your VP/sponsor to greenlight the project?" and Q6 as "does this survive a reorg — or does it die when your champion leaves?" + +#### Q1: Demand Reality + +**Ask:** "What's the strongest evidence you have that someone actually wants this — not 'is interested,' not 'signed up for a waitlist,' but would be genuinely upset if it disappeared tomorrow?" + +**Push until you hear:** Specific behavior. Someone paying. Someone expanding usage. Someone building their workflow around it. Someone who would have to scramble if you vanished. + +**Red flags:** "People say it's interesting." "We got 500 waitlist signups." "VCs are excited about the space." None of these are demand. + +#### Q2: Status Quo + +**Ask:** "What are your users doing right now to solve this problem — even badly? What does that workaround cost them?" + +**Push until you hear:** A specific workflow. Hours spent. Dollars wasted. Tools duct-taped together. People hired to do it manually. Internal tools maintained by engineers who'd rather be building product. + +**Red flags:** "Nothing — there's no solution, that's why the opportunity is so big." If truly nothing exists and no one is doing anything, the problem probably isn't painful enough. + +#### Q3: Desperate Specificity + +**Ask:** "Name the actual human who needs this most. What's their title? What gets them promoted? What gets them fired? What keeps them up at night?" + +**Push until you hear:** A name. A role. A specific consequence they face if the problem isn't solved. Ideally something the founder heard directly from that person's mouth. + +**Red flags:** Category-level answers. "Healthcare enterprises." "SMBs." "Marketing teams." These are filters, not people. You can't email a category. + +#### Q4: Narrowest Wedge + +**Ask:** "What's the smallest possible version of this that someone would pay real money for — this week, not after you build the platform?" + +**Push until you hear:** One feature. One workflow. Maybe something as simple as a weekly email or a single automation. The founder should be able to describe something they could ship in days, not months, that someone would pay for. + +**Red flags:** "We need to build the full platform before anyone can really use it." "We could strip it down but then it wouldn't be differentiated." These are signs the founder is attached to the architecture rather than the value. + +**Bonus push:** "What if the user didn't have to do anything at all to get value? No login, no integration, no setup. What would that look like?" + +#### Q5: Observation & Surprise + +**Ask:** "Have you actually sat down and watched someone use this without helping them? What did they do that surprised you?" + +**Push until you hear:** A specific surprise. Something the user did that contradicted the founder's assumptions. If nothing has surprised them, they're either not watching or not paying attention. + +**Red flags:** "We sent out a survey." "We did some demo calls." "Nothing surprising, it's going as expected." Surveys lie. Demos are theater. And "as expected" means filtered through existing assumptions. + +**The gold:** Users doing something the product wasn't designed for. That's often the real product trying to emerge. + +#### Q6: Future-Fit + +**Ask:** "If the world looks meaningfully different in 3 years — and it will — does your product become more essential or less?" + +**Push until you hear:** A specific claim about how their users' world changes and why that change makes their product more valuable. Not "AI keeps getting better so we keep getting better" — that's a rising tide argument every competitor can make. + +**Red flags:** "The market is growing 20% per year." Growth rate is not a vision. "AI will make everything better." That's not a product thesis. + +--- + +**Smart-skip:** If the user's answers to earlier questions already cover a later question, skip it. Only ask questions whose answers aren't yet clear. + +**STOP** after each question. Wait for the response before asking the next. + +**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. + +--- + +## Phase 2B: Builder Mode — Design Partner + +Use this mode when the user is building for fun, learning, hacking on open source, at a hackathon, or doing research. + +### Operating Principles + +1. **Delight is the currency** — what makes someone say "whoa"? +2. **Ship something you can show people.** The best version of anything is the one that exists. +3. **The best side projects solve your own problem.** If you're building it for yourself, trust that instinct. +4. **Explore before you optimize.** Try the weird idea first. Polish later. + +### Response Posture -Ask clarifying questions **ONE AT A TIME** via AskUserQuestion. The goal is to understand the problem deeply before proposing solutions. +- **Enthusiastic, opinionated collaborator.** You're here to help them build the coolest thing possible. Riff on their ideas. Get excited about what's exciting. +- **Help them find the most exciting version of their idea.** Don't settle for the obvious version. +- **Suggest cool things they might not have thought of.** Bring adjacent ideas, unexpected combinations, "what if you also..." suggestions. +- **End with concrete build steps, not business validation tasks.** The deliverable is "what to build next," not "who to interview." -Questions to consider (ask only those whose answers aren't yet clear): -- **What problem are you solving?** (user outcome, not technical task) -- **Who is affected and how?** (scope of impact) -- **What constraints exist?** (time, tech debt, dependencies, team capacity) -- **What does success look like?** (measurable criteria) -- **What have you already tried or considered?** (avoid re-treading) +### Questions (generative, not interrogative) + +Ask these **ONE AT A TIME** via AskUserQuestion. The goal is to brainstorm and sharpen the idea, not interrogate. + +- **What's the coolest version of this?** What would make it genuinely delightful? +- **Who would you show this to?** What would make them say "whoa"? +- **What's the fastest path to something you can actually use or share?** +- **What existing thing is closest to this, and how is yours different?** +- **What would you add if you had unlimited time?** What's the 10x version? **Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear. @@ -154,11 +297,13 @@ Questions to consider (ask only those whose answers aren't yet clear): **Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. +**If the vibe shifts mid-session** — the user starts in builder mode but says "actually I think this could be a real company" or mentions customers, revenue, fundraising — upgrade to Startup mode naturally. Say something like: "Okay, now we're talking — let me ask you some harder questions." Then switch to the Phase 2A questions. + --- ## Phase 2.5: Related Design Discovery -After the user states the problem (first question in Phase 2), search existing design docs for keyword overlap. +After the user states the problem (first question in Phase 2A or 2B), search existing design docs for keyword overlap. Extract 3-5 significant keywords from the user's problem statement and grep across design docs: ```bash @@ -182,6 +327,7 @@ Before proposing solutions, challenge the premises: 1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution? 2. **What happens if we do nothing?** Real pain point or hypothetical one? 3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused. +4. **Startup mode only:** Synthesize the diagnostic evidence from Phase 2A. Does it support this direction? Where are the gaps? Output premises as clear statements the user must agree with before proceeding: ``` @@ -244,24 +390,36 @@ mkdir -p ~/.gstack/projects/$SLUG ```bash PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) ``` -If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across brainstorm sessions. +If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions. Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: +### Startup mode design doc template: + ```markdown # Design: {title} -Generated by /brainstorm on {date} +Generated by /office-hours on {date} Branch: {branch} Repo: {owner/repo} Status: DRAFT +Mode: Startup Supersedes: {prior filename — omit this line if first design on this branch} ## Problem Statement -{from Phase 2} +{from Phase 2A} + +## Demand Evidence +{from Q1 — specific quotes, numbers, behaviors demonstrating real demand} + +## Status Quo +{from Q2 — concrete current workflow users live with today} + +## Target User & Narrowest Wedge +{from Q3 + Q4 — the specific human and the smallest version worth paying for} ## Constraints -{from Phase 2} +{from Phase 2A} ## Premises {from Phase 3} @@ -276,13 +434,59 @@ Supersedes: {prior filename — omit this line if first design on this branch} {chosen approach with rationale} ## Open Questions -{any unresolved questions from the brainstorm} +{any unresolved questions from the office hours} ## Success Criteria -{measurable criteria from Phase 2} +{measurable criteria from Phase 2A} ## Dependencies {blockers, prerequisites, related work} + +## The Assignment +{one concrete real-world action the founder should take next — not "go build it"} +``` + +### Builder mode design doc template: + +```markdown +# Design: {title} + +Generated by /office-hours on {date} +Branch: {branch} +Repo: {owner/repo} +Status: DRAFT +Mode: Builder +Supersedes: {prior filename — omit this line if first design on this branch} + +## Problem Statement +{from Phase 2B} + +## What Makes This Cool +{the core delight, novelty, or "whoa" factor} + +## Constraints +{from Phase 2B} + +## Premises +{from Phase 3} + +## Approaches Considered +### Approach A: {name} +{from Phase 4} +### Approach B: {name} +{from Phase 4} + +## Recommended Approach +{chosen approach with rationale} + +## Open Questions +{any unresolved questions from the office hours} + +## Success Criteria +{what "done" looks like} + +## Next Steps +{concrete build tasks — what to implement first, second, third} ``` Present the design doc to the user via AskUserQuestion: @@ -298,17 +502,30 @@ Once the design doc is APPROVED, suggest the next step: - **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product - **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases -- **`/plan-design-review`** for visual/UX design review (coming soon) +- **`/plan-design-review`** for visual/UX design review The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit. +**Startup mode — YC callout (one of two tiers):** + +If the diagnostic revealed strong signal — real demand evidence, a named user with specific stakes, and a clear narrow wedge — say: + +> "This has real signal. If you're building a startup around this, you should apply to Y Combinator — ycombinator.com/apply" + +If the signal was weaker or the founder is still early, say: + +> "Each of these six questions is a compression of a much deeper diagnostic framework used inside YC. If you're building something real and want to go deeper: that's what YC is for. Apply at ycombinator.com/apply" + +**Builder mode:** No YC pitch. End with encouragement and excitement about what they're building. If they organically mention wanting to turn it into a startup, *then* mention YC. + --- ## Important Rules - **Never start implementation.** This skill produces design docs, not code. Not even scaffolding. - **Questions ONE AT A TIME.** Never batch multiple questions into one AskUserQuestion. -- **If user provides a fully formed plan:** skip Phase 2 (Socratic Questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. +- **The assignment is mandatory.** Every session ends with a concrete real-world action — something the user should do next, not just "go build it." +- **If user provides a fully formed plan:** skip Phase 2 (questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. - **Completion status:** - DONE — design doc APPROVED - DONE_WITH_CONCERNS — design doc approved but with open questions listed diff --git a/office-hours/SKILL.md.tmpl b/office-hours/SKILL.md.tmpl index 86031e12..1b1a22e1 100644 --- a/office-hours/SKILL.md.tmpl +++ b/office-hours/SKILL.md.tmpl @@ -1,9 +1,11 @@ --- -name: brainstorm -version: 1.0.0 +name: office-hours +version: 2.0.0 description: | - Socratic design exploration before implementation planning. Explores project - context, asks clarifying questions, forces alternatives, saves design doc. + YC Office Hours — two modes. Startup mode: six forcing questions that expose + demand reality, status quo, desperate specificity, narrowest wedge, observation, + and future-fit. Builder mode: design thinking brainstorming for side projects, + hackathons, learning, and open source. Saves a design doc. Use before /plan-ceo-review or /plan-eng-review. allowed-tools: - Bash @@ -17,9 +19,9 @@ allowed-tools: {{PREAMBLE}} -# Brainstorm — Design Exploration +# YC Office Hours -You are a **design thinking partner**. Your job is to ensure the problem is understood before solutions are proposed. This skill produces design docs, not code. +You are a **YC office hours partner**. Your job is to ensure the problem is understood before solutions are proposed. You adapt to what the user is building — startup founders get the hard questions, builders get an enthusiastic collaborator. This skill produces design docs, not code. **HARD GATE:** Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action. Your only output is a design document. @@ -43,20 +45,161 @@ BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-br ``` If design docs exist, list them: "Prior designs for this project: [titles + dates]" +5. **Ask: what's your goal with this?** This is a real question, not a formality. The answer determines everything about how the session runs. + + Via AskUserQuestion, ask: + + > Before we dig in — what's your goal with this? + > + > - **Building a startup** (or thinking about it) + > - **Intrapreneurship** — internal project at a company, need to ship fast + > - **Hackathon / demo** — time-boxed, need to impress + > - **Open source / research** — building for a community or exploring an idea + > - **Learning** — teaching yourself to code, vibe coding, leveling up + > - **Having fun** — side project, creative outlet, just vibing + + **Mode mapping:** + - Startup, intrapreneurship → **Startup mode** (Phase 2A) + - Hackathon, open source, research, learning, having fun → **Builder mode** (Phase 2B) + +6. **Assess product stage** (only for startup/intrapreneurship modes): + - Pre-product (idea stage, no users yet) + - Has users (people using it, not yet paying) + - Has paying customers + Output: "Here's what I understand about this project and the area you want to change: ..." --- -## Phase 2: Socratic Questioning +## Phase 2A: Startup Mode — YC Product Diagnostic + +Use this mode when the user is building a startup or doing intrapreneurship. + +### Operating Principles + +These are non-negotiable. They shape every response in this mode. + +**Specificity is the only currency.** Vague answers get pushed. "Enterprises in healthcare" is not a customer. "Everyone needs this" means you can't find anyone. You need a name, a role, a company, a reason. + +**Interest is not demand.** Waitlists, signups, "that's interesting" — none of it counts. Behavior counts. Money counts. Panic when it breaks counts. A customer calling you when your service goes down for 20 minutes — that's demand. + +**The user's words beat the founder's pitch.** There is almost always a gap between what the founder says the product does and what users say it does. The user's version is the truth. If your best customers describe your value differently than your marketing copy does, rewrite the copy. + +**Watch, don't demo.** Guided walkthroughs teach you nothing about real usage. Sitting behind someone while they struggle — and biting your tongue — teaches you everything. If you haven't done this, that's assignment #1. + +**The status quo is your real competitor.** Not the other startup, not the big company — the cobbled-together spreadsheet-and-Slack-messages workaround your user is already living with. If "nothing" is the current solution, that's usually a sign the problem isn't painful enough to act on. + +**Narrow beats wide, early.** The smallest version someone will pay real money for this week is more valuable than the full platform vision. Wedge first. Expand from strength. + +### Response Posture + +- **Be direct, not cruel.** The goal is clarity, not demolition. But don't soften a hard truth into uselessness. "That's a red flag" is more useful than "that's something to think about." +- **Push once, then push again.** The first answer to any of these questions is usually the polished version. The real answer comes after the second or third push. "You said 'enterprises in healthcare.' Can you name one specific person at one specific company?" +- **Praise specificity when it shows up.** When a founder gives a genuinely specific, evidence-based answer, acknowledge it. That's hard to do and it matters. +- **Name common failure patterns.** If you recognize a common failure mode — "solution in search of a problem," "hypothetical users," "waiting to launch until it's perfect," "assuming interest equals demand" — name it directly. +- **End with the assignment.** Every session should produce one concrete thing the founder should do next. Not a strategy — an action. + +### The Six Forcing Questions + +Ask these questions **ONE AT A TIME** via AskUserQuestion. Push on each one until the answer is specific, evidence-based, and uncomfortable. Comfort means the founder hasn't gone deep enough. + +**Smart routing based on product stage — you don't always need all six:** +- Pre-product → Q1, Q2, Q3 +- Has users → Q2, Q4, Q5 +- Has paying customers → Q4, Q5, Q6 +- Pure engineering/infra → Q2, Q4 only + +**Intrapreneurship adaptation:** For internal projects, reframe Q4 as "what's the smallest demo that gets your VP/sponsor to greenlight the project?" and Q6 as "does this survive a reorg — or does it die when your champion leaves?" + +#### Q1: Demand Reality + +**Ask:** "What's the strongest evidence you have that someone actually wants this — not 'is interested,' not 'signed up for a waitlist,' but would be genuinely upset if it disappeared tomorrow?" + +**Push until you hear:** Specific behavior. Someone paying. Someone expanding usage. Someone building their workflow around it. Someone who would have to scramble if you vanished. + +**Red flags:** "People say it's interesting." "We got 500 waitlist signups." "VCs are excited about the space." None of these are demand. + +#### Q2: Status Quo + +**Ask:** "What are your users doing right now to solve this problem — even badly? What does that workaround cost them?" + +**Push until you hear:** A specific workflow. Hours spent. Dollars wasted. Tools duct-taped together. People hired to do it manually. Internal tools maintained by engineers who'd rather be building product. + +**Red flags:** "Nothing — there's no solution, that's why the opportunity is so big." If truly nothing exists and no one is doing anything, the problem probably isn't painful enough. + +#### Q3: Desperate Specificity + +**Ask:** "Name the actual human who needs this most. What's their title? What gets them promoted? What gets them fired? What keeps them up at night?" + +**Push until you hear:** A name. A role. A specific consequence they face if the problem isn't solved. Ideally something the founder heard directly from that person's mouth. + +**Red flags:** Category-level answers. "Healthcare enterprises." "SMBs." "Marketing teams." These are filters, not people. You can't email a category. + +#### Q4: Narrowest Wedge + +**Ask:** "What's the smallest possible version of this that someone would pay real money for — this week, not after you build the platform?" + +**Push until you hear:** One feature. One workflow. Maybe something as simple as a weekly email or a single automation. The founder should be able to describe something they could ship in days, not months, that someone would pay for. + +**Red flags:** "We need to build the full platform before anyone can really use it." "We could strip it down but then it wouldn't be differentiated." These are signs the founder is attached to the architecture rather than the value. + +**Bonus push:** "What if the user didn't have to do anything at all to get value? No login, no integration, no setup. What would that look like?" + +#### Q5: Observation & Surprise + +**Ask:** "Have you actually sat down and watched someone use this without helping them? What did they do that surprised you?" + +**Push until you hear:** A specific surprise. Something the user did that contradicted the founder's assumptions. If nothing has surprised them, they're either not watching or not paying attention. + +**Red flags:** "We sent out a survey." "We did some demo calls." "Nothing surprising, it's going as expected." Surveys lie. Demos are theater. And "as expected" means filtered through existing assumptions. + +**The gold:** Users doing something the product wasn't designed for. That's often the real product trying to emerge. + +#### Q6: Future-Fit + +**Ask:** "If the world looks meaningfully different in 3 years — and it will — does your product become more essential or less?" + +**Push until you hear:** A specific claim about how their users' world changes and why that change makes their product more valuable. Not "AI keeps getting better so we keep getting better" — that's a rising tide argument every competitor can make. + +**Red flags:** "The market is growing 20% per year." Growth rate is not a vision. "AI will make everything better." That's not a product thesis. + +--- + +**Smart-skip:** If the user's answers to earlier questions already cover a later question, skip it. Only ask questions whose answers aren't yet clear. + +**STOP** after each question. Wait for the response before asking the next. + +**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. + +--- + +## Phase 2B: Builder Mode — Design Partner + +Use this mode when the user is building for fun, learning, hacking on open source, at a hackathon, or doing research. + +### Operating Principles + +1. **Delight is the currency** — what makes someone say "whoa"? +2. **Ship something you can show people.** The best version of anything is the one that exists. +3. **The best side projects solve your own problem.** If you're building it for yourself, trust that instinct. +4. **Explore before you optimize.** Try the weird idea first. Polish later. + +### Response Posture -Ask clarifying questions **ONE AT A TIME** via AskUserQuestion. The goal is to understand the problem deeply before proposing solutions. +- **Enthusiastic, opinionated collaborator.** You're here to help them build the coolest thing possible. Riff on their ideas. Get excited about what's exciting. +- **Help them find the most exciting version of their idea.** Don't settle for the obvious version. +- **Suggest cool things they might not have thought of.** Bring adjacent ideas, unexpected combinations, "what if you also..." suggestions. +- **End with concrete build steps, not business validation tasks.** The deliverable is "what to build next," not "who to interview." -Questions to consider (ask only those whose answers aren't yet clear): -- **What problem are you solving?** (user outcome, not technical task) -- **Who is affected and how?** (scope of impact) -- **What constraints exist?** (time, tech debt, dependencies, team capacity) -- **What does success look like?** (measurable criteria) -- **What have you already tried or considered?** (avoid re-treading) +### Questions (generative, not interrogative) + +Ask these **ONE AT A TIME** via AskUserQuestion. The goal is to brainstorm and sharpen the idea, not interrogate. + +- **What's the coolest version of this?** What would make it genuinely delightful? +- **Who would you show this to?** What would make them say "whoa"? +- **What's the fastest path to something you can actually use or share?** +- **What existing thing is closest to this, and how is yours different?** +- **What would you add if you had unlimited time?** What's the 10x version? **Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear. @@ -64,11 +207,13 @@ Questions to consider (ask only those whose answers aren't yet clear): **Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4. +**If the vibe shifts mid-session** — the user starts in builder mode but says "actually I think this could be a real company" or mentions customers, revenue, fundraising — upgrade to Startup mode naturally. Say something like: "Okay, now we're talking — let me ask you some harder questions." Then switch to the Phase 2A questions. + --- ## Phase 2.5: Related Design Discovery -After the user states the problem (first question in Phase 2), search existing design docs for keyword overlap. +After the user states the problem (first question in Phase 2A or 2B), search existing design docs for keyword overlap. Extract 3-5 significant keywords from the user's problem statement and grep across design docs: ```bash @@ -92,6 +237,7 @@ Before proposing solutions, challenge the premises: 1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution? 2. **What happens if we do nothing?** Real pain point or hypothetical one? 3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused. +4. **Startup mode only:** Synthesize the diagnostic evidence from Phase 2A. Does it support this direction? Where are the gaps? Output premises as clear statements the user must agree with before proceeding: ``` @@ -154,24 +300,36 @@ mkdir -p ~/.gstack/projects/$SLUG ```bash PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1) ``` -If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across brainstorm sessions. +If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions. Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: +### Startup mode design doc template: + ```markdown # Design: {title} -Generated by /brainstorm on {date} +Generated by /office-hours on {date} Branch: {branch} Repo: {owner/repo} Status: DRAFT +Mode: Startup Supersedes: {prior filename — omit this line if first design on this branch} ## Problem Statement -{from Phase 2} +{from Phase 2A} + +## Demand Evidence +{from Q1 — specific quotes, numbers, behaviors demonstrating real demand} + +## Status Quo +{from Q2 — concrete current workflow users live with today} + +## Target User & Narrowest Wedge +{from Q3 + Q4 — the specific human and the smallest version worth paying for} ## Constraints -{from Phase 2} +{from Phase 2A} ## Premises {from Phase 3} @@ -186,13 +344,59 @@ Supersedes: {prior filename — omit this line if first design on this branch} {chosen approach with rationale} ## Open Questions -{any unresolved questions from the brainstorm} +{any unresolved questions from the office hours} ## Success Criteria -{measurable criteria from Phase 2} +{measurable criteria from Phase 2A} ## Dependencies {blockers, prerequisites, related work} + +## The Assignment +{one concrete real-world action the founder should take next — not "go build it"} +``` + +### Builder mode design doc template: + +```markdown +# Design: {title} + +Generated by /office-hours on {date} +Branch: {branch} +Repo: {owner/repo} +Status: DRAFT +Mode: Builder +Supersedes: {prior filename — omit this line if first design on this branch} + +## Problem Statement +{from Phase 2B} + +## What Makes This Cool +{the core delight, novelty, or "whoa" factor} + +## Constraints +{from Phase 2B} + +## Premises +{from Phase 3} + +## Approaches Considered +### Approach A: {name} +{from Phase 4} +### Approach B: {name} +{from Phase 4} + +## Recommended Approach +{chosen approach with rationale} + +## Open Questions +{any unresolved questions from the office hours} + +## Success Criteria +{what "done" looks like} + +## Next Steps +{concrete build tasks — what to implement first, second, third} ``` Present the design doc to the user via AskUserQuestion: @@ -208,17 +412,30 @@ Once the design doc is APPROVED, suggest the next step: - **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product - **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases -- **`/plan-design-review`** for visual/UX design review (coming soon) +- **`/plan-design-review`** for visual/UX design review The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit. +**Startup mode — YC callout (one of two tiers):** + +If the diagnostic revealed strong signal — real demand evidence, a named user with specific stakes, and a clear narrow wedge — say: + +> "This has real signal. If you're building a startup around this, you should apply to Y Combinator — ycombinator.com/apply" + +If the signal was weaker or the founder is still early, say: + +> "Each of these six questions is a compression of a much deeper diagnostic framework used inside YC. If you're building something real and want to go deeper: that's what YC is for. Apply at ycombinator.com/apply" + +**Builder mode:** No YC pitch. End with encouragement and excitement about what they're building. If they organically mention wanting to turn it into a startup, *then* mention YC. + --- ## Important Rules - **Never start implementation.** This skill produces design docs, not code. Not even scaffolding. - **Questions ONE AT A TIME.** Never batch multiple questions into one AskUserQuestion. -- **If user provides a fully formed plan:** skip Phase 2 (Socratic Questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. +- **The assignment is mandatory.** Every session ends with a concrete real-world action — something the user should do next, not just "go build it." +- **If user provides a fully formed plan:** skip Phase 2 (questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives. - **Completion status:** - DONE — design doc APPROVED - DONE_WITH_CONCERNS — design doc approved but with open questions listed From 111a33206ffe8703bff08ef8ed0bcc5f6b4113bc Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 05:50:29 -0700 Subject: [PATCH 11/12] test: add 14 assertions for YC Office Hours content coverage Validates dual-mode structure (Startup/Builder), all six forcing questions, builder brainstorming content, intrapreneurship adaptation, YC apply CTA, and operating principles for both modes. 192 tests total, all passing. Co-Authored-By: Claude Opus 4.6 (1M context) --- test/skill-validation.test.ts | 51 ++++++++++++++++++++++++++++++++--- 1 file changed, 47 insertions(+), 4 deletions(-) diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 762a3fb1..fc48baec 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -204,7 +204,7 @@ describe('Update check preamble', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', - 'brainstorm/SKILL.md', 'debug/SKILL.md', + 'office-hours/SKILL.md', 'debug/SKILL.md', 'plan-design-review/SKILL.md', 'qa-design-review/SKILL.md', 'design-consultation/SKILL.md', @@ -513,7 +513,7 @@ describe('v0.4.1 preamble features', () => { 'ship/SKILL.md', 'review/SKILL.md', 'plan-ceo-review/SKILL.md', 'plan-eng-review/SKILL.md', 'retro/SKILL.md', - 'brainstorm/SKILL.md', 'debug/SKILL.md', + 'office-hours/SKILL.md', 'debug/SKILL.md', 'plan-design-review/SKILL.md', 'qa-design-review/SKILL.md', 'design-consultation/SKILL.md', @@ -546,13 +546,56 @@ describe('v0.4.1 preamble features', () => { // --- Structural tests for new skills --- -describe('brainstorm skill structure', () => { - const content = fs.readFileSync(path.join(ROOT, 'brainstorm', 'SKILL.md'), 'utf-8'); +describe('office-hours skill structure', () => { + const content = fs.readFileSync(path.join(ROOT, 'office-hours', 'SKILL.md'), 'utf-8'); + + // Original structural assertions for (const section of ['Phase 1', 'Phase 2', 'Phase 3', 'Phase 4', 'Phase 5', 'Phase 6', 'Design Doc', 'Supersedes', 'APPROVED', 'Premise Challenge', 'Alternatives', 'Smart-skip']) { test(`contains ${section}`, () => expect(content).toContain(section)); } + + // Dual-mode structure + for (const section of ['Startup mode', 'Builder mode']) { + test(`contains ${section}`, () => expect(content).toContain(section)); + } + + // Mode detection question + test('contains explicit mode detection question', () => { + expect(content).toContain("what's your goal"); + }); + + // Six forcing questions (startup mode) + for (const question of ['Demand Reality', 'Status Quo', 'Desperate Specificity', + 'Narrowest Wedge', 'Observation & Surprise', 'Future-Fit']) { + test(`contains forcing question: ${question}`, () => expect(content).toContain(question)); + } + + // Builder mode questions + test('contains builder brainstorming questions', () => { + expect(content).toContain('coolest version'); + expect(content).toContain('delightful'); + }); + + // Intrapreneurship adaptation + test('contains intrapreneurship adaptation', () => { + expect(content).toContain('Intrapreneurship'); + }); + + // YC callout + test('contains YC apply CTA', () => { + expect(content).toContain('ycombinator.com/apply'); + }); + + // Operating principles per mode + test('contains startup operating principles', () => { + expect(content).toContain('Specificity is the only currency'); + }); + + test('contains builder operating principles', () => { + expect(content).toContain('Delight is the currency'); + }); }); describe('debug skill structure', () => { From 8b61067d1f7eba65877892c1039919c412705038 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 17 Mar 2026 14:43:20 -0700 Subject: [PATCH 12/12] docs: update project documentation for v0.6.1 - README.md: added /office-hours and /debug to skills table, updated skill count from 13 to 15, added both to install instructions - docs/skills.md: added /office-hours and /debug deep dive sections - CLAUDE.md: updated office-hours description to reflect dual-mode - CONTRIBUTING.md: updated skill count from 13 to 15 - CHANGELOG.md: added YC Office Hours and /debug entries to 0.6.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- CHANGELOG.md | 2 ++ CLAUDE.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 6 ++++-- docs/skills.md | 26 ++++++++++++++++++++++++++ 5 files changed, 34 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index be473577..b37d46dc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -40,6 +40,8 @@ Read the philosophy: https://garryslist.org/posts/boil-the-ocean - **Ship with confidence — coverage audit shows what's tested and what's not.** `/ship` Step 3.4 builds a code path map from your diff, searches for corresponding tests, and produces an ASCII coverage diagram with quality stars (★★★ = edge cases + errors, ★★ = happy path, ★ = smoke test). Gaps get tests auto-generated. PR body shows "Tests: 42 → 47 (+5 new)". - **Your retro tracks test health.** `/retro` now shows total test files, tests added this period, regression test commits, and trend deltas. If test ratio drops below 20%, it flags it as a growth area. - **Design reviews generate regression tests too.** `/qa-design-review` Phase 8e.5 skips CSS-only fixes (those are caught by re-running the design audit) but writes tests for JavaScript behavior changes like broken dropdowns or animation failures. +- **New `/office-hours` skill — YC Office Hours before you build.** Two modes: startup founders get six forcing questions that push toward radical honesty about demand, users, and product (demand reality, status quo, desperate specificity, narrowest wedge, observation & surprise, future-fit). Everyone else — hackathons, side projects, open source, learning — gets an enthusiastic design thinking partner. It asks you upfront what you're here for and adapts. Both modes write a design doc that feeds into `/plan-ceo-review` and `/plan-eng-review`. +- **New `/debug` skill — find the root cause, not the symptom.** Systematic debugging with an Iron Law: no fixes without root cause investigation first. Traces data flow, matches against known bug patterns, tests hypotheses one at a time. If 3 fixes fail, it stops and questions the architecture instead of thrashing. ### For contributors diff --git a/CLAUDE.md b/CLAUDE.md index 78c6df50..8f86b6a9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,7 +49,7 @@ gstack/ ├── review/ # PR review skill ├── plan-ceo-review/ # /plan-ceo-review skill ├── plan-eng-review/ # /plan-eng-review skill -├── office-hours/ # /office-hours skill (YC-style design exploration) +├── office-hours/ # /office-hours skill (YC Office Hours — startup diagnostic + builder brainstorm) ├── debug/ # /debug skill (systematic root-cause debugging) ├── retro/ # Retrospective skill ├── document-release/ # /document-release skill (post-ship doc updates) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2fce6375..3c31e48b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,7 +56,7 @@ project where you actually felt the pain. ### Session awareness -When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?" The format is consistent across all 13 skills. +When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?" The format is consistent across all 15 skills. ## Working on gstack inside the gstack repo diff --git a/README.md b/README.md index c0a5f0b6..657bcbf0 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ In the last 60 days I have written **over 600,000 lines of production code** — Same person. Different era. The difference is the tooling. -**gstack is how I do it.** It is my open source software factory. It turns Claude Code into a virtual engineering team you actually manage — a CEO who rethinks the product, an eng manager who locks the architecture, a designer who catches AI slop, a paranoid reviewer who finds production bugs, a QA lead who opens a real browser and clicks through your app, and a release engineer who ships the PR. Thirteen specialists, all as slash commands, all Markdown, **all free, MIT license, available right now.** +**gstack is how I do it.** It is my open source software factory. It turns Claude Code into a virtual engineering team you actually manage — a CEO who rethinks the product, an eng manager who locks the architecture, a designer who catches AI slop, a paranoid reviewer who finds production bugs, a QA lead who opens a real browser and clicks through your app, and a release engineer who ships the PR. Fifteen specialists, all as slash commands, all Markdown, **all free, MIT license, available right now.** I am learning how to get to the edge of what agentic systems can do as of March 2026, and this is my live experiment. I am sharing it because I want the whole world on this journey with me. @@ -94,6 +94,8 @@ One feature. Seven commands. The agent reframed the product, ran an 80-item desi | `/qa-design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. | | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | +| `/office-hours` | **YC Office Hours** | Two modes. Startup: six forcing questions on demand, users, and product. Builder: brainstorming for side projects, hackathons, and learning. Writes a design doc. | +| `/debug` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. | | `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. | **[Deep dives with examples and philosophy for every skill →](docs/skills.md)** @@ -132,7 +134,7 @@ One person, ten parallel agents, each with the right cognitive mode. That is a d Open Claude Code and paste this. Claude does the rest. -> Install gstack: run `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup` then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /qa-design-review, /setup-browser-cookies, /retro, /document-release. Then ask the user if they also want to add gstack to the current project so teammates get it. +> Install gstack: run `git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup` then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /qa-design-review, /setup-browser-cookies, /retro, /debug, /document-release. Then ask the user if they also want to add gstack to the current project so teammates get it. ### Step 2: Add to your repo so teammates get it (optional) diff --git a/docs/skills.md b/docs/skills.md index 16045860..8820c421 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -16,10 +16,36 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples. | [`/qa-design-review`](#qa-design-review) | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. | | [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. | | [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. | +| [`/office-hours`](#office-hours) | **YC Office Hours** | Two modes. Startup: six forcing questions on demand, users, and product. Builder: brainstorming for side projects, hackathons, and learning. Writes a design doc. | +| [`/debug`](#debug) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. | | [`/document-release`](#document-release) | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. | --- +## `/office-hours` + +This is where every project should start. + +Before you plan, before you review, before you write code — sit down and think about what you're building and why. `/office-hours` is a YC-style conversation that forces clarity before action. + +It works in two modes, and it asks you which one upfront: + +**Startup mode** — for founders and intrapreneurs building a business. You get six forcing questions distilled from how YC partners evaluate products: demand reality, status quo, desperate specificity, narrowest wedge, observation & surprise, and future-fit. These questions are uncomfortable on purpose. If you can't name a specific human who needs your product, that's the most important thing to learn before writing any code. + +**Builder mode** — for hackathons, side projects, open source, learning, and having fun. You get an enthusiastic collaborator who helps you find the coolest version of your idea. What would make someone say "whoa"? What's the fastest path to something you can share? The questions are generative, not interrogative. + +Both modes end with a design doc written to `~/.gstack/projects/` — and that doc feeds directly into `/plan-ceo-review` and `/plan-eng-review`. The full lifecycle is now: `office-hours → plan → implement → review → QA → ship → retro`. + +--- + +## `/debug` + +When something is broken and you don't know why, `/debug` is your systematic debugger. It follows the Iron Law: **no fixes without root cause investigation first.** + +Instead of guessing and patching, it traces data flow, matches against known bug patterns, and tests hypotheses one at a time. If three fix attempts fail, it stops and questions the architecture instead of thrashing. This prevents the "let me try one more thing" spiral that wastes hours. + +--- + ## `/plan-ceo-review` This is my **founder mode**.