From c298a1a4dcd2b71af0a6b8732b3f6864774381c2 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Tue, 3 Mar 2026 10:53:34 -0600 Subject: [PATCH] refactor: rename depth setting to granularity (closes #879) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "depth" setting with values quick/standard/comprehensive implied investigation thoroughness, but it only controls phase count. Renamed to "granularity" with values coarse/standard/fine to accurately reflect what it controls: how finely scope is sliced into phases. Includes backward-compatible migration in loadConfig and config-ensure that auto-renames depth→granularity with value mapping in both .planning/config.json and ~/.gsd/defaults.json. Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- agents/gsd-planner.md | 14 ++++++------ agents/gsd-roadmapper.md | 24 ++++++++++----------- docs/USER-GUIDE.md | 10 ++++----- get-shit-done/bin/lib/config.cjs | 7 ++++++ get-shit-done/bin/lib/core.cjs | 8 +++++++ get-shit-done/templates/config.json | 2 +- get-shit-done/templates/roadmap.md | 2 +- get-shit-done/workflows/new-project.md | 30 +++++++++++++------------- get-shit-done/workflows/settings.md | 2 +- 10 files changed, 58 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 91332b8ce..ca2e4d089 100644 --- a/README.md +++ b/README.md @@ -532,7 +532,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n | Setting | Options | Default | What it controls | |---------|---------|---------|------------------| | `mode` | `yolo`, `interactive` | `interactive` | Auto-approve vs confirm at each step | -| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness (phases × plans) | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity — how finely scope is sliced (phases × plans) | ### Model Profiles diff --git a/agents/gsd-planner.md b/agents/gsd-planner.md index 4013c98cd..cd1782e75 100644 --- a/agents/gsd-planner.md +++ b/agents/gsd-planner.md @@ -371,15 +371,15 @@ Plans should complete within ~50% context (not 80%). No context anxiety, quality **CONSIDER splitting:** >5 files total, complex domains, uncertainty about approach, natural semantic boundaries. -## Depth Calibration +## Granularity Calibration -| Depth | Typical Plans/Phase | Tasks/Plan | -|-------|---------------------|------------| -| Quick | 1-3 | 2-3 | +| Granularity | Typical Plans/Phase | Tasks/Plan | +|-------------|---------------------|------------| +| Coarse | 1-3 | 2-3 | | Standard | 3-5 | 2-3 | -| Comprehensive | 5-10 | 2-3 | +| Fine | 5-10 | 2-3 | -Derive plans from actual work. Depth determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient. +Derive plans from actual work. Granularity determines compression tolerance, not a target. Don't pad small work to hit a number. Don't compress complex work to look efficient. ## Context Per Task Estimates @@ -1135,7 +1135,7 @@ Apply goal-backward methodology (see goal_backward section): -Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check depth setting. +Verify each plan fits context budget: 2-3 tasks, ~50% target. Split if necessary. Check granularity setting. diff --git a/agents/gsd-roadmapper.md b/agents/gsd-roadmapper.md index fc02333c4..d11a9411e 100644 --- a/agents/gsd-roadmapper.md +++ b/agents/gsd-roadmapper.md @@ -200,17 +200,17 @@ Track coverage as you go. - New milestone: Start at 1 - Continuing milestone: Check existing phases, start at last + 1 -## Depth Calibration +## Granularity Calibration -Read depth from config.json. Depth controls compression tolerance. +Read granularity from config.json. Granularity controls compression tolerance. -| Depth | Typical Phases | What It Means | -|-------|----------------|---------------| -| Quick | 3-5 | Combine aggressively, critical path only | +| Granularity | Typical Phases | What It Means | +|-------------|----------------|---------------| +| Coarse | 3-5 | Combine aggressively, critical path only | | Standard | 5-8 | Balanced grouping | -| Comprehensive | 8-12 | Let natural boundaries stand | +| Fine | 8-12 | Let natural boundaries stand | -**Key:** Derive phases from work, then apply depth as compression guidance. Don't pad small projects or compress complex ones. +**Key:** Derive phases from work, then apply granularity as compression guidance. Don't pad small projects or compress complex ones. ## Good Phase Patterns @@ -357,7 +357,7 @@ When presenting to user for approval: ## ROADMAP DRAFT **Phases:** [N] -**Depth:** [from config] +**Granularity:** [from config] **Coverage:** [X]/[Y] requirements mapped ### Phase Structure @@ -401,7 +401,7 @@ Orchestrator provides: - PROJECT.md content (core value, constraints) - REQUIREMENTS.md content (v1 requirements with REQ-IDs) - research/SUMMARY.md content (if exists - phase suggestions) -- config.json (depth setting) +- config.json (granularity setting) Parse and confirm understanding before proceeding. @@ -437,7 +437,7 @@ Apply phase identification methodology: 1. Group requirements by natural delivery boundaries 2. Identify dependencies between groups 3. Create phases that complete coherent capabilities -4. Check depth setting for compression guidance +4. Check granularity setting for compression guidance ## Step 5: Derive Success Criteria @@ -502,7 +502,7 @@ When files are written and returning to orchestrator: ### Summary **Phases:** {N} -**Depth:** {from config} +**Granularity:** {from config} **Coverage:** {X}/{X} requirements mapped ✓ | Phase | Goal | Requirements | @@ -628,7 +628,7 @@ Roadmap is complete when: - [ ] All v1 requirements extracted with IDs - [ ] Research context loaded (if exists) - [ ] Phases derived from requirements (not imposed) -- [ ] Depth calibration applied +- [ ] Granularity calibration applied - [ ] Dependencies between phases identified - [ ] Success criteria derived for each phase (2-5 observable behaviors) - [ ] Success criteria cross-checked against requirements (gaps resolved) diff --git a/docs/USER-GUIDE.md b/docs/USER-GUIDE.md index 2d02cafd4..7b279083c 100644 --- a/docs/USER-GUIDE.md +++ b/docs/USER-GUIDE.md @@ -215,7 +215,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n ```json { "mode": "interactive", - "depth": "standard", + "granularity": "standard", "model_profile": "balanced", "planning": { "commit_docs": true, @@ -240,7 +240,7 @@ GSD stores project settings in `.planning/config.json`. Configure during `/gsd:n | Setting | Options | Default | What it Controls | |---------|---------|---------|------------------| | `mode` | `interactive`, `yolo` | `interactive` | `yolo` auto-approves decisions; `interactive` confirms at each step | -| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Planning thoroughness: 3-5, 5-8, or 8-12 phases | +| `granularity` | `coarse`, `standard`, `fine` | `standard` | Phase granularity: how finely scope is sliced (3-5, 5-8, or 8-12 phases) | | `model_profile` | `quality`, `balanced`, `budget` | `balanced` | Model tier for each agent (see table below) | ### Planning Settings @@ -364,11 +364,11 @@ claude --dangerously-skip-permissions ### Speed vs Quality Presets -| Scenario | Mode | Depth | Profile | Research | Plan Check | Verifier | +| Scenario | Mode | Granularity | Profile | Research | Plan Check | Verifier | |----------|------|-------|---------|----------|------------|----------| -| Prototyping | `yolo` | `quick` | `budget` | off | off | off | +| Prototyping | `yolo` | `coarse` | `budget` | off | off | off | | Normal dev | `interactive` | `standard` | `balanced` | on | on | on | -| Production | `interactive` | `comprehensive` | `quality` | on | on | on | +| Production | `interactive` | `fine` | `quality` | on | on | on | ### Mid-Milestone Scope Changes diff --git a/get-shit-done/bin/lib/config.cjs b/get-shit-done/bin/lib/config.cjs index 0d9a9260d..5c5717ed5 100644 --- a/get-shit-done/bin/lib/config.cjs +++ b/get-shit-done/bin/lib/config.cjs @@ -37,6 +37,13 @@ function cmdConfigEnsureSection(cwd, raw) { try { if (fs.existsSync(globalDefaultsPath)) { userDefaults = JSON.parse(fs.readFileSync(globalDefaultsPath, 'utf-8')); + // Migrate deprecated "depth" key to "granularity" + if ('depth' in userDefaults && !('granularity' in userDefaults)) { + const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; + userDefaults.granularity = depthToGranularity[userDefaults.depth] || userDefaults.depth; + delete userDefaults.depth; + try { fs.writeFileSync(globalDefaultsPath, JSON.stringify(userDefaults, null, 2), 'utf-8'); } catch {} + } } } catch (err) { // Ignore malformed global defaults, fall back to hardcoded diff --git a/get-shit-done/bin/lib/core.cjs b/get-shit-done/bin/lib/core.cjs index ac5e82276..420317e2c 100644 --- a/get-shit-done/bin/lib/core.cjs +++ b/get-shit-done/bin/lib/core.cjs @@ -85,6 +85,14 @@ function loadConfig(cwd) { const raw = fs.readFileSync(configPath, 'utf-8'); const parsed = JSON.parse(raw); + // Migrate deprecated "depth" key to "granularity" with value mapping + if ('depth' in parsed && !('granularity' in parsed)) { + const depthToGranularity = { quick: 'coarse', standard: 'standard', comprehensive: 'fine' }; + parsed.granularity = depthToGranularity[parsed.depth] || parsed.depth; + delete parsed.depth; + try { fs.writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf-8'); } catch {} + } + const get = (key, nested) => { if (parsed[key] !== undefined) return parsed[key]; if (nested && parsed[nested.section] && parsed[nested.section][nested.field] !== undefined) { diff --git a/get-shit-done/templates/config.json b/get-shit-done/templates/config.json index d67ef3026..79af2a09f 100644 --- a/get-shit-done/templates/config.json +++ b/get-shit-done/templates/config.json @@ -1,6 +1,6 @@ { "mode": "interactive", - "depth": "standard", + "granularity": "standard", "workflow": { "research": true, "plan_check": true, diff --git a/get-shit-done/templates/roadmap.md b/get-shit-done/templates/roadmap.md index ff679c9c0..9d6749bf5 100644 --- a/get-shit-done/templates/roadmap.md +++ b/get-shit-done/templates/roadmap.md @@ -105,7 +105,7 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4 **Initial planning (v1.0):** -- Phase count depends on depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12) +- Phase count depends on granularity setting (coarse: 3-5, standard: 5-8, fine: 8-12) - Each phase delivers something coherent - Phases can have 1+ plans (split if >3 tasks or multiple subsystems) - Plans use naming: {phase}-{plan}-PLAN.md (e.g., 01-02-PLAN.md) diff --git a/get-shit-done/workflows/new-project.md b/get-shit-done/workflows/new-project.md index 0ccd254a9..193602511 100644 --- a/get-shit-done/workflows/new-project.md +++ b/get-shit-done/workflows/new-project.md @@ -14,7 +14,7 @@ Check if `--auto` flag is present in $ARGUMENTS. **If auto mode:** - Skip brownfield mapping offer (assume greenfield) - Skip deep questioning (extract context from provided document) -- Config: YOLO mode is implicit (skip that question), but ask depth/git/agents FIRST (Step 2a) +- Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a) - After config: run Steps 6-9 automatically with smart defaults: - Research: Always yes - Requirements: Include all table stakes + features from provided document @@ -90,13 +90,13 @@ YOLO mode is implicit (auto = YOLO). Ask remaining config questions: ``` AskUserQuestion([ { - header: "Depth", - question: "How thorough should planning be?", + header: "Granularity", + question: "How finely should scope be sliced into phases?", multiSelect: false, options: [ - { label: "Quick (Recommended)", description: "Ship fast (3-5 phases, 1-3 plans each)" }, - { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" }, - { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" } + { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" }, + { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" }, + { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" } ] }, { @@ -169,7 +169,7 @@ Create `.planning/config.json` with mode set to "yolo": ```json { "mode": "yolo", - "depth": "[selected]", + "granularity": "[selected]", "parallelization": true|false, "commit_docs": true|false, "model_profile": "quality|balanced|budget", @@ -379,13 +379,13 @@ questions: [ ] }, { - header: "Depth", - question: "How thorough should planning be?", + header: "Granularity", + question: "How finely should scope be sliced into phases?", multiSelect: false, options: [ - { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" }, - { label: "Standard", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" }, - { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" } + { label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" }, + { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" }, + { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" } ] }, { @@ -468,7 +468,7 @@ Create `.planning/config.json` with all settings: ```json { "mode": "yolo|interactive", - "depth": "quick|standard|comprehensive", + "granularity": "coarse|standard|fine", "parallelization": true|false, "commit_docs": true|false, "model_profile": "quality|balanced|budget", @@ -903,7 +903,7 @@ Task(prompt=" - .planning/PROJECT.md (Project context) - .planning/REQUIREMENTS.md (v1 Requirements) - .planning/research/SUMMARY.md (Research findings - if exists) -- .planning/config.json (Depth and mode settings) +- .planning/config.json (Granularity and mode settings) @@ -1090,7 +1090,7 @@ Exit skill and invoke SlashCommand("/gsd:discuss-phase 1 --auto") - [ ] Brownfield detection completed - [ ] Deep questioning completed (threads followed, not rushed) - [ ] PROJECT.md captures full context → **committed** -- [ ] config.json has workflow mode, depth, parallelization → **committed** +- [ ] config.json has workflow mode, granularity, parallelization → **committed** - [ ] Research completed (if selected) — 4 parallel agents spawned → **committed** - [ ] Requirements gathered (from research or conversation) - [ ] User scoped each category (v1/v2/out of scope) diff --git a/get-shit-done/workflows/settings.md b/get-shit-done/workflows/settings.md index 9677001db..1c78b03c9 100644 --- a/get-shit-done/workflows/settings.md +++ b/get-shit-done/workflows/settings.md @@ -157,7 +157,7 @@ Write `~/.gsd/defaults.json` with: ```json { "mode": , - "depth": , + "granularity": , "model_profile": , "commit_docs": , "parallelization": ,