From ac9b1d8c85f81950a7096b0195884d8df5e2e281 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Wed, 18 Mar 2026 21:33:09 -0700 Subject: [PATCH] feat: /debug auto-freezes edits to the module being debugged Add PreToolUse hooks (Edit/Write) to debug/SKILL.md.tmpl that reference the existing freeze/bin/check-freeze.sh. After Phase 1 investigation, /debug locks edits to the narrowest affected directory. Graceful degradation: if freeze script is unavailable, scope lock is skipped. Users can run /unfreeze to remove the restriction. Deferred 6 enhancements to TODOS.md, gated on telemetry showing the freeze hook actually fires in real debugging sessions. Co-Authored-By: Claude Opus 4.6 (1M context) --- TODOS.md | 20 ++++++++++++++++++++ debug/SKILL.md | 37 +++++++++++++++++++++++++++++++++++++ debug/SKILL.md.tmpl | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 94 insertions(+) diff --git a/TODOS.md b/TODOS.md index 2e7c4629..bb85a56d 100644 --- a/TODOS.md +++ b/TODOS.md @@ -518,6 +518,26 @@ Shipped as `/careful`, `/freeze`, `/guard`, and `/unfreeze` in v0.6.5. Includes Shipped in v0.6.5. TemplateContext in gen-skill-docs.ts bakes skill name into preamble telemetry line. Analytics CLI (`bun run analytics`) for querying. /retro integration shows skills-used-this-week. +### /debug scoped debugging enhancements (gated on telemetry) + +**What:** Six enhancements to /debug auto-freeze, contingent on telemetry showing the freeze hook actually fires in real debugging sessions. + +**Why:** /debug v0.7.1 auto-freezes edits to the module being debugged. If telemetry shows the hook fires often, these enhancements make the experience smarter. If it never fires, the problem wasn't real and these aren't worth building. + +**Context:** All items are prose additions to `debug/SKILL.md.tmpl`. No new scripts. + +**Items:** +1. Stack trace auto-detection for freeze directory (parse deepest app frame) +2. Freeze boundary widening (ask to widen instead of hard-block when hitting boundary) +3. Post-fix auto-unfreeze + full test suite run +4. Debug instrumentation cleanup (tag with DEBUG-TEMP, remove before commit) +5. Debug session persistence (~/.gstack/debug-sessions/ — save investigation for reuse) +6. Investigation timeline in debug report (hypothesis log with timing) + +**Effort:** M (all 6 combined) +**Priority:** P3 +**Depends on:** Telemetry data showing freeze hook fires in real /debug sessions + ## Completed ### Phase 1: Foundations (v0.2.0) diff --git a/debug/SKILL.md b/debug/SKILL.md index a2808749..99b80223 100644 --- a/debug/SKILL.md +++ b/debug/SKILL.md @@ -12,6 +12,18 @@ allowed-tools: - Grep - Glob - AskUserQuestion +hooks: + PreToolUse: + - matcher: "Edit" + hooks: + - type: command + command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" + statusMessage: "Checking debug scope boundary..." + - matcher: "Write" + hooks: + - type: command + command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" + statusMessage: "Checking debug scope boundary..." --- @@ -177,6 +189,31 @@ Output: **"Root cause hypothesis: ..."** — a specific, testable claim about wh --- +## Scope Lock + +After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep. + +```bash +[ -x "${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE" +``` + +**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file: + +```bash +STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}" +mkdir -p "$STATE_DIR" +echo "/" > "$STATE_DIR/freeze-dir.txt" +echo "Debug scope locked to: /" +``` + +Substitute `` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction." + +If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why. + +**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted. + +--- + ## Phase 2: Pattern Analysis Check if this bug matches a known pattern: diff --git a/debug/SKILL.md.tmpl b/debug/SKILL.md.tmpl index 312d2420..4ef8c719 100644 --- a/debug/SKILL.md.tmpl +++ b/debug/SKILL.md.tmpl @@ -12,6 +12,18 @@ allowed-tools: - Grep - Glob - AskUserQuestion +hooks: + PreToolUse: + - matcher: "Edit" + hooks: + - type: command + command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" + statusMessage: "Checking debug scope boundary..." + - matcher: "Write" + hooks: + - type: command + command: "bash ${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" + statusMessage: "Checking debug scope boundary..." --- {{PREAMBLE}} @@ -46,6 +58,31 @@ Output: **"Root cause hypothesis: ..."** — a specific, testable claim about wh --- +## Scope Lock + +After forming your root cause hypothesis, lock edits to the affected module to prevent scope creep. + +```bash +[ -x "${CLAUDE_SKILL_DIR}/../freeze/bin/check-freeze.sh" ] && echo "FREEZE_AVAILABLE" || echo "FREEZE_UNAVAILABLE" +``` + +**If FREEZE_AVAILABLE:** Identify the narrowest directory containing the affected files. Write it to the freeze state file: + +```bash +STATE_DIR="${CLAUDE_PLUGIN_DATA:-$HOME/.gstack}" +mkdir -p "$STATE_DIR" +echo "/" > "$STATE_DIR/freeze-dir.txt" +echo "Debug scope locked to: /" +``` + +Substitute `` with the actual directory path (e.g., `src/auth/`). Tell the user: "Edits restricted to `/` for this debug session. This prevents changes to unrelated code. Run `/unfreeze` to remove the restriction." + +If the bug spans the entire repo or the scope is genuinely unclear, skip the lock and note why. + +**If FREEZE_UNAVAILABLE:** Skip scope lock. Edits are unrestricted. + +--- + ## Phase 2: Pattern Analysis Check if this bug matches a known pattern: