20_failure_postmortem_skill

Overview

This skill captures and persists structured records of execution failures so teams and agents can learn and prevent recurrence. It enforces synchronous analysis: each logged failure includes a root cause and a concrete preventive rule. Logs are appended to a persistent registry to guarantee an auditable trail of incidents and remedies.

How this skill works

When a command or plan fails, the skill accepts the command, error text, and optional context and appends a formatted failure analysis to a persistent POSTMORTEMS.md file under the agent workspace. It auto-creates the forensics directory if missing, verifies file writability, and guarantees append-only behavior to avoid data loss. The entry schema includes timestamp, context, command, error, root cause, and a preventive rule for future runs.

When to use it

• Automated agents experience an unexpected error or throw an exception
• A plan or tool run is abandoned and you need a record for retrospection
• After safety or QA checks identify a reproducible failure mode
• When building operational playbooks or runbooks from real incidents
• During adversarial reviews to capture edge-case failures

Best practices

• Include a clear, minimal command string and the full error trace for reproducibility
• Capture the agent intent or context to link failures to high-level goals
• Write the root cause as a specific, testable statement (not vague descriptions)
• Propose preventive rules that are actionable and enforceable by other skills or CI gates
• Run periodic reviews of POSTMORTEMS.md and convert recurring entries into automated safety checks

Example use cases

• Agent catches an out-of-memory build error and logs the command, trace, and a rule to increase Node memory limits
• A test harness aborts a deployment; postmortem records the configuration mismatch and adds validation before deploy
• Adversarial review finds a data leak edge case; entry prescribes sanitization and an automated lint check
• Step-level impasse detection logs manual intervention reasons and suggests automation or guardrails