Skip to content

plan-phase: stall-detection config key easy to mis-guess; key not named at use sites #5451

Open

Description

@trek-e

Summary

During /gsd-plan-phase 1 on a freshly created project, the orchestrator ran gsd-tools query config-get workflow.plan_stall_detection, which exited 1 with Error: Key not found: workflow.plan_stall_detection. The error was not investigated at the time and the planner was launched in the background without gsd_stall_watch polling.

Root cause (mostly orchestrator error, with small upstream friction points)

  • The key does not exist. The real key is planner.stall_detection_enabled (default true). The orchestrator guessed workflow.plan_stall_detection from the variable name PLANNER_STALL_DETECTION_ENABLED used in plan-phase.md steps 8, 10 and 12.
  • The correct key and gsd_stall_watch are defined in workflows/plan-phase/steps/stall-detection-helpers.md (step 7.99), which the orchestrator skipped. The spec does state the key, but only in the helper, not at the points of use.
  • Stall detection was not broken on the new install: config-get planner.stall_detection_enabled returned true via the default, and the helper falls back to true. The project's .planning/config.json simply has no planner block.

Suggestions (not demonstrated defects)

  1. plan-phase.md mentions PLANNER_STALL_DETECTION_ENABLED at steps 8, 10 and 12 without naming planner.stall_detection_enabled inline. A one-line pointer to the config key (or to step 7.99) at each "Dispatch/wait gate" would make a guessed key less likely.
  2. config-get on an unknown key could suggest the nearest valid key. config-set already lists all valid keys on rejection; config-get only says Key not found.
  3. Consider whether new-project should seed planner.* defaults into .planning/config.json, so effective settings are visible. Behavior is already correct via defaults, so this is a visibility choice.

Environment

gsd-core installed under the user's Claude config directory; Claude Code runtime; macOS. Paths redacted.

Activity

  1. trek-e commented on Oct 16, 2026

    @trek-e
    CollaboratorAuthor

    AI Disclaimer: This comment was generated by an AI agent.

    Diagnosis

    The root cause is a lack of explicit configuration key naming at the points of use in gsd-core/workflows/plan-phase.md. While the correct key (planner.stall_detection_enabled) is defined in the helper file gsd-core/workflows/plan-phase/steps/stall-detection-helpers.md, the main workflow refers to the resulting variable PLANNER_STALL_DETECTION_ENABLED without naming the key. This leads orchestrators to guess incorrect keys (e.g., workflow.plan_stall_detection) when attempting to resolve the configuration.

    Full diagnosis artifact created at .gsd/triage/20-diagnosis/5451.md.

  2. trek-e commented on Oct 16, 2026

    @trek-e
    CollaboratorAuthor

    AI Disclaimer: This comment was generated by an AI agent.

    Agent Brief

    The orchestrator is prone to guessing the wrong configuration key for planner stall detection because plan-phase.md refers to a variable (PLANNER_STALL_DETECTION_ENABLED) without explicitly naming the underlying config key (planner.stall_detection_enabled).

    To fix this, the workflow should be updated to explicitly name the config key or provide a direct pointer to the helper step where the key is defined at every point of use. This removes the need for orchestrator guesswork and prevents Key not found errors during execution.

  3. added
    bugSomething isn't working
    and removed
    needs-triageNew issue awaiting maintainer review
    on Oct 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingconfirmed-bugVerified reproducible bug

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions