Skip to content

Rename depth setting — "quick/comprehensive" implies investigation thoroughness, not phase granularity #879

@patrick833

Description

@patrick833

Problem or motivation

Summary

The depth setting (quick / standard / comprehensive) suggests that choosing
quick results in shallower investigation, when in reality it only controls how many
phases the roadmap is sliced into. Each phase still receives the full research → plan →
check → execute → verify cycle regardless of the depth value.

Current behavior

depth Phases Implication from name
quick 3-5 "Less thorough"
standard 5-8 "Normal thoroughness"
comprehensive 8-12 "More thorough investigation"

A user choosing quick might expect faster but shallower analysis. A user choosing
comprehensive might expect deeper per-phase research. Neither is true — the per-phase
pipeline is identical across all three values.

What it actually controls

The number of phases in the roadmap, which determines:

  • Granularity of control — more phases = more checkpoints to course-correct
  • Scope per phase — fewer phases = each phase covers broader ground
  • Total wall-clock time and token cost — scales linearly with phase count

Proposed solution

Proposal

Rename the setting and its values to reflect what they actually control:

Option Current name Suggested name
Setting depth granularity
Value 1 quick coarse
Value 2 standard standard
Value 3 comprehensive fine

Alternative value names: broad / standard / detailed, or few / standard / many.

The setting description in /gsd:settings should also be updated from
"Planning thoroughness" to something like "Phase granularity — how finely scope is sliced."

Impact

  • config.json schema change (with backward compat for existing configs)
  • /gsd:settings UI text
  • /gsd:new-project prompts
  • User guide documentation

Alternatives considered

No response

Additional context

No response

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageNew issue awaiting maintainer review

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions