sonder-debugging-playbook

Diagnose Sonder Runtime failures with ranked causes and discriminating experiments per symptom.

6|3|Updated Jul 3, 2026
One-click install
npx skills add https://github.com/Krilliac/Sonder-runtime --skill sonder-debugging-playbook-krilliac
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: sonder-debugging-playbook
Source: https://github.com/Krilliac/Sonder-runtime/tree/main/.claude/skills/sonder-debugging-playbook
Command: npx skills add https://github.com/Krilliac/Sonder-runtime --skill sonder-debugging-playbook-krilliac

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When the Sonder Runtime breaks — tests fail with connection refused, the server won't start, Ollama is unreachable, or a database locks — engineers waste time guessing causes. This Skill maps each known failure symptom to ranked likely causes plus the cheapest discriminating experiment that splits hypothesis A from B. ## Core Features & Use Cases - Symptom-to-fix triage index: Thirteen sections covering test failures, import errors, server startup, doctor/preflight checks, Ollama connectivity, database locks, disk exhaustion, selfmod breakage, and Windows encoding issues. - Discriminating experiments: Each section gives the cheapest command that distinguishes competing hypotheses, with what each outcome means. - Runbook pointers and provenance: Links to docs/runbooks/ procedures and grep commands to re-verify volatile claims against the codebase. - Use Case: A developer sees "database is locked" during a test run. The Skill directs them to identify the store, run PRAGMA integrity_check on a stopped service to distinguish lock contention from corruption, then follow the appropriate runbook. ## Quick Start Ask the assistant to triage why the Sonder server won't start or why tests fail with connection refused, and it will walk through the ranked causes and discriminating commands.

Frequently Asked Questions about sonder-debugging-playbook

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Sonder tests failing with connection refused on port 1?

Connection refused to 127.0.0.1:1 is the test harness working as designed: conftest.py sets offline sentinels at import time. Fix the test's mocking or mark it network/model; never start Ollama to fix it.

Why does the Sonder server fail to start with a preflight error?

Serve runs preflight first and fails closed on checks like state-home writability, free disk below 5 GiB, schema version mismatches, and policy loading. Read the named failing check; epoch-2 state homes require migrate --adopt-epoch2.

How do I tell a database lock from corruption in SQLite stores?

Stop the service, then run sqlite3 <store>.db "PRAGMA integrity_check;". An ok result means lock contention that a drain and restart clears; anything else means corruption requiring the backup-restore runbook.

Does Sonder work when Ollama is unreachable or has no models?

Missing models degrade rather than crash: unbound tiers are not offered and semantic recall falls back to lexical retrieval. Doctor treats a reachable Ollama with zero models as a warn, fixed by running setup_alias.py.

When should I not use this debugging playbook?

Do not use it for chronological when-did-this-break investigation (use sonder-failure-archaeology), operating the selfmod pipeline (use sonder-selfmod-lifecycle), or layering and import-boundary design (use sonder-architecture-contract).