sonder-failure-archaeology

Documents historical incidents, root causes, and fix disciplines for the Sonder Runtime repository.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? When working on the Sonder Runtime codebase, engineers risk re-attempting fixes that already failed, undoing deliberate reverts, or misreading strangely-shaped guards without knowing their history. This Skill provides chronological institutional memory of every major investigation, dead end, rejected fix, and revert so you can answer "why is this code written this way" before changing it. ## Core Features & Use Cases - Incident index with verified status: Thirteen documented incidents, each with symptom, root cause, evidence commits, and a status (fixed, open, or policy) re-verified against a specific commit. - Fix discipline checklist: A distilled six-step sequence covering reproduction through production paths, mutation-proving guards, corroborating zero-counts, and re-verifying file:line anchors and git lineage. - Re-verification one-liners: Ready-to-run shell commands that confirm whether each incident's fix is still present in the current tree. - Use Case: Before re-attempting a fix that a code comment hints was tried before, consult this Skill to learn that shell_run was wholesale-reverted as a safety policy, or that the smoke gate was once a constant-true assertion, so you do not repeat the mistake. ## Quick Start Ask why a specific guard or check in the Sonder Runtime repo is shaped the way it is, or whether a particular fix has been tried before.

Frequently Asked Questions about sonder-failure-archaeology

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

FAQPage Schema
How do I find out why code was reverted in a repository?

Consult the incident index, which records each revert with its symptom, root cause, evidence commit hash, and current status. For example, the shell_run tool was reverted wholesale as a standing safety policy, and the Skill states the revert must not be undone.

How do I check if a bug fix was already tried before?

Search the chronological incident history for the symptom or subsystem in question. Each entry records what was attempted, why it failed or was rejected, and whether the fix is present at the verified commit, preventing repeated failed approaches.

When should I use failure history instead of a debugging playbook?

Use failure history for past-tense questions like why a guard is shaped strangely or what happened with a previous fix. Use a debugging playbook when you have a live failing test or stack trace right now and need to know what to try next.

How do I verify a fix is actually on my git branch?

Run git merge-base --is-ancestor <fix-commit> HEAD before claiming any fix is on your lineage. The Skill documents cases where the same defect was fixed on one branch while other branches carried the pre-fix code with a now-false docstring.

What is mutation testing for guards and how is it done?

Mutation-proving a guard means planting the violation, watching the named test fail, then reverting with a byte-exact backup and watching it pass. The Skill requires this for every new guard, with plants held outside the scanned tree so a scanner cannot scan its own plant.

What are the known open issues in the Sonder Runtime repo?

Two counting bugs remain open: secret_scan increments its scanned counter before reading files so unreadable files count as scanned, and reclaim_orphans increments its reclaimed counter even when cancellation raises. Both were re-verified as still present at the documented commit.