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