@therocketcode/gsd-core 1.4.0

package/gsd-core/references/common-bug-patterns.md

@@ -0,0 +1,114 @@
+# Common Bug Patterns
+
+Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by frequency. Check these FIRST — they cover ~80% of bugs across all technology stacks.
+
+<patterns>
+
+## Null / Undefined Access
+
+- **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
+
+- **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** — 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
+
+- **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`
+- **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 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
+
+- **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
+
+- **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
+
+- **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
+
+- **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
+- **Lost this binding** — callback loses context, need `.bind()` or arrow function
+- **Scope confusion** — `var` hoisted to function, `let`/`const` block-scoped
+
+</patterns>
+
+<usage>
+
+## How to Use This Checklist
+
+1. **Before forming any hypothesis**, scan the relevant categories based on the symptom
+2. **Match symptom to pattern** — if the bug involves "undefined is not an object", check Null/Undefined first
+3. **Each checked pattern is a hypothesis candidate** — verify or eliminate with evidence
+4. **If no pattern matches**, proceed to open-ended investigation
+
+### Symptom-to-Category Quick Map
+
+| Symptom | Check First |
+|---------|------------|
+| "Cannot read property of undefined/null" | Null/Undefined Access |
+| "X is not a function" | Import/Module, Type/Coercion |
+| Works sometimes, fails sometimes | Async/Timing, State Management |
+| Works locally, fails in CI/prod | Environment/Config |
+| Wrong data displayed | Data Shape, State Management |
+| Off by one item / missing last item | Off-by-One/Boundary |
+| "Unexpected token" / parse error | Data Shape, Type/Coercion |
+| Memory leak / growing resource usage | Async/Timing (cleanup), Scope/Closure |
+| Infinite loop / max call stack | State Management, Async/Timing |
+
+</usage>

package/gsd-core/references/context-budget.md

@@ -0,0 +1,85 @@
+# Context Budget Rules
+
+Standard rules for keeping orchestrator context lean. Reference this in workflows that spawn subagents or read significant content.
+
+See also: `references/universal-anti-patterns.md` for the complete set of universal rules.
+
+---
+
+## Universal Rules
+
+Every workflow that spawns agents or reads significant content must follow these rules:
+
+1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them
+2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
+4. **Delegate** heavy work to subagents -- the orchestrator routes, it doesn't execute
+5. **Proactive warning**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
+
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window`. If the field is absent, treat as 200k (conservative default).
+
+## Context Degradation Tiers
+
+Monitor context usage and adjust behavior accordingly:
+
+| Tier | Usage | Behavior |
+|------|-------|----------|
+| PEAK | 0-30% | Full operations. Read bodies, spawn multiple agents, inline results. |
+| GOOD | 30-50% | Normal operations. Prefer frontmatter reads, delegate aggressively. |
+| DEGRADING | 50-70% | Economize. Frontmatter-only reads, minimal inlining, warn user about budget. |
+| POOR | 70%+ | Emergency mode. Checkpoint progress immediately. No new reads unless critical. |
+
+## Context Degradation Warning Signs
+
+Quality degrades gradually before panic thresholds fire. Watch for these early signals:
+
+- **Silent partial completion** -- agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** -- agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** -- agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output -- only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
+## MCP Tool Schema Cost (Harness Concern)
+
+Every enabled MCP server injects its tool schema into **every turn**, regardless of whether you call any of its tools. Heavyweight servers can cost 20k+ tokens per turn each — often dwarfing whatever GSD itself can save through `model_profile` tuning. This is a Claude Code harness concern, not a GSD concern: GSD does **not** manage MCP enablement. The toggle lives in `.claude/settings.json` under `enabledMcpjsonServers` and `disabledMcpjsonServers`.
+
+### Why this is the biggest cost lever you don't own
+
+Tool schemas count against the same context budget as model context, prompts, and conversation history. If a project has 5 unused MCP servers averaging 5k tokens of schema each, every turn pays a 25k-token tax before the assistant reads a single project file. Trimming MCPs has a **multiplier effect** that compounds with whichever `model_profile` you've chosen — every-turn overhead drops regardless of which model is in use.
+
+### Pre-Phase MCP Audit
+
+Before starting a long phase (especially `/gsd:execute-phase`, `/gsd:plan-phase`, or anything that fans out across many subagents), run this audit:
+
+- [ ] **Browser / playwright tools enabled?** If this phase has no UI work, disable them. They're among the heaviest per-turn schemas.
+- [ ] **Platform-specific tools enabled?** Mac-tools / Windows-tools / OS-specific helpers should be disabled when not actively needed for the phase at hand.
+- [ ] **Cross-project / stale MCPs?** Servers added for a different project that are still enabled here. These are often forgotten and pay a per-turn tax for zero benefit.
+- [ ] **Duplicate or shadow servers?** Two MCPs offering similar tools (e.g. two different filesystem helpers). Keep one.
+
+Each item disabled removes its schema from every subsequent turn for the rest of the session.
+
+### How to toggle
+
+The keys live in `.claude/settings.json` (project) or `~/.claude/settings.json` (global) — **not** in `.planning/config.json`:
+
+```json
+{
+  "enabledMcpjsonServers": ["context7"],
+  "disabledMcpjsonServers": ["playwright", "mac-tools"]
+}
+```
+
+Either list works — `enabledMcpjsonServers` is an explicit allow-list, `disabledMcpjsonServers` is a block-list against the default. See the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) for the canonical reference; this section just flags it as a context-budget lever GSD users routinely overlook.
+
+### Composition with model_profile
+
+Trimming MCPs and tuning `model_profile` are independent levers that **compound**. Disabling a 25k-token MCP saves 25k per turn whether you're running `quality` (opus everywhere) or `budget` (sonnet/haiku); the savings are additive, not in lieu of model tuning. Don't pick one — do both, and audit MCPs first because the per-turn savings show up immediately and stack across every subagent the orchestrator spawns.

