When bassclef breaks at 2am

Six named failure classes. Each carries a symptom, a diagnose command, an expected output, and the recovery step.

Use this when

Something bassclef is supposed to do is not happening, or a session just did something you did not expect. Look for the symptom that matches your case. Run the diagnose command. Compare against the expected output. Follow the recovery step.

Skip this when

You are evaluating bassclef or reading the docs for fun. This page is for the moment things break. Bookmark it now so you can find it later.

The six classes

Session-start hook did not fire

Symptom: Claude Code opens but no BLOCKED banner appears, no whereami read, no substrate sync. The session feels like a fresh clone with no bassclef wiring.
Diagnose: cat ~/.claude/settings.json | jq '.hooks.SessionStart'
Expected output: An array with at least one entry pointing at bassclef-sync.sh or a dispatcher path
Recovery: Run bassclef check to see which hooks are wired. If the SessionStart entry is missing, run bassclef initagain in the repo root. If bassclef check itself is not found, reinstall the CLI.

Skill dispatches but produces no output

Symptom: You type /riff or /launch and Claude answers as if the skill is not there. No skill-specific procedure runs. Claude falls back to freeform text.
Diagnose: ls ~/.claude/skills/riff/SKILL.md
Expected output: A file listing that shows the SKILL.md exists at the expected path
Recovery: The symlink is broken or the skill was not synced. Run bassclef sync to re-symlink from the bassclef release. If the symlink target is a version you did not want, edit .bassclef-source.json and set the version explicitly.

Hook silently blocks work

Symptom: Claude tries to edit a file and the edit does not happen. No error appears in the response. Claude keeps going as if the edit succeeded.
Diagnose: tail -50 ~/.claude/logs/hook-trace.log
Expected output: A recent entry naming the hook that fired, the tool it blocked, and the reason
Recovery: Read the hook name in the trace log. Find the matching rule under .claude/rules/ — the rule body carries the override env var (usually SKIP_<NAME>=1). Set the override for your next call if the block is a false-positive, or fix the underlying condition the hook is checking.

Auto-sync fetched a broken release

Symptom: A session that worked yesterday breaks today. New errors appear about missing skills, missing rules, or hooks that reference paths that do not exist.
Diagnose: cat .bassclef-source.json && ls -la ~/.claude/skills/ | head
Expected output: A source config with a version pinned, and skill symlinks pointing at the fetched release directory
Recovery: Set auto_sync: false in .bassclef-source.json, pin an explicit version that worked (see the release feed for the last known-good tag), and re-run bassclef sync. Report the broken release on GitHub Issues so upstream can fix it.

State-spine schema validation fails on write

Symptom: Something tries to update whereami or a marker and the write is refused with an ajv error about missing or extra fields.
Diagnose: bash .claude/hooks/state-validate.sh <path-to-file>
Expected output: Either PASS or a specific error naming the failing field and the schema constraint
Recovery: Fix the field to match the schema, or update the schema if it is genuinely wrong (that requires a PR). For a one-off migration, set SKIP_STATE_VALIDATE=1 — logged to trace; use rarely. Full detail at the rule doc.

Session ended abruptly and left work uncommitted

Symptom: Next session starts with a BLOCKED banner about a session-rescue file in docs/deferred-actions/. The rescue file names an unfinished obligation from the prior session.
Diagnose: ls docs/deferred-actions/ | grep session-rescue
Expected output: One or more *-session-rescue.md files
Recovery: Read the rescue file's body. Run /session-end to complete the flagged obligations. If the rescue was a false-positive (work was actually done), Pattern B applies — git mv docs/deferred-actions/<file> docs/deferred-actions/completed/. Commit with a note explaining the false-positive reason.

Something else broke

If your symptom is not on this page, file an issue with the diagnose output attached: Report an issue on GitHub. The page grows as new classes surface.