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/, or DEPLOYMENT_PLAN.md in an older project;
  • README, docker-compose*.yml, Dockerfile, the CI workflows, and .env.example;
  • the technical specs, and CLAUDE.md or AGENTS.md.
Installs
31
GitHub Stars
9
First Seen
Jul 27, 2026