package/gsd-core/references/continuation-format.md

@@ -0,0 +1,253 @@
+# Continuation Format
+
+Standard format for presenting next steps after completing a command or workflow.
+
+## Core Structure
+
+```
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**{identifier}: {name}** — {one-line description}
+
+`/clear` then:
+
+`{command to copy-paste}`
+
+---
+
+**Also available:**
+- `{alternative option 1}` — description
+- `{alternative option 2}` — description
+
+---
+```
+
+> 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
+2. **Pull context from source** — ROADMAP.md for phases, PLAN.md `<objective>` for plans
+3. **Command in inline code** — backticks, easy to copy-paste, renders as clickable link
+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
+
+### Execute Next Plan
+
+```
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry
+
+`/clear` then:
+
+`/gsd:execute-phase 2`
+
+---
+
+**Also available:**
+- Review plan before executing
+- `/gsd:discuss-phase 2 --assumptions` — check assumptions
+
+---
+```
+
+### Execute Final Plan in Phase
+
+Add note that this is the last plan and what comes after:
+
+```
+---
+
+## ▶ 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>
+
+`/clear` then:
+
+`/gsd:execute-phase 2`
+
+---
+
+**After this completes:**
+- Phase 2 → Phase 3 transition
+- Next: **Phase 3: Core Features** — User dashboard and settings
+
+---
+```
+
+### Plan a Phase
+
+```
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Phase 2: Authentication** — JWT login flow with refresh tokens
+
+`/clear` then:
+
+`/gsd:plan-phase 2`
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 2` — gather context first
+- `/gsd:plan-phase --research-phase 2` — investigate unknowns
+- Review roadmap
+
+---
+```
+
+### Phase Complete, Ready for Next
+
+Show completion status before next action:
+
+```
+---
+
+## ✓ Phase 2 Complete
+
+3/3 plans executed
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/clear` then:
+
+`/gsd:plan-phase 3`
+
+---
+
+**Also available:**
+- `/gsd:discuss-phase 3` — gather context first
+- `/gsd:plan-phase --research-phase 3` — investigate unknowns
+- Review what Phase 2 built
+
+---
+```
+
+### Multiple Equal Options
+
+When there's no clear primary action:
+
+```
+---
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Phase 3: Core Features** — User dashboard, settings, and data export
+
+`/clear` then one of:
+
+**To plan directly:** `/gsd:plan-phase 3`
+
+**To discuss context first:** `/gsd:discuss-phase 3`
+
+**To research unknowns:** `/gsd:plan-phase --research-phase 3`
+
+---
+```
+
+### Milestone Complete
+
+```
+---
+
+## 🎉 Milestone v1.0 Complete
+
+All 4 phases shipped
+
+## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
+
+**Start v1.1** — questioning → research → requirements → roadmap
+
+`/clear` then:
+
+`/gsd:new-milestone`
+
+---
+```
+
+## Pulling Context
+
+### For phases (from ROADMAP.md):
+
+```markdown
+### Phase 2: Authentication
+**Goal**: JWT login flow with refresh tokens
+```
+
+Extract: `**Phase 2: Authentication** — JWT login flow with refresh tokens`
+
+### For plans (from ROADMAP.md):
+
+```markdown
+Plans:
+- [ ] 02-03: Add refresh token rotation
+```
+
+Or from PLAN.md `<objective>`:
+
+```xml
+<objective>
+Add refresh token rotation with sliding expiry window.
+
+Purpose: Extend session lifetime without compromising security.
+</objective>
+```
+
+Extract: `**02-03: Refresh Token Rotation** — Add /api/auth/refresh with sliding expiry`
+
+## Anti-Patterns
+
+### Don't: Command-only (no context)
+
+```
+## To Continue
+
+Run `/clear`, then paste:
+/gsd:execute-phase 2
+```
+
+User has no idea what 02-03 is about.
+
+### Don't: Missing /clear explanation
+
+```
+`/gsd:plan-phase 3`
+
+Run /clear first.
+```
+
+Doesn't explain why. User might skip it.
+
+### Don't: "Other options" language
+
+```
+Other options:
+- Review roadmap
+```
+
+Sounds like an afterthought. Use "Also available:" instead.
+
+### Don't: Fenced code blocks for commands
+
+```
+```
+/gsd:plan-phase 3
+```
+```
+
+Fenced blocks inside templates create nesting ambiguity. Use inline backticks instead.

