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