debug-cycle

Debug Cycle - PDCA Framework

Overview

A systematic, platform-agnostic approach to debugging using the PDCA (Plan-Do-Check-Act) cycle. This methodology provides a structured workflow for forming hypotheses, adding instrumentation, analyzing behavior, and iterating until root cause identification.

When to Use

• Debugging issues that require observation of runtime behavior
• Investigating problems that cannot be determined through static analysis alone
• Verifying that a fix actually resolves the issue
• Understanding data flow through complex systems
• Troubleshooting intermittent or timing-related bugs
• Any scenario where "guess and check" has failed

The PDCA Cycle

Phase 1: Plan (Hypothesis Formation)

Objective: Form a testable hypothesis about the root cause.

Steps:

1. Document the symptom - Describe the observed behavior precisely
2. Form a hypothesis - What specific condition might cause this?
3. Identify data points - What values/states would confirm or refute the hypothesis?
4. Determine instrumentation points - Where should debug output be added?

Hypothesis Template:

Symptom: [Precisely what is happening]
Expected: [What should happen instead]
Hypothesis: [Specific cause I believe is responsible]
Data needed: [Values/states to capture]
Instrumentation points: [Files, methods, lines to add logging]

Good vs Bad Hypotheses:

Bad (Vague)	Good (Specific)
"Something is wrong with the data"	"The user ID is null when passed to fetchProfile()"
"The UI isn't updating"	"setState is not being called after the API response"
"It's slow"	"The database query is executing N+1 times in the loop"

Phase 2: Do (Instrument & Build)

Objective: Add targeted instrumentation to capture the data needed.

Steps:

1. Add debug logs at identified points
2. Include contextual information:
   • Variable values at decision points
   • Method entry/exit with parameters and return values
   • Which conditional branch was taken
   • State before and after changes
3. Build and deploy the instrumented code
4. Use hot reload/restart when available for faster iteration

Log Naming Convention:

[ClassName] methodName: description key=value

Essential Logging Points:

• Method entry with parameters
• Conditional branch decisions
• Loop iterations (with index/count)
• Exception catch blocks
• State mutations
• Async operation start/complete

Phase 3: Check (Observe & Analyze)

Objective: Collect and analyze data to evaluate the hypothesis.

Steps:

1. Reproduce the scenario that triggers the issue
2. Capture all output - logs, screenshots, error messages
3. Analyze the data:
   • Compare actual values vs expected values
   • Identify the exact point where behavior diverges
   • Note any unexpected states, ordering, or timing
4. Document findings with evidence

Analysis Questions:

• At what point does actual behavior diverge from expected?
• Are there any null/undefined values where data was expected?
• Is the execution order what was expected?
• Are there any race conditions or timing issues?

Phase 4: Act (Decide Next Action)

Objective: Based on analysis, determine the appropriate next step.

Decision Matrix:

Result	Evidence	Action
Hypothesis CONFIRMED	Logs show exact predicted cause	Implement fix, then verify with new cycle
Hypothesis REFUTED	Logs show different behavior than predicted	Form new hypothesis based on actual findings
INCONCLUSIVE	Not enough data to determine	Add more granular logging, narrow scope
Root cause FOUND & FIXED	Fix applied, issue no longer reproduces	Remove debug logs, document solution
New issue DISCOVERED	Logs reveal separate problem	Create new hypothesis for new issue

Cycle Iteration Rules

1. One hypothesis per cycle - Test only one thing at a time
2. Narrow, don't widen - Each cycle should focus on a smaller scope
3. Evidence-based pivots - New hypotheses must be based on observed data
4. Maximum 5 cycles - If not solved, step back and reconsider approach
5. Document everything - Keep a log of all cycles for future reference

Common Anti-patterns

Anti-pattern	Problem	Better Approach
"Shotgun debugging"	Changing multiple things at once	Change one thing, test, repeat
"Hypothesis-free" logging	Adding random logs hoping to find something	Form specific hypothesis first
"Premature fixing"	Implementing fix before confirming cause	Complete the Check phase first
"Ignoring inconclusive"	Assuming no news is good news	Add more instrumentation
"Forgetting cleanup"	Leaving debug code in production	Remove logs after resolution

Integration with Other Skills

• debug-log-patterns: Language-specific logging syntax and patterns
• mobile-debug-tools: MCP tools for mobile device interaction and log retrieval

Quick Reference Card

PLAN:  Symptom -> Hypothesis -> Data needed -> Log points
DO:    Add logs -> Build -> Deploy
CHECK: Reproduce -> Capture -> Analyze -> Document
ACT:   Confirmed? -> Fix | Refuted? -> New hypothesis | Unclear? -> More logs