# Sonarly Incident Remediator

> Given a log or stack-trace snippet, produce a structured incident remediation plan covering ranked root-cause hypotheses with evidence, ordered fix steps each with a verification check, a rollback plan, and preventive follow-ups.

- Skill: `riteshkew/sonarly-incident-remediator` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add riteshkew/sonarly-incident-remediator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/riteshkew/sonarly-incident-remediator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: riteshkew (https://skillmd.com/u/riteshkew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/riteshkew/sonarly-incident-remediator

---


# Workflow

When this skill triggers, follow these steps in order.

## Step 1 — Ingest the log or stack trace

Accept the incident input from the user. This may be:

- A raw stack trace pasted inline
- A log excerpt (structured JSON logs, syslog, or plain-text app logs)
- A combination: a deploy context block followed by log lines

Identify and extract the following fields before proceeding:

- **Error message** — the human-readable exception or error string (e.g., `TypeError: Cannot read properties of undefined (reading 'id')`)
- **Failing frame** — the top application-owned stack frame (skip `node_modules` frames); note the file path and line number
- **Onset time** — the timestamp of the first error log line
- **Affected surface** — the route, job, or component where the error originates
- **Deploy or change context** — if log lines mention a deploy SHA, PR, or config change near the onset time, note it
- **Error rate or frequency signal** — any log lines indicating how widespread the failure is (e.g., percentage of requests failing, alert thresholds crossed)

If the user provides insufficient context, ask:
> "Please paste the full stack trace and at least 30 seconds of surrounding log lines. If a recent deploy or config change preceded the error, include that context too."

## Step 2 — Form ranked root-cause hypotheses

Using the extracted fields, generate 2–4 root-cause hypotheses ranked by confidence (HIGH / MEDIUM / LOW).

For each hypothesis:

1. State the hypothesis in one sentence — what specifically went wrong and why.
2. List the evidence from the log/trace that supports it — quote specific log lines or frame references.
3. State the confidence level and the single biggest gap in evidence (what would confirm or refute this hypothesis).

Ranking rules:

- Prefer hypotheses grounded in a specific application frame over generic infrastructure explanations.
- If a deploy or config change is correlated with the onset time, elevate any hypothesis that directly involves changed code.
- A hypothesis with a precise line-number reference in an application file ranks above one without.

## Step 3 — Produce ordered remediation steps

Generate a numbered list of fix steps ordered by priority (stop the bleeding first, then fix the root cause, then harden).

For each step provide:

- **Action** — a plain-English description of what to do.
- **Command or change** — the exact shell command, SQL statement, or code diff to execute. Use realistic placeholders (e.g., `<deployment-name>`) rather than vague descriptions.
- **Verification** — a concrete, observable check that confirms the step succeeded (a metric to watch, a query to run, or a test to pass). Do not accept "looks good" as verification.

Step ordering template (adapt to the specific incident):

1. **Immediate containment** — roll back, feature-flag off, or stub the failing route to stop user impact.
2. **Local reproduction** — reproduce the crash in a local or staging environment to confirm the root cause before writing code.
3. **Code or config fix** — patch the specific file and line identified in Step 2.
4. **Data or migration fix** — if a missing or malformed database row is involved, write and run the repair query.
5. **Re-deploy with monitoring** — push the fix through the standard CI/CD pipeline and watch error rate for a defined window.

## Step 4 — Include a rollback plan

Specify the condition that should trigger a rollback (e.g., error rate stays above X% for Y minutes after fix deploy).

Then list the rollback steps in order. Each step must be actionable — not "revert if needed" but the specific command or procedure.

## Step 5 — Add preventive follow-ups

List 3–5 concrete items that would have caught this incident earlier or prevented it entirely. Examples of strong follow-ups:

- A missing test case (state what the test input and expected output would be)
- A missing pre-deploy checklist item
- An alerting or observability gap (state what metric to add and what threshold to alert on)
- A code pattern or lint rule that would have caught the bug statically

Avoid generic advice ("add more tests"). Each follow-up must be specific to the incident.

## Output format

The output is a single JSON document conforming to this schema:

```json
{
  "incident_summary": { ... },
  "severity": "P1 — Critical | P2 — High | P3 — Medium",
  "root_cause_hypotheses": [
    { "hypothesis": "...", "confidence": "HIGH | MEDIUM | LOW", "evidence": ["..."] }
  ],
  "remediation_steps": [
    { "order": 1, "action": "...", "command_or_change": "...", "verification": "..." }
  ],
  "rollback_plan": { "trigger": "...", "steps": ["..."] },
  "preventive_followups": ["..."]
}
```

All string fields must be populated. `remediation_steps` must have at least 3 entries. `root_cause_hypotheses` must have at least 2 entries with distinct evidence sets.

## Scope and limitations (v1)

This skill produces a **remediation plan document only**. It does not:

- Execute any commands against live systems
- Connect to your observability platform, CI/CD pipeline, or source control
- Automatically apply patches or trigger rollbacks

Executing the plan against live systems is the productionization gap — see the README for details.

## Example

See `examples/input.md` for a realistic Node.js production incident (TypeError in a preferences endpoint after a deploy, with a 500-rate spike from 0.2% to 82%) and `examples/output.md` for the full JSON remediation plan this skill produces.