gsd-debug

Imported from Gustavosareto/gerenciador-de-quadras (.codex/skills/gsd-debug/SKILL.md). Install upstream with npx skills add Gustavosareto/gerenciador-de-quadras --skill gsd-debug. Copyright stays with the author.

<codex_skill_adapter>

A. Skill Invocation

• This skill is invoked by mentioning $gsd-debug.
• Treat all user text after $gsd-debug as {{GSD_ARGS}}.
• If no arguments are present, treat {{GSD_ARGS}} as empty.

B. AskUserQuestion → request_user_input Mapping

GSD workflows use AskUserQuestion (Claude Code syntax). Translate to Codex request_user_input:

Parameter mapping:

• header → header
• question → question
• Options formatted as "Label" — description → {label: "Label", description: "description"}
• Generate id from header: lowercase, replace spaces with underscores

Batched calls:

• AskUserQuestion([q1, q2]) → single request_user_input with multiple entries in questions[]

Multi-select workaround:

• Codex has no multiSelect. Use sequential single-selects, or present a numbered freeform list asking the user to enter comma-separated numbers.

Execute mode fallback:

• When request_user_input is rejected (Execute mode), present a plain-text numbered list and pick a reasonable default.

C. Task() → spawn_agent Mapping

GSD workflows use Task(...) (Claude Code syntax). Translate to Codex collaboration tools:

Direct mapping:

• Task(subagent_type="X", prompt="Y") → spawn_agent(agent_type="X", message="Y")
• Task(model="...") → omit (Codex uses per-role config, not inline model selection)
• fork_context: false by default — GSD agents load their own context via <files_to_read> blocks

Parallel fan-out:

• Spawn multiple agents → collect agent IDs → wait(ids) for all to complete

Result parsing:

• Look for structured markers in agent output: CHECKPOINT, PLAN COMPLETE, SUMMARY, etc.
• close_agent(id) after collecting results from each agent </codex_skill_adapter>

Orchestrator role: Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations.

Why subagent: Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.

Flags:

• --diagnose — Diagnose only. Find root cause without applying a fix. Returns a structured Root Cause Report. Use when you want to validate the diagnosis before committing to a fix.

<available_agent_types> Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):

• gsd-debugger — Diagnoses and fixes issues </available_agent_types>

Parse flags from {{GSD_ARGS}}:

• If --diagnose is present, set diagnose_only=true and remove the flag from the issue description.
• Otherwise, diagnose_only=false.

Check for active sessions:

ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5

0. Initialize Context

INIT=$(node "C:/Users/gusta/OneDrive/Documentos/gerenciador-de-quadras/.codex/get-shit-done/bin/gsd-tools.cjs" state load)
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

Extract commit_docs from init JSON. Resolve debugger model:

debugger_model=$(node "C:/Users/gusta/OneDrive/Documentos/gerenciador-de-quadras/.codex/get-shit-done/bin/gsd-tools.cjs" resolve-model gsd-debugger --raw)

1. Check Active Sessions

If active sessions exist AND no {{GSD_ARGS}}:

• List sessions with status, hypothesis, next action
• User picks number to resume OR describes new issue

If {{GSD_ARGS}} provided OR user describes new issue:

• Continue to symptom gathering

2. Gather Symptoms (if new issue)

Use AskUserQuestion for each:

1. Expected behavior - What should happen?
2. Actual behavior - What happens instead?
3. Error messages - Any errors? (paste or describe)
4. Timeline - When did this start? Ever worked?
5. Reproduction - How do you trigger it?

After all gathered, confirm ready to investigate.

3. Spawn gsd-debugger Agent

Fill prompt and spawn:

<objective>
Investigate issue: {slug}

**Summary:** {trigger}
</objective>

<symptoms>
expected: {expected}
actual: {actual}
errors: {errors}
reproduction: {reproduction}
timeline: {timeline}
</symptoms>

<mode>
symptoms_prefilled: true
goal: {if diagnose_only: "find_root_cause_only", else: "find_and_fix"}
</mode>

<debug_file>
Create: .planning/debug/{slug}.md
</debug_file>

Task(
  prompt=filled_prompt,
  subagent_type="gsd-debugger",
  model="{debugger_model}",
  description="Debug {slug}"
)

4. Handle Agent Return

If ## ROOT CAUSE FOUND (diagnose-only mode):

• Display root cause, confidence level, files involved, and suggested fix strategies
• Offer options:
  • "Fix now" — spawn a continuation agent with goal: find_and_fix to apply the fix (see step 5)
  • "Plan fix" — suggest /gsd-plan-phase --gaps
  • "Manual fix" — done

If ## DEBUG COMPLETE (find_and_fix mode):

• Display root cause and fix summary
• Offer options:
  • "Plan fix" — suggest /gsd-plan-phase --gaps if further work needed
  • "Done" — mark resolved

If ## CHECKPOINT REACHED:

• Present checkpoint details to user
• Get user response
• If checkpoint type is human-verify:
  • If user confirms fixed: continue so agent can finalize/resolve/archive
  • If user reports issues: continue so agent returns to investigation/fixing
• Spawn continuation agent (see step 5)

If ## INVESTIGATION INCONCLUSIVE:

• Show what was checked and eliminated
• Offer options:
  • "Continue investigating" - spawn new agent with additional context
  • "Manual investigation" - done
  • "Add more context" - gather more symptoms, spawn again

5. Spawn Continuation Agent (After Checkpoint or "Fix now")

When user responds to checkpoint OR selects "Fix now" from diagnose-only results, spawn fresh agent:

<objective>
Continue debugging {slug}. Evidence is in the debug file.
</objective>

<prior_state>
<files_to_read>
- .planning/debug/{slug}.md (Debug session state)
</files_to_read>
</prior_state>

<checkpoint_response>
**Type:** {checkpoint_type}
**Response:** {user_response}
</checkpoint_response>

<mode>
goal: find_and_fix
</mode>

Task(
  prompt=continuation_prompt,
  subagent_type="gsd-debugger",
  model="{debugger_model}",
  description="Continue debug {slug}"
)

<success_criteria>

• Active sessions checked
• Symptoms gathered (if new)
• gsd-debugger spawned with context
• Checkpoints handled correctly
• Root cause confirmed before fixing </success_criteria>