gsd-antigravity-kit 2.0.0 → 2.1.0

package/.agent/skills/gsd/references/docs/artifact-types.md

@@ -72,6 +72,24 @@ reads is inert — the consumption mechanism is what gives an artifact meaning.
 - **Location**: `.planning/spikes/SPIKE-NNN/`
 - **Consumed by**: Planner when spike is referenced; `pause-work` for spike context handoff
 
+### Spike README.md / MANIFEST.md (per-spike, via /gsd-spike)
+- **Shape**: YAML frontmatter (spike, name, validates, verdict, related, tags) + run instructions + results
+- **Lifecycle**: Created by `/gsd-spike` → Verified → Wrapped up by `/gsd-spike-wrap-up`
+- **Location**: `.planning/spikes/NNN-name/README.md`, `.planning/spikes/MANIFEST.md`
+- **Consumed by**: `/gsd-spike-wrap-up` for curation; `pause-work` for spike context handoff
+
+### Sketch README.md / MANIFEST.md / index.html (per-sketch)
+- **Shape**: YAML frontmatter (sketch, name, question, winner, tags) + variants as tabbed HTML
+- **Lifecycle**: Created by `/gsd-sketch` → Evaluated → Wrapped up by `/gsd-sketch-wrap-up`
+- **Location**: `.planning/sketches/NNN-name/README.md`, `.planning/sketches/NNN-name/index.html`, `.planning/sketches/MANIFEST.md`
+- **Consumed by**: `/gsd-sketch-wrap-up` for curation; `pause-work` for sketch context handoff
+
+### WRAP-UP-SUMMARY.md (per wrap-up session)
+- **Shape**: Curation results, included/excluded items, feature/design area groupings
+- **Lifecycle**: Created by `/gsd-spike-wrap-up` or `/gsd-sketch-wrap-up`
+- **Location**: `.planning/spikes/WRAP-UP-SUMMARY.md` or `.planning/sketches/WRAP-UP-SUMMARY.md`
+- **Consumed by**: Project history; not read by automated workflows
+
 ---
 
 ## Standing Reference Artifacts

package/.agent/skills/gsd/references/docs/autonomous-smart-discuss.md

