Debug an error message with AI step by step
A diagnostic workflow for using AI to understand an error, form hypotheses, test them one at a time, and avoid random code changes.
Who it is for
- Developers debugging unfamiliar errors.
- Beginners learning how to reason from stack traces.
- Teams that want clearer bug notes.
Who should skip it
- Users who cannot share logs safely.
- Incidents that need immediate expert response.
- Cases involving secrets in logs.
Workflow
Step 1
Clean the error report
Remove secrets and unrelated log noise, then provide the exact error, stack trace, environment, and recent change.
Example input
Here is the error, framework version, command, and last change. Explain likely causes.
Expected output
A safe, focused error report.
Common failure
The model diagnoses from incomplete or unsafe logs.
Human check
Check that no tokens, passwords, or private customer data are included.
Step 2
Ask for hypotheses, not fixes
Request ranked hypotheses with evidence from the error. This avoids immediate random patches.
Example input
Give three likely causes and what evidence supports each.
Expected output
A ranked hypothesis list.
Common failure
The assistant suggests a fix without explaining why.
Human check
Reject any fix that is not tied to a line of evidence.
Step 3
Design one test per hypothesis
Ask how to confirm or reject each hypothesis with the smallest command or code inspection.
Example input
For each hypothesis, give one minimal test and expected result.
Expected output
A test plan that avoids broad changes.
Common failure
Multiple changes are made before learning anything.
Human check
Run one test, record the result, then continue.
Step 4
Apply the smallest fix
After a hypothesis is confirmed, ask for the smallest fix and why it should work. Do not accept refactors disguised as fixes.
Example input
Hypothesis 2 is confirmed. Propose the smallest fix only.
Expected output
A limited fix with explanation.
Common failure
The model rewrites surrounding code.
Human check
Compare the diff against the confirmed cause.
Step 5
Write a bug note
Have AI summarize cause, fix, verification, and prevention. This turns debugging into reusable learning.
Example input
Write a bug note with cause, fix, verification, and prevention.
Expected output
A concise debugging record.
Common failure
The same bug returns because no one records the cause.
Human check
Check whether the note would help another developer reproduce the reasoning.
Human review checklist
- Check whether the AI output directly solves the original AI-assisted debugging instead of drifting into a generic answer.
- Verify all factual claims, dates, names, numbers, links, and quoted material against the original source or a trusted reference.
- Remove unsupported claims, filler language, repetitive transitions, and confident statements that do not have evidence.
- Compare the output with the intended reader, channel, and format before using it in public or sending it to another person.
- Keep a short note of the prompt, tool, input material, manual edits, and final decision so the workflow can be repeated.
Mistakes to avoid
- Starting the AI-assisted debugging workflow with a vague prompt and no acceptance criteria.
- Asking the model for a final answer before giving it source material, constraints, examples, or review rules.
- Treating a fluent answer as correct without checking source coverage, missing assumptions, and edge cases.
- Using the same prompt for research, writing, review, and final editing even though those are different jobs.
- Skipping the human review step because the first output looks polished.
Related AI skills
Choose the right AI tool for a task
A decision workflow for choosing an AI tool by task, input type, risk, review needs, deployment requirements, and failure cost instead of popularity or marketing claims.
Refactor code with AI without breaking context
A controlled coding workflow for using AI on refactors without handing it the whole repository or accepting broad, unreviewable changes.