hello-debug

Debugging-related work must follow these guidelines.

Before Coding

Do not fix directly without root cause analysis. First establish a runnable, repeatable, and judgeable feedback loop; without a feedback loop, do not directly guess the cause or change code.

Git as Memory

Before each debugging session, first read the relevant git history:

git log --oneline -20 View recent changes
git log --all --grep="revert" View past failed rollbacks
If it is found that a similar fix has already been attempted and rolled back before → do not repeat the same direction

Feedback Loop First

The feedback loop is the entry point for debugging and must be able to prove "the problem appears / the problem disappears":

Prefer writing a failing test; when writing a test is not suitable, reproduce with HTTP scripts, CLI sample inputs, browser scripts, request / event replay, minimal verification scripts, diff comparison, or stress loops
The loop should be as fast and stable as possible, assert the specific symptom, and not use "it did not crash" as a substitute for correctness
For nondeterministic problems, first increase the reproduction rate, and record the number of triggers, failure ratio, and key conditions
When a loop truly cannot be established, stop and explain the methods already attempted, and ask the user for logs, screen recordings, request records, environment access, or authorization to add temporary observation points

Four-Phase Debugging Method

1. Locate

Read the error message completely (do not truncate, do not guess)
Use the feedback loop to stably reproduce the problem (determine the trigger conditions)
Trace the data flow backward (trace upstream from the error point)

2. Analyze

Find similar code that works normally and compare the differences
Check recent changes (git log/diff)
Identify all implicit assumptions

3. Hypothesize

Form 3-5 hypotheses ordered by likelihood
Each hypothesis must be falsifiable: clearly state "if the cause is X, then changing or observing Y will produce Z"
Test one variable at a time (change only one thing at a time)
Record each attempt and result

4. Fix

First write a failing test to reproduce the bug
Implement the minimal fix (target the root cause, not the symptom)
Verify that the fix is effective and has no regressions

Temporary Observation Points

Temporary logs must carry a unique prefix, such as [DEBUG-a4f2]
Do not "print everywhere and then search"; each observation point must correspond to a hypothesis
Before wrapping up, search for the prefix and delete all temporary logs, temporary verification scripts, and experiment files; if they really need to be kept, move them to an explicit debug directory and explain why

Stuck Escalation Mechanism

When consecutive fix attempts fail, escalate according to the following ladder strategy:

Failure 1-2: Reflect normally and adjust the fix direction Failure 3: Stop. 3 failures mean it may be an architectural problem rather than a local bug. Restart from root cause analysis and question whether the current direction is correct Failure 4: Expand the scope—reread all relevant files, review relevant changes in git history, and check whether there are hidden dependencies or side effects Failure 5: Must discuss with the user. Propose the following options:

Combine previous attempts that were close to success
Try the completely opposite direction
Refactor the architecture instead of continuing local patching
Redefine the problem

More than 5 times: stop autonomous attempts and switch to user decision.

Delivery check

Root cause identified and recorded
Established a feedback loop that can prove the problem appears / disappears
There is a failing test that reproduces the bug, or it has been explained that there is no suitable test entry point and alternative verification has been provided
Single fix targets the root cause
Temporary observation points and experiment files have been cleaned up
No regression introduced