package/gsd-core/references/db-test-isolation.md

@@ -0,0 +1,54 @@
+# Database Test Isolation & Parallelization
+
+How-to reference for keeping DB integration tests deterministic under parallelism — the "passes in isolation, fails in parallel" problem. Read this when tests share a database. Pairs with `test-containers.md`.
+
+## The problem
+
+Tests that share a database and run in parallel clobber each other's data → flaky, order-dependent failures. Fix = per-worker isolation + deterministic, test-owned data.
+
+## Strategy tradeoff table
+
+| Strategy | How | Parallel-safe | Speed | Tradeoff |
+|---|---|---|---|---|
+| **Txn-per-test + rollback** | open a transaction in setup, roll back in teardown; nothing commits | yes, if each worker has its own connection | fastest (in-memory rollback) | breaks if app code opens its own transactions / parallel queries; can't test commit-time behavior |
+| **TRUNCATE/DELETE between tests** | wipe tables after each test | hard on a shared DB | ok small; slows as data grows | serializes the suite |
+| **Schema-per-worker** | `CREATE SCHEMA w$i` + `search_path`; drop after | yes | ~200 ms clone | conflicts if the app already uses schemas for multi-tenancy |
+| **Database-per-worker** | each parallel worker gets its own DB (by worker index) | yes (strongest) | ~400 ms full clone | more DBs to manage |
+| **Template DB** (`CREATE DATABASE x TEMPLATE app_template`) | build a migrated+seeded template once, copy per worker/test | yes | fast reset (copy beats re-migrating) | **no sessions may be connected to the template during the copy** |
+| **No-truncate + UUID-scoped data** | each test inserts only its own rows keyed by UUID; never clean up | yes | very fast (no reset) | can't assert global counts; assertions must be scoped to test-owned rows |
+
+## Recommended default (parallel CI)
+
+**Database-per-worker (or schema-per-worker), seeded from a template DB, with transaction-per-test rollback inside each worker.** Stacks per-worker isolation (no cross-worker races) with cheap per-test reset. Fall back to template-copy or no-truncate+UUID where app code manages its own transactions (rollback won't work there).
+
+## Determinism checklist
+
+- One DB/schema per worker → zero shared mutable state.
+- Unique keys via **UUID or a per-factory sequence** — never raw Faker values you assert on (Heisenbugs).
+- Fixed clock + seeded RNG (see `flaky-test-checklist.md`).
+- Order-independent: every test self-seeds; no test depends on another's leftover rows.
+
+## Worker-indexed DB (Playwright example)
+
+```ts
+// derive a per-worker DB from the worker index, in a worker-scoped fixture
+const dbName = `app_w${process.env.TEST_PARALLEL_INDEX ?? test.info().workerIndex}`;
+// CREATE DATABASE ${dbName} TEMPLATE app_template;  (drain template connections first)
+```
+
+## Postgres template DB
+
+```sql
+-- build once (migrated + reference/seed data), then per worker/test:
+-- drain the template first (it must have ZERO active connections):
+SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname = 'app_template' AND pid <> pg_backend_pid();
+CREATE DATABASE app_w0 TEMPLATE app_template;  -- run this while connected to another DB (e.g. postgres)
+```
+
+## Anti-patterns
+
+- A single shared DB across parallel workers with TRUNCATE between tests (races; forces serialization).
+- Raw random Faker values in assertions (intermittent failures you can't reproduce).
+- Order-dependent tests (one test relying on another's leftover state).
+
+*Sources: conroy.org (schema-per-test); Kevin Burke (parallel DB tests, UUID-scoped); Postgres template-DB docs; Playwright parallel docs. Genuine tradeoff: txn-rollback is fastest but incompatible with app-managed transactions; UUID-scoped never cleans up but can't assert global state — choose by whether your assertions need global counts.*

package/gsd-core/references/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, Claude = 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

package/gsd-core/references/decimal-phase-calculation.md

@@ -0,0 +1,64 @@
+# Decimal Phase Calculation
+
+Calculate the next decimal phase number for urgent insertions.
+
+## Using gsd-tools
+
+```bash
+# Get next decimal phase after phase 6
+gsd-tools query phase.next-decimal 6
+```
+
+Output:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.1",
+  "existing": []
+}
+```
+
+With existing decimals:
+```json
+{
+  "found": true,
+  "base_phase": "06",
+  "next": "06.3",
+  "existing": ["06.1", "06.2"]
+}
+```
+
+## Extract Values
+
+```bash
+DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick next)
+BASE_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --pick base_phase)
+```
+
+Or with --raw flag:
+```bash
+DECIMAL_PHASE=$(gsd-tools query phase.next-decimal "${AFTER_PHASE}" --raw)
+# Returns just: 06.1
+```
+
+## Examples
+
+| Existing Phases | Next Phase |
+|-----------------|------------|
+| 06 only | 06.1 |
+| 06, 06.1 | 06.2 |
+| 06, 06.1, 06.2 | 06.3 |
+| 06, 06.1, 06.3 (gap) | 06.4 |
+
+## Directory Naming
+
+Decimal phase directories use the full decimal number:
+
+```bash
+SLUG=$(gsd-tools query generate-slug "$DESCRIPTION" --raw)
+PHASE_DIR=".planning/phases/${DECIMAL_PHASE}-${SLUG}"
+mkdir -p "$PHASE_DIR"
+```
+
+Example: `.planning/phases/06.1-fix-critical-auth-bug/`