| name | dev-sanity |
| description | Run a mode-driven local development health check across repos, env files, containers, and health endpoints. Use for "dev sanity", "what's broken locally", "check my local stack", "startup checks", "service status", or "why won't this local environment boot". |
Dev Sanity
Check whether a local development environment is wired correctly before you
start deeper debugging.
This skill is for local environment health, not production operations.
Default Marker
Start with a stable first progress update such as:
Using dev-sanity to run the configured local checks and surface the first real failure.
Private Mode Overlay
This skill expects a gitignored shell config at modes/config.sh.
The private mode defines one or more of these Bash arrays:
- repo paths to verify
- env files that must exist
- docker container names
- local health endpoints
Copy references/mode-template.md into
modes/config.sh, fill in your stack, and keep it untracked. Track only
generic examples and placeholders in this skill.
The helper also accepts DEV_SANITY_MODE_FILE=/abs/path/to/config.sh or
--mode-file /abs/path/to/config.sh when the mode file lives elsewhere.
If the mode file is missing, stop and point the operator at the template. Do
not guess repo roots.
On Trigger
Resolve the bundled script path, then run it immediately:
bash scripts/sanity_check.sh
For narrower requests, use the focused modes first:
bash scripts/sanity_check.sh --mode-file /abs/path/to/config.sh
bash scripts/sanity_check.sh --repos-only
bash scripts/sanity_check.sh --env-only
bash scripts/sanity_check.sh --docker-only
bash scripts/sanity_check.sh --health-only
Any check group may be omitted from the mode file when it does not apply to the
current stack.
What To Report
Summarize only:
- what passed
- what failed
- the first likely root cause
- the next exact command to run
Do not bury the first failure under a full wall of green checks.
Fixing Failures
Missing repo
- confirm the path in
modes/config.sh
- clone or restore the repo before continuing
Missing env file
- regenerate it from the environment manager or repo bootstrap flow
- if the env file is intentionally optional, remove it from the mode config
Missing container
- start the relevant local stack
- if the service is no longer containerized, remove it from the mode config
- if Docker itself is unavailable, install or start Docker before debugging the
app layer
Failing health endpoint
- inspect the app logs for that service
- verify the configured local port matches the service that is actually running
- check env wiring before assuming the app code is broken
- if
curl is missing, install it or use an equivalent HTTP probe command
Validation
Before shipping changes to this skill:
SKILLS_ROOT="/path/to/skills/root"
python3 "$SKILLS_ROOT/skill-issue/scripts/quick_validate.py" "$SKILLS_ROOT/dev-sanity"
bash "$SKILLS_ROOT/dev-sanity/scripts/sanity_check.sh" >/tmp/dev-sanity.out 2>/tmp/dev-sanity.err || true
head -n 2 /tmp/dev-sanity.out /tmp/dev-sanity.err
The helper should fail cleanly with a missing-mode message when no private mode
exists and should return non-zero when a configured check fails.
