Debugging Way

Source: hooks/ways/softwaredev/environment/debugging/debugging.md

Frontmatter

Field	Value
description	debugging, troubleshooting failures, investigating broken behavior
vocabulary	debug debugging troubleshoot troubleshooting stack trace stacktrace backtrace add logging tracing root cause reproduce reproduction bisect regression crash crashes segfault exception panic core dump breakpoint bug
refire	0.15
scope	agent, subagent

Before Changing Any Code

1. Read the full error message and stack trace
2. Search the codebase for the error string
3. Check recent changes: git log --oneline -10 and git diff HEAD~3
4. Reproduce the issue — if you can't trigger it, you can't verify a fix

Do Not

• Change code based on guessing — verify the root cause first
• Fix multiple things at once — one change, one test
• Assume the bug is where the error appears — trace back to the source

When Stuck

• git bisect start / git bisect bad / git bisect good <ref> to find the introducing commit
• Add targeted logging at function boundaries, not scattered everywhere
• Check the obvious: typos, wrong file, stale cache, wrong branch, missing env var