gsd-debug
GitHub基于科学方法的系统化调试技能，通过子代理隔离上下文以高效排查问题。支持会话恢复、症状收集及自动化诊断修复，保持主上下文轻量。
Trigger Scenarios
Install
npx skills add NeverSight/learn-skills.dev --skill gsd-debug -g -y
SKILL.md
Frontmatter
{
"name": "gsd-debug",
"description": "Systematic debugging with persistent state across context resets"
}
<cursor_skill_adapter>
A. Skill Invocation
- This skill is invoked when the user mentions
gsd-debugor describes a task matching this skill. - Treat all user text after the skill mention as
{{GSD_ARGS}}. - If no arguments are present, treat
{{GSD_ARGS}}as empty.
B. User Prompting
When the workflow needs user input, prompt the user conversationally:
- Present options as a numbered list in your response text
- Ask the user to reply with their choice
- For multi-select, ask for comma-separated numbers
C. Tool Usage
Use these Cursor tools when executing GSD workflows:
Shellfor running commands (terminal operations)StrReplacefor editing existing filesRead,Write,Glob,Grep,Task,WebSearch,WebFetch,TodoWriteas needed
D. Subagent Spawning
When the workflow needs to spawn a subagent:
- Use
Task(subagent_type="generalPurpose", ...) - The
modelparameter maps to Cursor's model options (e.g., "fast") </cursor_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.
<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>
Check for active sessions:
ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5
0. Initialize Context
INIT=$(node "D:/code/Project/tablez-demo2-allByAi/.cursor/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 "D:/code/Project/tablez-demo2-allByAi/.cursor/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 conversational prompting for each:
- Expected behavior - What should happen?
- Actual behavior - What happens instead?
- Error messages - Any errors? (paste or describe)
- Timeline - When did this start? Ever worked?
- 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: 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:
- Display root cause and evidence summary
- Offer options:
- "Fix now" - spawn fix subagent
- "Plan fix" - suggest /gsd-plan-phase --gaps
- "Manual fix" - done
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)
When user responds to checkpoint, 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>
Version History
- e0220ca Current 2026-07-05 23:23
