Troubleshooting

Run ana doctor. It checks five dimensions — CLI version, scan freshness, context quality, skill enrichment, and proof chain health — and prints a single dashboard. Use ana doctor --json for CI or structured output. Fix any red (✗) items it surfaces before running the pipeline.

1. Run from your project root, not a subdirectory or a worktree
2. Git must be configured: git status must succeed, git config user.name and user.email must be set
3. Node 22+ required (node --version) — declared in package.json but not checked at runtime, so older versions produce cryptic errors
4. If a prior init was interrupted, you'll see "Found incomplete init from a previous run" — follow the recovery steps it prints
5. If re-initializing: ana init --force skips confirmation prompts but still preserves your data

Install dependencies first (npm install / pnpm install). Without node_modules/, convention detection (formatting, import patterns) is limited — init warns you. Framework and database detection reads package.json dependencies directly. An empty repo with no commits limits detection — commit at least once. If tree-sitter analysis failed, init shows a warning with what was missed.

Scan detects from your dependency manifest and reports the first match when multiple options exist. If a dependency is listed but unused, you'll see inaccurate detection. This doesn't affect your code — it affects what agents know about your stack. To correct: edit .ana/context/project-context.md (the file agents actually read for architecture decisions). To reduce noise on future scans, remove unused dependencies from your manifest. If wrong gotchas were seeded during init, edit or remove them from .claude/skills/{name}/SKILL.md under the Gotchas section.

Setup's quality depends on your answers. Don't describe your stack — describe your product, your users, the problem you solve. Take your time on design principles. You can always re-run: delete setupPhase from ana.json and run claude --agent ana-setup again. See Using ana-setup for how to give great answers.

Anatomia scans the full repository, not individual packages. Init detects surfaces (packages that qualify as development targets) and generates per-surface commands. commands.test and commands.build are project-wide by default. To scope pipeline work to a specific surface, use surfaces.{name}.commands.test and surfaces.{name}.commands.build. Override with ana config set surfaces.cli.commands.test "your-command".

FAIL means Verify found issues — this is the pipeline working as designed. 22 of our 163 proofs had rejection cycles.

1. Read verify_report.md. It lists every UNSATISFIED assertion with evidence.
2. Common causes: test tagged @ana A003 but doesn't actually test what the contract says, missing test tags, tests that pass on both correct and incorrect implementations.
3. Run claude --agent ana-build to fix. Build reads the verify report and addresses each failure.
4. Re-run claude --agent ana-verify.

1. Large specs can exceed the model's context window. Try multi-phase specs for big changes.
2. ana work status shows pipeline state. If build is "in-progress," the previous session may have crashed — re-open claude --agent ana-build and it resumes.
3. Check if tests are hanging. Vitest defaults to watch mode — the test command must include --run.
4. If Claude Code itself stops responding, check your subscription status and API rate limits — these aren't Anatomia failures but they surface during pipeline runs.

1. Database or service not running. Pipeline agents run your test command exactly as configured. If tests need PostgreSQL, Redis, or Docker — start them first.
2. Missing environment variables. .env files aren't loaded automatically in all test runners. Check that CI-required vars are set in your shell.
3. Wrong test command detected. Run ana config show — check commands.test (project-wide) and surfaces.{name}.commands.test (per-surface). Override: ana config set commands.test "your-command".
4. Prisma client not generated. If using Prisma, run npx prisma generate before the pipeline. Some test setups require this explicitly.
5. Monorepo surface mismatch. Init may target the wrong package. See the monorepo troubleshooting card above for per-surface command overrides.

Usually means the spec was too vague. Vague specs produce vague implementations, and Verify finds more to fault. Tighten the scope, write more specific acceptance criteria, and re-plan. A good contract has 15–30 assertions. Over 40 suggests the scope should be split.

Must run from the main project directory on the artifact branch (usually main), not from inside a worktree. If using --merge: requires gh CLI, requires a PR to exist, and branch protection rules on GitHub can block the merge. Without --merge: merge the PR on GitHub first, then run ana work complete <slug>.

The contract was satisfied but the behavior is wrong — the contract didn't cover what matters. An assertion that checks toBeDefined() passes on garbage output. This isn't a system failure — the verification proved the contract was met. The contract was underspecified. Next cycle: write assertions with specific values and matchers. Check: does every assertion test the behavior users would notice if broken?

Commands that modify the proof chain (close, promote, strengthen) require the artifact branch (usually main). Read-only commands (proof, audit, health, stale, context) work from any branch. If you see "Wrong branch," check: are you in a worktree? Run proof-modifying commands from the main project directory.

Deleted .ana/? Proof chain history and archived artifacts are gone permanently. ana init regenerates scan data and scaffolds but cannot recover proofs, context, or design principles. Deleted .claude/? Enriched skill rules are gone. ana init regenerates templates but enrichments need re-running setup. Prevention: run ana init instead of deleting — it refreshes everything and preserves your data.

Remove Anatomia's generated content: rm -rf .ana .claude/agents .claude/skills AGENTS.md. If Anatomia created your CLAUDE.md, remove it too (check git log --oneline CLAUDE.md). Keep .claude/settings.json and .claude/agent-memory/ if you use Claude Code — those are Claude Code native, not Anatomia. If you committed with ana init commit, revert: git revert <commit-hash>. Your source code is never modified — only infrastructure files.

Active work: .ana/plans/active/. Completed: .ana/plans/completed/ and proof_chain.json. Run ana proof to see all entries. Run ana proof <slug> for details on a specific one.

The pipeline creates PRs via ana pr create, which uses gh under the hood. If gh isn't installed or authenticated, PR creation fails but everything else works — Build, Verify, and the proof chain are independent of GitHub. Install from cli.github.com, then gh auth login.

If ana work status or ana doctor shows a version mismatch between your CLI and the project's anaVersion, run ana init to update the project to your CLI version. This refreshes scan data and templates while preserving your context and proof chain.