@@ -0,0 +1,277 @@
+# Smart Discuss — Autonomous Mode
+
+Smart discuss is the autonomous-optimized variant of `gsd-discuss-phase`. It proposes grey area answers in batch tables — the user accepts or overrides per area — then writes an identical CONTEXT.md to what discuss-phase produces.
+
+**Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
+
+```bash
+PHASE_STATE=$(gsd-sdk query init.phase-op ${PHASE_NUM})
+```
+
+Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.
+
+---
+
+## Sub-step 1: Load prior context
+
+Read project-level and prior phase context to avoid re-asking decided questions.
+
+**Read project files:**
+
+```bash
+cat .planning/PROJECT.md 2>/dev/null || true
+cat .planning/REQUIREMENTS.md 2>/dev/null || true
+cat .planning/STATE.md 2>/dev/null || true
+```
+
+Extract from these:
+- **PROJECT.md** — Vision, principles, non-negotiables, user preferences
+- **REQUIREMENTS.md** — Acceptance criteria, constraints, must-haves vs nice-to-haves
+- **STATE.md** — Current progress, decisions logged so far
+
+**Read all prior CONTEXT.md files:**
+
+```bash
+(find .planning/phases -name "*-CONTEXT.md" 2>/dev/null || true) | sort
+```
+
+For each CONTEXT.md where phase number < current phase:
+- Read the `<decisions>` section — these are locked preferences
+- Read `<specifics>` — particular references or "I want it like X" moments
+- Note patterns (e.g., "user consistently prefers minimal UI", "user rejected verbose output")
+
+**Build internal prior_decisions context** (do not write to file):
+
+```
+<prior_decisions>
+## Project-Level
+- [Key principle or constraint from PROJECT.md]
+- [Requirement affecting this phase from REQUIREMENTS.md]
+
+## From Prior Phases
+### Phase N: [Name]
+- [Decision relevant to current phase]
+- [Preference that establishes a pattern]
+</prior_decisions>
+```
+
+If no prior context exists, continue without — expected for early phases.
+
+---
+
+## Sub-step 2: Scout Codebase
+
+Lightweight codebase scan to inform grey area identification and proposals. Keep under ~5% context.
+
+**Check for existing codebase maps:**
+
+```bash
+ls .planning/codebase/*.md 2>/dev/null || true
+```
+
+**If codebase maps exist:** Read the most relevant ones (CONVENTIONS.md, STRUCTURE.md, STACK.md based on phase type). Extract reusable components, established patterns, integration points. Skip to building context below.
+
+**If no codebase maps, do targeted grep:**
+
+Extract key terms from the phase goal. Search for related files:
+
+```bash
+grep -rl "{term1}\|{term2}" src/ app/ --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" 2>/dev/null | head -10 || true
+ls src/components/ src/hooks/ src/lib/ src/utils/ 2>/dev/null || true
+```
+
+Read the 3-5 most relevant files to understand existing patterns.
+
+**Build internal codebase_context** (do not write to file):
+- **Reusable assets** — existing components, hooks, utilities usable in this phase
+- **Established patterns** — how the codebase does state management, styling, data fetching
+- **Integration points** — where new code connects (routes, nav, providers)
+
+---
+
+## Sub-step 3: Analyze Phase and Generate Proposals
+
+**Get phase details:**
+
+```bash
+DETAIL=$(gsd-sdk query roadmap.get-phase ${PHASE_NUM})
+```
+
+Extract `goal`, `requirements`, `success_criteria` from the JSON response.
+
+**Infrastructure detection — check FIRST before generating grey areas:**
+
+A phase is pure infrastructure when ALL of these are true:
+1. Goal keywords match: "scaffolding", "plumbing", "setup", "configuration", "migration", "refactor", "rename", "restructure", "upgrade", "infrastructure"
+2. AND success criteria are all technical: "file exists", "test passes", "config valid", "command runs"
+3. AND no user-facing behavior is described (no "users can", "displays", "shows", "presents")
+
+**If infrastructure-only:** Skip Sub-step 4. Jump directly to Sub-step 5 with minimal CONTEXT.md. Display:
+
+```
+Phase ${PHASE_NUM}: Infrastructure phase — skipping discuss, writing minimal context.
+```
+
+Use these defaults for the CONTEXT.md:
+- `<domain>`: Phase boundary from ROADMAP goal
+- `<decisions>`: Single "### Antigravity's Discretion" subsection — "All implementation choices are at Antigravity's discretion — pure infrastructure phase"
+- `<code_context>`: Whatever the codebase scout found
+- `<specifics>`: "No specific requirements — infrastructure phase"
+- `<deferred>`: "None"
+
+**If NOT infrastructure — generate grey area proposals:**
+
+Determine domain type from the phase goal:
+- Something users **SEE** → visual: layout, interactions, states, density
+- Something users **CALL** → interface: contracts, responses, errors, auth
+- Something users **RUN** → execution: invocation, output, behavior modes, flags
+- Something users **READ** → content: structure, tone, depth, flow
+- Something being **ORGANIZED** → organization: criteria, grouping, exceptions, naming
+
+Check prior_decisions — skip grey areas already decided in prior phases.
+
+Generate **3-4 grey areas** with **~4 questions each**. For each question:
+- **Pre-select a recommended answer** based on: prior decisions (consistency), codebase patterns (reuse), domain conventions (standard approaches), ROADMAP success criteria
+- Generate **1-2 alternatives** per question
+- **Annotate** with prior decision context ("You decided X in Phase N") and code context ("Component Y exists with Z variants") where relevant
+
+---
+
+## Sub-step 4: Present Proposals Per Area
+
+Present grey areas **one at a time**. For each area (M of N):
+
+Display a table:
+
+```
+### Grey Area {M}/{N}: {Area Name}
+
+| # | Question | ✅ Recommended | Alternative(s) |
+|---|----------|---------------|-----------------|
+| 1 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
+| 2 | {question} | {answer} — {rationale} | {alt1} |
+| 3 | {question} | {answer} — {rationale} | {alt1}; {alt2} |
+| 4 | {question} | {answer} — {rationale} | {alt1} |
+```
+
+Then prompt the user via **AskUserQuestion**:
+- **header:** "Area {M}/{N}"
+- **question:** "Accept these answers for {Area Name}?"
+- **options:** Build dynamically — always "Accept all" first, then "Change Q1" through "Change QN" for each question (up to 4), then "Discuss deeper" last. Cap at 6 explicit options max (AskUserQuestion adds "Other" automatically).
+
+**On "Accept all":** Record all recommended answers for this area. Move to next area.
+
+**On "Change QN":** Use AskUserQuestion with the alternatives for that specific question:
+- **header:** "{Area Name}"
+- **question:** "Q{N}: {question text}"
+- **options:** List the 1-2 alternatives plus "You decide" (maps to Antigravity's Discretion)
+
+Record the user's choice. Re-display the updated table with the change reflected. Re-present the full acceptance prompt so the user can make additional changes or accept.
+
+**On "Discuss deeper":** Switch to interactive mode for this area only — ask questions one at a time using AskUserQuestion with 2-3 concrete options per question plus "You decide". After 4 questions, prompt:
+- **header:** "{Area Name}"
+- **question:** "More questions about {area name}, or move to next?"
+- **options:** "More questions" / "Next area"
+
+If "More questions", ask 4 more. If "Next area", display final summary table of captured answers for this area and move on.
+
+**On "Other" (free text):** Interpret as either a specific change request or general feedback. Incorporate into the area's decisions, re-display updated table, re-present acceptance prompt.
+
+**Scope creep handling:** If user mentions something outside the phase domain:
+
+```
+"{Feature} sounds like a new capability — that belongs in its own phase.
+I'll note it as a deferred idea.
+
+Back to {current area}: {return to current question}"
+```
+
+Track deferred ideas internally for inclusion in CONTEXT.md.
+
+---
+
+## Sub-step 5: Write CONTEXT.md
+
+After all areas are resolved (or infrastructure skip), write the CONTEXT.md file.
+
+**File path:** `${phase_dir}/${padded_phase}-CONTEXT.md`
+
+Use **exactly** this structure (identical to discuss-phase output):
+
+```markdown
+# Phase {PHASE_NUM}: {Phase Name} - Context
+
+**Gathered:** {date}
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+{Domain boundary statement from analysis — what this phase delivers}
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### {Area 1 Name}
+- {Accepted/chosen answer for Q1}
+- {Accepted/chosen answer for Q2}
+- {Accepted/chosen answer for Q3}
+- {Accepted/chosen answer for Q4}
+
+### {Area 2 Name}
+- {Accepted/chosen answer for Q1}
+- {Accepted/chosen answer for Q2}
+...
+
+### Antigravity's Discretion
+{Any "You decide" answers collected — note Antigravity has flexibility here}
+
+</decisions>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- {From codebase scout — components, hooks, utilities}
+
+### Established Patterns
+- {From codebase scout — state management, styling, data fetching}
+
+### Integration Points
+- {From codebase scout — where new code connects}
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+{Any specific references or "I want it like X" from discussion}
+{If none: "No specific requirements — open to standard approaches"}
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+{Ideas captured but out of scope for this phase}
+{If none: "None — discussion stayed within phase scope"}
+
+</deferred>
+```
+
+Write the file.
+
+**Commit:**
+
+```bash
+gsd-sdk query commit "docs(${PADDED_PHASE}): smart discuss context" "${phase_dir}/${padded_phase}-CONTEXT.md"
+```
+
+Display confirmation:
+
+```
+Created: {path}
+Decisions captured: {count} across {area_count} areas
+```

package/.agent/skills/gsd/references/docs/checkpoints.md

@@ -759,6 +759,36 @@ timeout 30 bash -c 'until node -e "fetch(\"http://localhost:3000\").then(r=>{pro
 
 </anti_patterns>
 
+<type name="tdd-review">
+## checkpoint:tdd-review (TDD Mode Only)
+
+**When:** All waves in a phase complete and `workflow.tdd_mode` is enabled. Inserted by the execute-phase orchestrator after `aggregate_results`.
+
+**Purpose:** Collaborative review of TDD gate compliance across all `type: tdd` plans in the phase. Advisory — does not block execution.
+
+**Use for:**
+- Verifying RED/GREEN/REFACTOR commit sequence for each TDD plan
+- Surfacing gate violations (missing RED or GREEN commits)
+- Reviewing test quality (tests fail for the right reason)
+- Confirming minimal GREEN implementations
+
+**Structure:**
+```xml
+<task type="checkpoint:tdd-review" gate="advisory">
+  <what-checked>TDD gate compliance for {count} plans in Phase {X}</what-checked>
+  <gate-results>
+    | Plan | RED | GREEN | REFACTOR | Status |
+    |------|-----|-------|----------|--------|
+    | {id} |  ✓  |   ✓   |    ✓     | Pass   |
+  </gate-results>
+  <violations>[List of gate violations, or "None"]</violations>
+  <resume-signal>Review complete — proceed to phase verification</resume-signal>
+</task>
+```
+
+**Auto-mode behavior:** When `workflow._auto_chain_active` or `workflow.auto_advance` is true, the TDD review checkpoint auto-approves (advisory gate — never blocks).
+</type>
+
 <summary>
 
 Checkpoints formalize human-in-the-loop points for verification and decisions, not manual work.

package/.agent/skills/gsd/references/docs/common-bug-patterns.md

@@ -6,85 +6,85 @@ Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by
 
 ## Null / Undefined Access
 
-- [ ] Accessing property on `null` or `undefined` — missing null check or optional chaining
-- [ ] Function returns `undefined` instead of expected value — missing `return` statement or wrong branch
-- [ ] Array/object destructuring on `null`/`undefined` — API returned error shape instead of data
-- [ ] Optional parameter used without default — caller omitted argument
+- **Null property access** — accessing property on `null` or `undefined`, missing null check or optional chaining
+- **Missing return value** — function returns `undefined` instead of expected value, missing `return` statement or wrong branch
+- **Destructuring null** — array/object destructuring on `null`/`undefined`, API returned error shape instead of data
+- **Undefaulted optional** — optional parameter used without default, caller omitted argument
 
 ## Off-by-One / Boundary
 
-- [ ] Loop starts at 1 instead of 0, or ends at `length` instead of `length - 1`
-- [ ] Fence-post error — "N items need N-1 separators" miscounted
-- [ ] Inclusive vs exclusive range boundary — `<` vs `<=`, slice/substring end index
-- [ ] Empty collection not handled — `.length === 0` falls through to logic assuming items exist
+- **Wrong loop bound** — loop starts at 1 instead of 0, or ends at `length` instead of `length - 1`
+- **Fence-post error** — "N items need N-1 separators" miscounted
+- **Inclusive vs exclusive** — range boundary `<` vs `<=`, slice/substring end index
+- **Empty collection** — `.length === 0` falls through to logic assuming items exist
 
 ## Async / Timing
 
-- [ ] Missing `await` on async function — gets Promise object instead of resolved value
-- [ ] Race condition — two async operations read/write same state without coordination
-- [ ] Stale closure — callback captures old variable value, not current one
-- [ ] Event handler fires before setup complete — initialization order dependency
-- [ ] Timeout/interval not cleaned up — fires after component/context destroyed
+- **Missing await** — async function called without `await`, gets Promise object instead of resolved value
+- **Race condition** — two async operations read/write same state without coordination
+- **Stale closure** — callback captures old variable value, not current one
+- **Initialization order** — event handler fires before setup complete
+- **Leaked timer** — timeout/interval not cleaned up, fires after component/context destroyed
 
 ## State Management
 
-- [ ] Mutating shared state — object/array modified in place affects other consumers
-- [ ] State updated but UI not re-rendered — missing reactive trigger or wrong reference
-- [ ] Stale state in event handler — closure captures state at bind time, not current value
-- [ ] Multiple sources of truth — same data stored in two places, one gets out of sync
-- [ ] State machine allows invalid transition — missing guard condition
+- **Shared mutation** — object/array modified in place affects other consumers
+- **Stale render** — state updated but UI not re-rendered, missing reactive trigger or wrong reference
+- **Stale handler state** — closure captures state at bind time, not current value
+- **Dual source of truth** — same data stored in two places, one gets out of sync
+- **Invalid transition** — state machine allows transition missing guard condition
 
 ## Import / Module
 
-- [ ] Circular dependency — module A imports B, B imports A, one gets `undefined`
-- [ ] Default vs named export mismatch — `import X` vs `import { X }`
-- [ ] Wrong file extension — `.js` vs `.cjs` vs `.mjs`, `.ts` vs `.tsx`
-- [ ] Path case sensitivity — works on Windows/macOS, fails on Linux
-- [ ] Missing file extension in import — ESM requires explicit extensions
+- **Circular dependency** — module A imports B, B imports A, one gets `undefined`
+- **Export mismatch** — default vs named export, `import X` vs `import { X }`
+- **Wrong extension** — `.js` vs `.cjs` vs `.mjs`, `.ts` vs `.tsx`
+- **Path case sensitivity** — works on Windows/macOS, fails on Linux
+- **Missing extension** — ESM requires explicit file extensions in imports
 
 ## Type / Coercion
 
-- [ ] String vs number comparison — `"5" > "10"` is `true` (lexicographic), `5 > 10` is `false`
-- [ ] Implicit type coercion — `==` instead of `===`, truthy/falsy surprises (`0`, `""`, `[]`)
-- [ ] Integer overflow or floating point — `0.1 + 0.2 !== 0.3`, large numbers lose precision
-- [ ] Boolean vs truthy check — value is `0` or `""` which is valid but falsy
+- **String vs number compare** — `"5" > "10"` is `true` (lexicographic), `5 > 10` is `false`
+- **Implicit coercion** — `==` instead of `===`, truthy/falsy surprises (`0`, `""`, `[]`)
+- **Numeric precision** — `0.1 + 0.2 !== 0.3`, large integers lose precision
+- **Falsy valid value** — value is `0` or `""` which is valid but falsy
 
 ## Environment / Config
 
-- [ ] Environment variable missing or wrong — different value in dev vs prod vs CI
-- [ ] Hardcoded path or URL — works on one machine, fails on another
-- [ ] Port already in use — previous process still running
-- [ ] File permission denied — different user/group in deployment
-- [ ] Missing dependency — not in package.json or not installed
+- **Missing env var** — environment variable missing or wrong value in dev vs prod vs CI
+- **Hardcoded path** — works on one machine, fails on another
+- **Port conflict** — port already in use, previous process still running
+- **Permission denied** — different user/group in deployment
+- **Missing dependency** — not in package.json or not installed
 
 ## Data Shape / API Contract
 
-- [ ] API response shape changed — backend updated, frontend expects old format
-- [ ] Array where object expected (or vice versa) — `data` vs `data.results` vs `data[0]`
-- [ ] Missing field in payload — required field omitted, backend returns validation error
-- [ ] Date/time format mismatch — ISO string vs timestamp vs locale string
-- [ ] Encoding mismatch — UTF-8 vs Latin-1, URL encoding, HTML entities
+- **Changed response shape** — backend updated, frontend expects old format
+- **Wrong container type** — array where object expected or vice versa, `data` vs `data.results` vs `data[0]`
+- **Missing required field** — required field omitted in payload, backend returns validation error
+- **Date format mismatch** — ISO string vs timestamp vs locale string
+- **Encoding mismatch** — UTF-8 vs Latin-1, URL encoding, HTML entities
 
 ## Regex / String
 
-- [ ] Regex `g` flag with `.test()` then `.exec()` — `lastIndex` not reset between calls
-- [ ] Missing escape — `.` matches any char, `$` is special, backslash needs doubling
-- [ ] Greedy match captures too much — `.*` eats through delimiters, need `.*?`
-- [ ] String interpolation in wrong quote type — template literals need backticks
+- **Sticky lastIndex** — regex `g` flag with `.test()` then `.exec()`, `lastIndex` not reset between calls
+- **Missing escape** — `.` matches any char, `$` is special, backslash needs doubling
+- **Greedy overmatch** — `.*` eats through delimiters, need `.*?`
+- **Wrong quote type** — string interpolation needs backticks for template literals
 
 ## Error Handling
 
-- [ ] Catch block swallows error — empty `catch {}` or logs but doesn't rethrow/handle
-- [ ] Wrong error type caught — catches base `Error` when specific type needed
-- [ ] Error in error handler — cleanup code throws, masking original error
-- [ ] Promise rejection unhandled — missing `.catch()` or try/catch around `await`
+- **Swallowed error** — empty `catch {}` or logs but doesn't rethrow/handle
+- **Wrong error type** — catches base `Error` when specific type needed
+- **Error in handler** — cleanup code throws, masking original error
+- **Unhandled rejection** — missing `.catch()` or try/catch around `await`
 
 ## Scope / Closure
 
-- [ ] Variable shadowing — inner scope declares same name, hides outer variable
-- [ ] Loop variable capture — all closures share same `var i`, use `let` or bind
-- [ ] `this` binding lost — callback loses context, need `.bind()` or arrow function
-- [ ] Block scope vs function scope — `var` hoisted to function, `let`/`const` block-scoped
+- **Variable shadowing** — inner scope declares same name, hides outer variable
+- **Loop variable capture** — all closures share same `var i`, use `let` or bind
+- **Lost this binding** — callback loses context, need `.bind()` or arrow function
+- **Scope confusion** — `var` hoisted to function, `let`/`const` block-scoped
 
 </patterns>
 

package/.agent/skills/gsd/references/docs/continuation-format.md

@@ -7,7 +7,7 @@ Standard format for presenting next steps after completing a command or workflow
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **{identifier}: {name}** — {one-line description}
 
@@ -24,6 +24,9 @@ Standard format for presenting next steps after completing a command or workflow
 ---
 ```
 
+> If `project_code` is not set in the init context, omit the project identity suffix:
+> `## ▶ Next Up` (no ` — [CODE] Title`).
+
 ## Format Rules
 
 1. **Always show what it is** — name + description, never just a command path
@@ -32,6 +35,7 @@ Standard format for presenting next steps after completing a command or workflow
 4. **`/clear` first** — always show `/clear` before the command so users run it in the correct order
 5. **"Also available" not "Other options"** — sounds more app-like
 6. **Visual separators** — `---` above and below to make it stand out
+7. **Project identity in heading** — include `[PROJECT_CODE] PROJECT_TITLE` from init context so handoffs are self-identifying across sessions. If `project_code` is not set, omit the suffix entirely (just `## ▶ Next Up`)
 
 ## Variants
 
@@ -40,7 +44,7 @@ Standard format for presenting next steps after completing a command or workflow
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 
@@ -64,7 +68,7 @@ Add note that this is the last plan and what comes after:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
 <sub>Final plan in Phase 2</sub>
@@ -87,7 +91,7 @@ Add note that this is the last plan and what comes after:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 2: Authentication** — JWT login flow with refresh tokens
 
@@ -116,7 +120,7 @@ Show completion status before next action:
 
 3/3 plans executed
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
@@ -141,7 +145,7 @@ When there's no clear primary action:
 ```
 ---
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Phase 3: Core Features** — User dashboard, settings, and data export
 
@@ -165,7 +169,7 @@ When there's no clear primary action:
 
 All 4 phases shipped
 
-## ▶ Next Up
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
 
 **Start v1.1** — questioning → research → requirements → roadmap
 

package/.agent/skills/gsd/references/docs/debugger-philosophy.md

@@ -0,0 +1,76 @@
+# Debugger Philosophy
+
+Evergreen debugging disciplines — applies across every bug, every language, every system. Loaded by `gsd-debugger` via `@file` include.
+
+## User = Reporter, Antigravity = Investigator
+
+The user knows:
+- What they expected to happen
+- What actually happened
+- Error messages they saw
+- When it started / if it ever worked
+
+The user does NOT know (don't ask):
+- What's causing the bug
+- Which file has the problem
+- What the fix should be
+
+Ask about experience. Investigate the cause yourself.
+
+## Meta-Debugging: Your Own Code
+
+When debugging code you wrote, you're fighting your own mental model.
+
+**Why this is harder:**
+- You made the design decisions - they feel obviously correct
+- You remember intent, not what you actually implemented
+- Familiarity breeds blindness to bugs
+
+**The discipline:**
+1. **Treat your code as foreign** - Read it as if someone else wrote it
+2. **Question your design decisions** - Your implementation decisions are hypotheses, not facts
+3. **Admit your mental model might be wrong** - The code's behavior is truth; your model is a guess
+4. **Prioritize code you touched** - If you modified 100 lines and something breaks, those are prime suspects
+
+**The hardest admission:** "I implemented this wrong." Not "requirements were unclear" - YOU made an error.
+
+## Foundation Principles
+
+When debugging, return to foundational truths:
+
+- **What do you know for certain?** Observable facts, not assumptions
+- **What are you assuming?** "This library should work this way" - have you verified?
+- **Strip away everything you think you know.** Build understanding from observable facts.
+
+## Cognitive Biases to Avoid
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" |
+| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any |
+| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
+| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
+
+## Systematic Investigation Disciplines
+
+**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered.
+
+**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses crucial details.
+
+**Embrace not knowing:** "I don't know why this fails" = good (now you can investigate). "It must be X" = dangerous (you've stopped thinking).
+
+## When to Restart
+
+Consider starting over when:
+1. **2+ hours with no progress** - You're likely tunnel-visioned
+2. **3+ "fixes" that didn't work** - Your mental model is wrong
+3. **You can't explain the current behavior** - Don't add changes on top of confusion
+4. **You're debugging the debugger** - Something fundamental is wrong
+5. **The fix works but you don't know why** - This isn't fixed, this is luck
+
+**Restart protocol:**
+1. Close all files and terminals
+2. Write down what you know for certain
+3. Write down what you've ruled out
+4. List new hypotheses (different from before)
+5. Begin again from Phase 1: Evidence Gathering