From 6cf424fb4907a3e2dea3ebd68308af5dbe94c858 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 10:09:32 -0500 Subject: [PATCH 1/8] =?UTF-8?q?feat:=20add=20escalation=20protocol=20to=20?= =?UTF-8?q?preamble=20=E2=80=94=20all=20skills=20get=20DONE/BLOCKED/NEEDS?= =?UTF-8?q?=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 b362e82..67bb6a4 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 28e976d..22e464b 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 438b782..fb4d89e 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 c11f8a6..7a98235 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 28280c9..1ff5cb1 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 bafed64..45ca4fb 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 0623024..3d9cfcd 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 2/8] =?UTF-8?q?feat:=20add=20verification=20gate=20to=20/s?= =?UTF-8?q?hip=20(Step=206.5)=20=E2=80=94=20no=20push=20without=20fresh=20?= =?UTF-8?q?evidence?= 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 e023816..14d3aa1 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 06ff5a0..9c1b164 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 3/8] 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 32c597a..c05e68a 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 124a539..14afe6f 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 4/8] 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 c82753a..c3c9428 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 ef14a28..400fb57 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 5/8] 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 819ef07..b993483 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 410b072..57bca4c 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 6/8] 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 0000000..02992bb --- /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 0000000..86031e1 --- /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 0000000..23a6ba5 --- /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 0000000..312d242 --- /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 7/8] 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 e724b82..d0bddfb 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 7bd1176..eb8c95f 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 88e9893..bdec781 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 8/8] 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 57c2c1a..ded48ad 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 267577d..a918a2a 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.4.1 +0.6.0