incident

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:incident; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

/incident Skill: Structured Incident Logging

Overview

This skill helps you systematically capture incidents, analyze their root causes, and extract lessons learned to prevent future recurrence.

Workflow

Step 1: Gather Incident Details

If the user provided a description with /incident <description>, use that. Otherwise, ask the user:

• What went wrong? (the symptom, the failure, what the user observed)
• What was the context? (what was being done, what changed, what was the state)
• What was the impact? (did it affect production, other users, how long did it last)

Step 2: Perform Root Cause Analysis

Once you have the details, conduct a structured RCA:

• Immediate cause: What directly caused the failure? (e.g., missing validation, race condition, config not deployed)
• Root cause: Why was the immediate cause present? (e.g., code not tested, config drift, async task not awaited)
• Category: Classify the root cause into one of these categories:
  • settings-disconnect: Config defined but not wired, loaded, or called
  • edge-case: Untested input, OS-specific behavior, empty/null/first-run state
  • async-race: TOCTOU (time-of-check-time-of-use), stale closures, missing locks, zombie processes
  • security: Unsanitized input, leaked secrets, missing auth/validation
  • deploy-gap: Source differs from deployed, config not reloaded, code defined but not called at runtime

Step 3: Write Incident Entry

Create or update .clade/incidents.md with a new entry:

## Incident — {date: YYYY-MM-DD}
**What:** {1-2 sentence symptom - what went wrong}
**Context:** {1-2 sentences - what was being done, what changed}
**Root cause:** {1-2 sentences - why did it happen, which category}
**Fix applied:** {how was it resolved, if immediate fix exists}
**Prevention:** {what should prevent this next time - concrete steps, not vague}

Example:

## Incident — 2026-02-26
**What:** API endpoint returned 500 on startup, database connection string missing from error response.
**Context:** Deploying to production with new secrets management; assumed .env would be loaded from system but it wasn't.
**Root cause:** Secrets loading hook defined in config but never called during server startup. [deploy-gap]
**Fix applied:** Added explicit `await loadSecrets()` call in server init before database connect.
**Prevention:** Add startup checklist: (1) required envvars defined, (2) all config-loading hooks executed, (3) test startup on fresh container.

Agent-caused incidents: extra fields

If the failure came from an agent run (unattended loop, dispatched worker, cron session) rather than a human-driven edit, the standard entry is not enough — agent incidents carry delegated authority, so the postmortem must reconstruct what the agent was allowed to do, not just what it did. Add:

Agent: {which run/worker/session, with its log or evidence-bundle path} Authority scope: {permissions granted vs. the ones actually exercised} Tool-call trace: {replayable record — session transcript, hook log, or evidence bundle} Blast radius: {compute/API spend and external side effects (messages sent, pushes, deploys), not just code damage} Facts vs. hypotheses: {what the trace proves vs. what is inferred — mark each}

An agent-incident postmortem that names no trace is UNVERIFIED by construction: an agent's own summary of its run is a claim, not evidence.

Step 4: Extract Corrective Rule (Optional)

If the incident reveals a pattern worth remembering, offer to append a rule to corrections/rules.md:

Format:

- [YYYY-MM-DD] {domain} ({root-cause-category}): {do this} instead of {not this}

Example:

- [2026-02-26] deploy (deploy-gap): Call `loadSecrets()` explicitly in server init — not rely on framework autoload

Ask the user if they want to add the rule. If yes, append it to the file. If no, skip.

Step 5: Confirm and Close

Once the incident entry is written, print:

✓ Incident logged to .clade/incidents.md — [link to timestamp]

If a rule was added:

✓ Corrective rule added to corrections/rules.md

---

Implementation Notes

• Keep it concise: Incident entries should be scannable — one incident per date.
• Date format: Use YYYY-MM-DD (e.g., 2026-02-27).
• Prevention is key: The "Prevention" section is the most valuable part — it should be concrete and actionable, not vague.
• Root cause category is required for rule extraction — it helps organize lessons by type.
• If .clade/incidents.md doesn't exist, create it with a header: # Incident Log\n\n.
• If corrections/rules.md doesn't exist, create it with a header: # Correction Rules\n\n.

---

User Interaction Model

1. User runs /incident with optional description: /incident "API timeout during batch job"
2. If no description, ask for what/context/impact
3. Conduct RCA together (ask clarifying questions if needed)
4. Write the incident entry to .clade/incidents.md
5. Append the prevention work to TODO.md. The entry's Prevention field is already the follow-up task; a postmortem whose prevention lives only in an incidents file is a postmortem nobody acts on. One checkbox per preventable cause, each naming the file or gate that would have caught it. Say so if there is genuinely nothing to prevent — that is a finding, not an omission.
6. Offer to extract a rule — get user confirmation before appending
7. Confirm logging is complete, and name the TODO items you added

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.