Building Debugging Playbooks

A debugging playbook is a codified diagnosis path for a specific class of errors. When a developer on your team encounters "ECONNREFUSED on the database," they should not be guessing. The playbook says: check if the database container is running (docker ps), check the connection string (echo $DATABASE_URL), check the network (ping db-host), check credentials (psql -U user -h host). Four steps, two minutes, diagnosis complete.

Claude Code accelerates playbook creation. After you debug a non-trivial issue, tell Claude: "Document the debugging steps we just followed as a playbook. Include the symptoms, the diagnosis steps in order, the root cause, and the fix." Claude produces a structured playbook from the session history. Add it to your project wiki or to a debugging/ directory in the repository. The next developer who hits the same error — or the next Claude Code session — has a ready-made diagnosis path.

## Symptom: ECONNREFUSED on database connection

### Diagnosis Steps
1. Verify database is running: `docker ps | grep postgres`
2. Check connection string: `echo $DATABASE_URL`
3. Test network connectivity: `pg_isready -h $DB_HOST -p $DB_PORT`
4. Test credentials: `psql $DATABASE_URL -c "SELECT 1"`

### Common Root Causes
- Container not started after reboot
- Connection string points to wrong port
- Firewall blocking connection
- Credentials rotated but env not updated