Skip to main content
skill CX Codex

pl-analyze — Claude Code skill for incident analysis

The pl-analyze skill for Claude Code investigates incidents and reviews process failures. It activates through PL routing or an explicit request for a retrospective or root-cause report.

Apache-2.0 ★ 869 updated 2026-11-16

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sno-ai/sno-station-skills --skill pl-analyze -a claude-code
Open on GitHub

What pl-analyze does

The skill reconstructs an incident timeline from disk records, timestamps, execution logs and git history when the project uses git. Reports and recollections are leads to verify, not evidence. Sources missing from the project are skipped and noted.

Its report gives a conclusion, supporting facts with paths or commands, the location of the fix and a control to prevent recurrence. The cause class determines where the change belongs: a script fault calls for a code fix and test, while a missing process rule goes to the owner for approval. The skill requires shell access and file read/write access. Code changes outside PL control scripts go to an executor; skill-text changes follow the owner-approval process.

What it helps with

  • rebuild the event sequence behind a failed run
  • connect separate failures to a shared cause
  • place a fix according to the cause class
  • record a control that prevents a repeat incident

Example prompts for the agent

  • Write a retrospective explaining why this run failed.
  • Find the root cause of the stalled process in the logs and identify where its mechanism needs a fix.
  • Review recurring estimate errors and report the process cause.

How to install pl-analyze

1Skills CLI (Vercel)

npx skills add sno-ai/sno-station-skills --skill pl-analyze -a claude-code

2Manually: put the files in place

~/.claude/skills/pl-analyze/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pl-analyze/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about pl-analyze

How do I install pl-analyze in Claude Code?

Run npx skills add sno-ai/sno-station-skills --skill pl-analyze -a claude-code. The skill file is located at ~/.claude/skills/pl-analyze/SKILL.md.

What does pl-analyze do?

It rebuilds incident timelines from disk records, classifies causes and maps each cause to a fix location. Its report includes evidence and a recurrence control.

When does pl-analyze activate?

PL routing can load it, or the owner can request a retrospective, root-cause report or process review. It does not load automatically from ambient context.

Source text

SKILL.md · Apache-2.0
---
name: pl-analyze
description: "PL (Project Lead) role sub-skill for incident analysis and process evaluation. Loaded through the pl core routing table, or when the owner explicitly asks for a retrospective or root-cause write-up; NEVER auto-load from ambient context."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}
---

# PL · Analyze — incident analysis & process evaluation

Scripts named below run as `bash "${PL_SKILL_DIR}/scripts/<name>.sh" ...`, where `PL_SKILL_DIR` is the
absolute path of the `pl` skill directory; set it in the same Bash call. The workspace layout (`ai-doc/...`,
ledgers) is documented in the pl core's State files section; a source that does not exist in this project
is skipped and noted in the analysis.

Sub-skill of the PL role, also usable standalone. Words such as journey, callsign, night shift and
take-over are defined once, in the pl core's Terms glossary. The rules in this file are the PL role's
defaults; a project may choose otherwise.

Invoke when something went
wrong — an escaped bug, a stalled run, a run killed at its time limit, an estimate blowup, a
protocol breach, a close-audit FAIL — or when the owner ("owner" means whoever owns the work, often
the user) asks for a retrospective, a root-cause account of what went wrong, or for periodic process
evaluation (patterns in estimate errors, recurring frictions). The deliverable is never just an explanation: it is a
verified cause AND a fix landed in the right place. Core iron rules bind
unchanged; the owner is addressed in the user's own language.

## Method — evidence first, always from disk

Sessions lie and die; disk is the memory. Rebuild the timeline exclusively from:

- `sno reach log --as <your-strict-address> --work <id>` — the journey's
  full message provenance (`sno reach export --work <id> --output <path>` keeps the full
  thread bytes); command grammar is defined in
  `~/.local/lib/sno-reach/current/guide/agent-reach.md`
