What is spec-troubleshoot?

A troubleshooting command for the Vibe-Spec web-development setup. It connects an error or symptom to a likely cause and suggests a fix, asking before it changes anything.

Use it to check versions, services, ports, environment setup, database connections, generated Prisma files, lint and test gates, and commit hooks.

It reduces guesswork when installed tools, databases, Prisma, linting, tests, or Git hooks fail.

spec-troubleshoot — Command for Claude Code by Connorrmcd6

Install

Getting it into your agent

This one installs as part of its plugin. Adding the marketplace and installing the plugin brings it with everything else the plugin ships.

Claude Code

/plugin marketplace add Connorrmcd6/vibe-spec

Claude Code

/plugin install vibe-spec

Made for: Claude Code.

Or install vibe-spec, the plugin that ships this one along with the rest of its 1 skill, 9 commands.

Wrote this? Show the measurements

A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.

README.md

[![agentmods](https://agentmods.dev/badge/commands/connorrmcd6/vibe-spec/spec-troubleshoot/github.svg)](https://agentmods.dev/commands/connorrmcd6/vibe-spec/spec-troubleshoot)

Your own site

<a href="https://agentmods.dev/commands/connorrmcd6/vibe-spec/spec-troubleshoot"><img src="https://agentmods.dev/badge/commands/connorrmcd6/vibe-spec/spec-troubleshoot/github.svg" alt="Measured on agentmods" height="20"></a>

Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.

Your own site · 80×15

<a href="https://agentmods.dev/commands/connorrmcd6/vibe-spec/spec-troubleshoot"><img src="https://agentmods.dev/badge/commands/connorrmcd6/vibe-spec/spec-troubleshoot.svg" alt="Reviewed on agentmods" width="80" height="20"></a>

Per session 50 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 941 The whole file, excluding the scripts and references it only reads on demand.

Security scan B 1 finding. A grade says what 26 rules found in the file — not that it is safe.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5.1	$0.00050	$0.00941
Opus 5	$0.00025	$0.00470
Sonnet 5	$0.00010	$0.00188
Haiku 4.5	$0.00005	$0.00094

Measured 8d ago against content hash e400f0c1e5b0, method: parsed. Prices are Anthropic first-party input rates as of 2026-09-08, from the pricing page.

Security

Grade B, and why

spec-troubleshoot scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 8d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Asks for rootmediumPrivilege escalation

A mod that escalates privileges can change anything on the machine, not only the project.

daemon (Docker Desktop / `colima start` / `sudo systemctl start docker`). → `03-docker`

commands/spec-troubleshoot.md · 57 lines

How it starts

The opening of the file, as written. The whole thing — 57 lines — stays where its author put it; the contents beside it link to each section on GitHub.

You are running /spec-troubleshoot: a symptom → cause → fix diagnostician for the Vibe-Spec stack. Consult the vibe-spec skill — start with ${CLAUDE_PLUGIN_ROOT}/skills/vibe-spec/reference/18-prerequisites.md, then load the specific reference for the failing area (e.g. Prisma ⇒ 05-prisma + 04-database; local DB ⇒ 03-docker; lint/test ⇒ 10-testing / 14-ci-cd; commit hooks ⇒ 15-pre-commit).

Hard rules

Diagnostics may run freely (read-only). Confirm with the user before running any command that changes state (e.g. docker compose up -d, pnpm install, pnpm prisma generate, editing files).
One fix at a time; re-check after each.

What to do

If $ARGUMENTS is empty, ask what's going wrong or offer the common categories below. If they pasted an error, parse it for the failing tool/area.
Run targeted read-only diagnostics for the suspected area (daemon status, port in use, env var present, versions, install/generate state).
Map to a known cause and propose a fix, then confirm before running it. Re-run the diagnostic to verify it's resolved. Link the relevant reference.

Common failures catalog

For each: how to confirm → fix → reference.

pnpm: command not found — confirm pnpm --version fails → install via Corepack (corepack enable); if it's an npm/pnpm mix-up, note pnpm-not-npm. → 18-prerequisites, 01-scaffolding
uv / docker not found — confirm with --version → install per 18-prerequisites (point to /spec-setup). → 18-prerequisites
Cannot connect to the Docker daemon — docker info exits non-zero → start the daemon (Docker Desktop / colima start / sudo systemctl start docker). → 03-docker
Postgres port 5432 already in use — lsof -i :5432 (or docker ps) shows a conflict → stop the other Postgres or remap the host port in docker-compose.yml. → 03-docker
DB connection refused / DATABASE_URL missing or wrong — check .env has DATABASE_URL and the container is up (docker compose ps) → fix the URL / start the DB. → 03-docker, 04-database
Prisma: client not generated / @prisma/client did not initialize / src/generated missing — run pnpm prisma generate; for schema drift pnpm prisma migrate dev. → 05-prisma
pnpm vs npm lockfile mismatch (package-lock.json present, or "lockfile out of date") — remove package-lock.json, use pnpm install. → 01-scaffolding
Node version too old (engine warnings, build failures) — node --version below LTS → switch with fnm use --lts / nvm use --lts. → 18-prerequisites, 01-scaffolding
Git hooks not running (lint/format didn't fire on commit) — git config core.hooksPath is unset → run pnpm run prepare (sets core.hooksPath .githooks). → 15-pre-commit
Lint/test gate failing — run pnpm lint / pnpm test to see the real error; surface it before guessing. → 10-testing, 14-ci-cd

Read the full file on GitHub · 57 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

8d ago First seen · 57 lines · 50 tokens per session scan B e400f0c1e5b0

Subscribe to this mod's changes

spec-troubleshoot is a command published in the GitHub repository Connorrmcd6/vibe-spec (9 stars, last pushed 2mo ago), licensed MIT. It adds 50 tokens to every session and 941 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it B with 1 finding (asks for root). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Claude Code Debugging ai-assisted-development nextjs postgresql prisma spec-driven

spec-troubleshoot

Getting it into your agent

Wrote this? Show the measurements

What it costs to keep this loaded

Grade B, and why

Asks for rootmediumPrivilege escalation

How it starts

Hard rules

What to do

Common failures catalog

What this file has done since we first saw it

Other commands, from other repositories

magic-wand

clean-code

fix

cleanup-repo

brainstorm

devops