refactor: rename depth setting to granularity (closes #879)

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 <noreply@anthropic.com>
2026-04-25 17:25:23 +02:00 · 2026-03-03 10:53:34 -06:00
parent e2b6179ba7
commit c298a1a4dc
10 changed files with 58 additions and 43 deletions
--- 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

--- 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):
 </step>

 <step name="estimate_scope">
-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.
 </step>

 <step name="confirm_breakdown">
--- 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)
--- 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

--- 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
--- 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) {
--- 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,
--- 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

 <guidelines>
 **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)
--- 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)
 </files_to_read>

 </planning_context>
@@ -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)
--- 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": <current>,
-  "depth": <current>,
+  "granularity": <current>,
  "model_profile": <current>,
  "commit_docs": <current>,
  "parallelization": <current>,