- `ai-doc/JOURNAL/routing-ledger.jsonl` — routed/closed/correction events (`board_closed` lines are written by `bash "${PL_SKILL_DIR}/scripts/todo.sh" close`; the PL writes the journey's own `routed`, `closed` and `correction` lines by hand)
- `ai-doc/ACTIVE/PL/exec-logs/` + dispatch files under `ai-doc/ACTIVE/PL/dispatch/`
- git log/diff of the journey's commits when the project uses git (the fence file lists the paths the journey may touch)
- the convergence series (the recorded remaining-work counts per fix cycle; `bash "${PL_SKILL_DIR}/scripts/convergence-watch.sh" verdict --journey <id>`)
- `~/.local/state/agent-spawns.jsonl` + `agent-callsigns.jsonl` + tmux autopsy
  (an executor killed at its time limit leaves its session up — read the screen)

Reports, memories, and your own recollection are HYPOTHESES to check against
this record, never evidence. Timestamp every step; a contradiction between two
sources is a finding, not noise. N different-looking failures arriving together
get ONE joined timeline BEFORE any is diagnosed separately — join the
timestamps in the target machine's system log first; cascades collapse into
one root event and red herrings die at the join — several apparently separate
failures are often one shared cause. A status table built from disk beats a report built from a
stale card — trust the freshest disk join, not the most confident narrator.

## Root-cause classification → fix location

The class DECIDES where the fix lands — never write a note where a mechanism
belongs:

| Class | Signature | Fix lands in |
|---|---|---|
| Machinery bug | a script/skill deterministically did the wrong thing | the skill CODE (script fix + test), then reinstalled |
| Judgment lapse | the agent saw the signal and chose wrong / waited on a human | MECHANIZE it — an alarm/verdict/gate in scripts (e.g. a stalled-close alarm); a memory note is NOT a fix |
| Estimation error | estimate vs actual > 2× | the est/actual pair → calibration material for `agentic-time-estimate` (when installed; otherwise a plain note of the pair) |
| Knowledge trap | a known trap, hit again | the lessons file `ai-doc/LESSONS.md` (written only by the PL; a trap enters the index on its SECOND hit — see the pl core, Lessons file) |
| Process gap | no rule existed for the situation | retro proposal → owner approval → skill text patch (never self-edited mid-journey) |

Design principle: **the machine must lose patience before the owner
does** — every place the owner had to scold marks a missing mechanical control;
an analysis is not done until that control is named (or shown to already exist).

## Output shape

Owner-facing report, written in the user's own language, four sections: (1) conclusion — what broke, one line;
(2) evidence chain — the 2–4 load-bearing facts, each with its path/command;
(3) where the fix lands — the fix and its location per the table above; (4) recurrence prevention — the
check/alarm/rule that now exists. Agent-facing: the same content as an English
postmortem section in the journey's journal entry, plus ledger `correction` events
wherever the durable record was wrong.

## Routing the lessons

A finished analysis routes each lesson to the file that OWNS the behavior:
dispatch-time rules → `pl-dispatch`; in-flight controls and alarms →
`pl-watch`; close/probe rules → `pl-audit`; environment checks → `pl-env`;
board/memory/Reach-substrate law → the `pl` core. A lesson without a named
owner file is not landed.

## Boundaries

- Script/machinery fixes land directly ONLY within the core iron-rule-1
  exception: PL-owned control scripts under the pl skill's `scripts/`,
  with a test, then reinstalled and reported to the owner. Anything else that needs code —
  repo source, other skills' scripts — is dispatched to an executor, never
  hand-edited. SKILL text changes still ride the retro → owner-approval path
  (core boundary).
- Estimation analysis only FILES the calibration pair — rate/multiplier changes
  belong to the estimator skill's own validation loop (when installed).
- Analysis of a journey never reopens settled owner rulings; if the cause traces
  to a ruling, report the trace, don't relitigate.

© sno-ai · Apache-2.0 · sno-ai/sno-station-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set40

The whole set →
pl-watch The pl-watch Claude Code skill gives a Project Lead rules for supervising active executors. The PL core loads it for incoming cards, stalls, watch events, and other work in progress. CX Codex +1 ★ 869repo stars pl-env The pl-env Claude Code skill checks a project environment and investigates blockers before test runs or VM work. The core pl skill loads it through its routing table. CX Codex +1 ★ 869repo stars pl-dispatch The pl-dispatch Claude Code skill helps a Project Lead open a work journey and prepare its dispatch. The pl core routing table loads it for scheduling decisions or requests to start work. CX Codex +1 ★ 869repo stars pl-audit The pl-audit Claude Code skill checks executor reports and task closure. The pl core skill routes it in when a report or a closure signal arrives. CX Codex +1 ★ 869repo stars cos A Claude Code skill, cos coordinates the project owner and project leads. It activates on /cos, $cos, or a direct request to act as Chief of Staff. CX Codex +1 ★ 869repo stars cos-watch The cos-watch Claude Code skill monitors active PLs, checking liveness, wake cycles, and task order. The COS core loads it through its routing table while work is in flight. CX Codex +1 ★ 869repo stars cos-review The cos-review Claude Code skill audits decisions, completed work, and estimates after a declared night shift. COS core routes it in when the owner returns or a batch of closes lands. CX Codex +1 ★ 869repo stars cos-evolve The cos-evolve Claude Code skill turns recurring management failures into rules for COS or PL. COS loads it after the owner activates the role and routes a repeated failure to it. CX Codex +1 ★ 869repo stars

Project sponsors

Companies that keep this analytics open