| name | process-troubleshooting |
| description | Five-scenario workflow troubleshooting guide for diagnosing and fixing common orchestration failure patterns. Use when diagnosing premature implementation, agent confusion, validation gaps, documentation conflicts, or terminal stalls during a workflow session. DO NOT USE FOR: general code review (use code-review-intake), debugging application code (use systematic-debugging), or post-merge cleanup (use post-pr-review). |
Process Troubleshooting
Diagnostic workflows for common orchestration failure patterns.
When to Use
- Code was created before tests existed
- Multiple agents handled the same phase or overlapping roles
- Quality gate failures were discovered late in the workflow
- Contradictory instructions are causing confusion
- An agent is blocked by a long-running or hung terminal command
Scenario 1: Premature Implementation
Symptoms: Code created before tests, implementations in test-writer mode
Analysis:
- Check git log: Were
.ts files created before .test.ts files?
- Review plan: Did phase headers show test-writer → code-smith order?
- Check conversation: Was TDD flow mentioned?
Recommendations:
- Add explicit RED state validation
- Strengthen test-writer → code-smith handoff
- Create TDD checklist for issue-planner
Scenario 2: Agent Confusion
Symptoms: Multiple agents handling same phase, role overlap
Analysis:
- Review agent descriptions: Are boundaries clear?
- Check plan: Were agent assignments explicit?
- Examine handoffs: Were handoff buttons used?
Recommendations:
- Clarify agent responsibilities
- Add phase-to-agent mapping table
- Create decision tree for agent selection
Scenario 3: Validation Gaps
Symptoms: Quality gate failures discovered late, rework needed
Analysis:
- Check when tests were run: After each task or only at end?
- Review phase completion: Were validation commands listed?
- Examine changes file: Were validation results recorded?
Recommendations:
- Add validation checklist to plan-tracking
- Require validation output in changes file
- Create pre-handoff validation step
Scenario 4: Documentation Conflicts
Symptoms: Contradictory instructions, confusion about standards
Analysis:
- Search for duplicate topics in workspace docs: Use
grep_search with query subject and includePattern: "**/*.md". For session memory, use the vscode/memory tool (view /memories/session/ then read individual files) to check for overlapping topics.
- Check file ages: Which is canonical?
- Review references: Which files link to which?
Recommendations:
- Consolidate redundant files
- Establish clear hierarchy (primary vs reference)
- Add cross-reference validation
Scenario 5: Terminal Stall During Workflow
Symptoms: Agent appears blocked by long-running or hung terminal commands
Analysis:
- Check terminal history for repeated commands with no output progress
- Review whether timeout boundaries were set or adjusted
- Verify whether escalation happened after repeated stalls
Recommendations:
- Add timeout defaults and retry limits in workflow instructions
- Introduce a "stall triage" checklist before rerunning commands
- Require fallback path documentation when terminal automation is unavailable
Gotchas
| Trigger | Gotcha | Fix |
|---|
| Diagnosing premature implementation without checking git log dates | Incorrectly attributes cause to agent confusion rather than sequencing failure | Check git log --diff-filter=A --name-only to verify creation order |
| Treating contradictory instructions as a single-file problem | Root cause may span multiple agents and instruction files | Search workspace-wide before proposing consolidation |
| Fixing terminal stalls by rerunning the same command | Repeated retries accumulate output buffer and mask the underlying block | Switch to isBackground: true and check output with execute/getTerminalOutput |
| Assuming agent confusion caused a validation gap | May have been missing validation commands in the plan, not role overlap | Check the plan file: were validation steps present and ordered correctly? |
| Applying scenario fixes without updating the plan for next time | Same pattern recurs on next issue | Route systemic improvements to the plan template or instruction file via Process-Review |
