troubleshooting
Installation
SKILL.md
Troubleshooting Guide
A troubleshooting guide is as good as the failures it knows. Before real incidents exist, this skill works from the architecture. It finds where this system most likely breaks, at its seams, and seeds an entry for each. Say plainly that the result is a skeleton. Real incidents replace guesses over time.
Two phases: map the seams with the user, then write the guide by symptom.
Phase 1: Map the seams
Read the repo first. Ask only what the files cannot tell you. Read:
docs/deployment-plan/, orDEPLOYMENT_PLAN.mdin an older project;README,docker-compose*.yml,Dockerfile, the CI workflows, and.env.example;- the technical specs, and
CLAUDE.mdorAGENTS.md.