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:

{
  "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.