@sitar_fiercer4c/skills 0.1.0

package/skills/refac-wrt-business-goal/SKILL.md

@@ -0,0 +1,305 @@
+---
+name: refac-wrt-business-goal
+description: Converge on a business model of a codebase — an under-50-word business goal, a node table, an edge list, an ASCII graph, and the input and output test seams a characterization test can be pinned to — from the repo, the user's account of the happy path, and an API recording of it. Use this whenever someone wants a flow modelled before a refactor, or asks where to pin a test for that flow.
+---
+
+# Refactor with respect to the business goal
+
+## Inputs
+
+Three things, all required. Ask for any that is missing and wait — starting without one costs more
+than the wait does.
+
+1. **The repo, and which flow in it.** One flow, named by what the user does, not by a file.
+2. **The user's account of the happy path.** What they do, step by step, and where the business
+   considers the job done. The finish line especially: it is almost never where the code stops.
+3. **An API recording of that happy path** — the `backend-inbound.log` and `.jsonl` pair
+   produced by the `record-api-traffic` skill, landing in that skill's own workspace at
+   `skills/record-api-traffic-workspace/recordings/<repo-slug>/run-<stamp>/`. That run folder
+   also holds the frontend's two legs and the backend's outbound calls, if you need them.
+
+The recording is not a nice-to-have. Without it you are guessing which code runs, and a graph built
+from code that never executes is the expensive failure here — you model a path the business
+abandoned two years ago and hand it back as a blueprint. If the user has no recording, point them at
+`record-api-traffic` to capture one, and wait. Its `references/reading-recordings.md` has the field
+meanings and jq recipes.
+
+## Output
+
+Exactly one file, at
+`skills/refac-wrt-business-goal-workspace/<target-name>-business-model.md`, with six sections:
+
+```
+# Business model: <target>
+
+## Business goal   (under 50 words)
+## Nodes           (the workflow's steps: the table, plus external inputs and rule footnotes)
+## Edges           (what moves between steps, explicit list)
+## Graph           (the workflow drawn, ASCII)
+## Input seam      (where a test drives this workflow, in code that exists today)
+## Output seam     (where every outcome becomes durable, and which field carries each node)
+```
+
+There are three things here, not six. The **goal** is what the business is for. The **workflow** is
+how it gets there — the ordered decisions that carry an external input to an outcome — and the
+nodes, edges and graph are that one workflow written three ways: its steps, its transitions, its
+picture. The **seams** are where that workflow touches the code as it stands today.
+
+The first two give the chain the whole exercise is built on: **every business goal is achieved by a
+workflow, and the graph represents that workflow.** They are done when an independent critic says
+both links hold — that the workflow achieves the goal, and that the graph is a faithful drawing of
+the workflow.
+
+The seams exist because a model that stops at the graph is a claim nobody can check. The refactor it
+is written to guide will move every file it describes, and without two fixed points where the
+current behaviour can be held still, nothing afterwards can show the workflow survived. Naming the
+seams is what turns the model from a description into something falsifiable.
+
+**Not an output: any change to the repo. Not one line, not a rename, not a comment.** The artifact is
+the whole deliverable. If the user asks for the refactor too, produce the artifact first and let them
+start the refactor as a separate request. A model written by someone already mid-edit drifts toward
+describing the edits instead of the business.
+
+Naming a seam invites writing the test at it. Don't: this skill names seams, it does not write tests,
+and it does not export a helper to make one reachable.
+
+## 1. Read the code, against the recording
+
+Follow one flow, from the entry point to the business finish line. The recording tells you where
+that flow really goes: every call it made, in order, with bodies. Read it first, then open the code
+the calls land in.
+
+Before opening anything, list the files and their sizes and work out which sit past the finish line
+— those you skim only far enough to confirm they are downstream, and then don't model. A quarter of
+a services directory is often export and delivery code that runs after the business considers the
+job done.
+
+Read in batches: issue the reads for every file in the current layer in one go, rather than opening
+one, thinking, and opening the next. You are following a flow, not auditing a directory, and the
+thinking that matters happens once you have the layer in front of you.
+
+Four things will lie to you, all in the same direction — they describe an older system. The
+recording is what you check each of them against, because it is the only account of the system that
+cannot be out of date:
+
+- **the repo's own docs** (architecture notes, code reviews, plans)
+- **comments and names** — a step labelled `fallback` may be the success path
+- **a subagent's narrative** — subagents find files well and summarise flows badly, because they
+  read excerpts
+- **your first read** — go back and check what each step *writes*, including mutation of arguments
+
+Find what is dead at runtime as well as what runs. Dead code tells you which business rules were
+tried and abandoned, which is exactly the kind of thing the user has stopped noticing. The recording
+makes this cheap: code with no call behind it is a candidate, and grepping the exported names on
+your flow for callers settles the rest.
+
+## 2. Say what you think this is for, and wait to be told you're right
+
+You have read the code and watched the calls. Now commit to a reading of the business and have the
+user check it — before you write the goal, a node, or an edge.
+
+Put three things in front of them with `AskUserQuestion`:
+
+- **A short paragraph in plain language.** Who this serves, what they get out of it, where the
+  business considers it finished, what it refuses to do. No vocabulary from the repo — if a
+  sentence needs a filename to make sense, you are describing the code.
+- **The steps of the workflow you expect, in order. Names only, no descriptions.** Names are cheap
+  to throw away; a filled-in node table takes long enough to write that you would defend it rather
+  than drop it. The point here is a cheap check on the *shape* of the workflow, while changing it is
+  still free.
+- **3–4 questions.** Each one a thing that would change the paragraph or the node list if answered
+  the other way. The test of a good question: it is about what the business wants, and a person who
+  has never read the code could answer it.
+
+  Good: *"Is the photo on the customer's inquiry decoration, or part of the requirement?"*
+  Bad: *"Should `injectImages` run before or after filtering?"*
+
+**Then stop.** No goal sentence, no node table, no graph until the answers land. The finish line, and
+which rules are invariants rather than conveniences somebody added, are not recoverable from code —
+a model built without them is a picture of the code, which is the thing the user is complaining
+about. And a goal drafted before the answers arrive is a goal you will then defend: what comes back
+gets filed as a correction to it, rather than as the thing it should have been built on.
+
+If the answers change your understanding, rewrite it and put it back. **Loop until the user confirms
+it, with no cap.** This is the only unbounded loop in the skill, and deliberately so — a human ends
+it. The critic loop later is capped precisely because nothing human is there to stop it.
+
+## 3. Write the goal in under 50 words
+
+The budget is the mechanism. It has no room for what the system does, only what it is *for*, so it
+forces you to rank the business's concerns. Write it as one sentence about the customer's outcome.
+
+If a rule you believe is important won't fit, that is information: either it isn't core, or your
+goal sentence is aimed at the wrong thing.
+
+The sentence says what the business is for. It does not say how the business gets there — that is
+the workflow, and it is next.
+
+## 4. Write the workflow: nodes, edges and graph
+
+A goal is achieved by a workflow: an ordered run of decisions that carries something arriving from
+outside all the way to an outcome the business recognises. Model that, and the three artifacts fall
+out of it — the **nodes** are its steps, the **edges** are what moves between them, the **graph** is
+it drawn.
+
+Keeping the workflow in mind is what stops this becoming a taxonomy. A decomposition of a system
+into parts is easy to write and passes a casual read; it has no start, no order, and nothing that
+would let you say a step ran too late. If a node isn't a step on the way from an input to an
+outcome, it is not part of the workflow, however true it may be about the system.
+
+Node names are verb phrases in the language of the business, named for the decision the step makes.
+Not for the function that makes it — a workflow rebuilt from the call chain is a picture of the code
+you already have, which is the thing the user is complaining about.
+
+List the **external inputs** — the things arriving from outside the workflow — above the table, so
+the first step's `handed` column has somewhere to come from.
+
+Then one table, five columns:
+
+| node | handed | decides | refuses when | emits |
+|---|---|---|---|---|
+| `carry-quantities-into-the-draft` | the quotable line rows, and which column holds quantity | fills in the quantity the customer asked for, and nothing else (R1, R2) | never — see R2 | draft rows in the customer's order, each naming its inquiry row |
+| `pin-photos-to-their-inquiry-rows` | every photo with the row it sits on | which inquiry line each photo illustrates (R3) | never — strays are discarded | for each row that has one, the photo belonging to it |
+
+**Keep cells to a clause each.** A rule that needs a paragraph becomes a numbered footnote under the
+table — `R1`, `R2` — referenced from the cell:
+
+> R1. Every other field is left blank for the salesperson deliberately; this is the rule, not an
+> unfinished mapping.
+> R2. A quantity that cannot be read as a number is left empty rather than guessed at, and the line
+> is still created.
+> R3. One photo to a row, first wins a contested row; photos anchored outside the item table are
+> discarded rather than attached to an arbitrary line.
+
+The table earns its shape by putting `handed` and `emits` on the same row, so a node whose output
+nothing consumes, or whose input no edge produces, shows up by scanning one column. That is exactly
+what the critic checks under graph integrity. The thing to guard against is not columns but **cells
+that swell into paragraphs** — once they do, the row stops being scannable and the defect hides
+again. That is what the footnotes are for: let the rule run as long as it genuinely needs down
+there, where nothing depends on it staying short.
+
+Write the **edge list** out explicitly and separately: `E<n>. <source> -> <target> — <what travels>`.
+The drawing is where mistakes hide; the edge list is what you check it against.
+
+Then draw the graph in this shape, every time:
+
+```
+(A) external input
+(B) external input
+  |
+  | E1,E2
+  v
+first-node ........................ E4 -> [R]
+  | E3
+  v
+second-node ....................... E8 -> [R]
+  | E5
+  v
+third-node ........................ E13 -> [R]
+  | E9                              E10 -> a-later-node
+  v                                 E11 -> another-node
+fourth-node ....................... E16 -> [R]
+
+[R] refuse-node -> OUTCOME 2: <what the user is told, and can act on>
+commit-node --------------------> OUTCOME 1: <what they get>
+```
+
+External inputs at the top, the spine down the left one step per line in the order the workflow runs
+them, forward and cross edges as labelled jumps on the right, a single refusal sink `[R]` at the
+bottom, and every path ending in a named outcome. The layout is doing more than looking tidy: read
+top to bottom it is the workflow in sequence, so a step drawn out of order, or one with nothing
+above it and nothing below, is visible without checking anything. One fixed shape also means the
+drawing is comparable run to run and diffable, and that you spend your effort on the model rather
+than on inventing notation.
+
+## 5. Loop a critic until it agrees
+
+The loop tests the chain: **the workflow achieves the 50-word goal, and the graph represents the
+workflow.** Everything below serves those two links.
+
+**Methodology.** Spawn a fresh critic each round — a continuation anchors to its own last verdict.
+Round 1 is three critics in a single message so they run concurrently, each led onto a different part
+of the checklist; round 2 onward is one. Merge by defect, not by critic. Where two critics
+*contradict* each other, don't split the difference — go to the code and the goal and settle it.
+Brief them from `references/critic.md`, which holds the checklist, the emphasis split and the
+response format.
+
+**Constraints.** TRUE means every clause of the goal is achieved by a step, every step earns its
+place from the goal, and the drawing is the workflow — not that the model is beyond improvement. Two
+rounds is normal, four is the hard ceiling. Defects still standing at four are reported as open
+questions, not fixed.
+
+**Gotchas.** A lone first-round TRUE is an agreeable critic, not a correct graph. Critics may read
+the repo to settle a factual dispute, but the model is what is under review — a critic that starts
+listing what it would change about the code has drifted. Re-submitting a converged model always
+returns a fresh remark — that is oscillation, not a reopened defect.
+
+## 6. Find the seams the model can be pinned to
+
+Only now, once the critic has converged. A seam mapped against a graph that is still moving gets
+re-mapped every round, and mapping is the expensive part of this step.
+
+**Find a seam, don't create one.** A seam you have to export into existence is a change to the repo,
+and this skill makes none. Search only `services/` and `utils/`: a seam above that layer drags HTTP,
+auth and Express into the fixture without adding a single business input.
+
+Read the recording again first, filtered to the state-changing 2xx calls — OPTIONS, 304s and polling
+GETs carried nothing. A `202` is worth stopping on: it means the work is fire-and-forget, so the
+response body is not the outcome and the seam does not await it. Name the signal a test polls for
+completion instead, or the test asserts on a workflow that hasn't run yet.
+
+- **Input seam** — the narrowest already-exported function with every external input on its input
+  side. Count what it fetches, reads and imports, not just its parameters: an env var, a module-level
+  client and a database read are all things the test has to control, and they don't appear in a
+  signature.
+- **Output seam** — where every outcome becomes durable, refusals included. Read the `catch` block;
+  that is usually where the refusal is written, and a seam that only sees OUTCOME 1 can never assert
+  OUTCOME 2.
+- **Reject any seam the refactor would dissolve.** Pure helpers die under a refactor — that is what
+  the refactor is for. The orchestrator entry and the terminal write survive it, which is exactly
+  what makes them seams and a well-named private helper not one.
+- **Grep every call site of the output seam** and say what distinguishes the in-graph ones. A durable
+  write is usually shared with unrelated code, and a test asserting that a save happened has proved
+  nothing about this workflow.
+- **Read the seam's body before committing to it.** Retry loops and pruning ladders mutate the
+  payload between attempts, and they will silently void the assertions you are about to plan.
+
+**Then map every node onto the output seam.** Take each node's `emits` and name the field on the
+seam's payload that carries it. This mapping is the check — it is why no critic round is spent here.
+A node that will not map means one of two things, and which one matters: either the seam is in the
+wrong place, or nobody implemented that node. Say which. An unimplemented node is the most valuable
+thing this step turns up, and the graph is the only reason anyone noticed it.
+
+Write the two sections tight — the node table is where length is earned, not here. Each seam is
+`name(signature)` with `file:line`, one sentence on why this one and not the runner-up you rejected,
+then bullets: for the input seam one per external input, saying what it is, how it arrives and which
+node it feeds; for the output seam one per node, naming the field that carries its `emits`. Cite
+`file:line` for every claim — a seam named without a line number is a guess, and whoever writes the
+test finds that out the expensive way.
+
+## 7. Write the artifact and stop
+
+Write the six-section file described under **Output**. Then say in chat — not in the file — how many
+rounds the critic loop ran and anything the last round still noted.
+
+Then stop. Don't start the refactor, don't sketch a file layout, don't rename anything, and don't
+write the test.
+
+## Anti-patterns
+
+- Starting without the recording, and modelling a path that no longer runs.
+- Drafting the goal or the nodes before the user has confirmed your understanding.
+- Building the graph from function names or the call chain.
+- A decomposition rather than a workflow — parts of the system with no order, no start and no
+  outcome, so nothing in it could ever be said to happen too late.
+- A node that only moves data from one place to another.
+- Table cells grown into paragraphs, so the row stops being scannable and the rules stop being
+  findable.
+- Treating a convenience (dropping noisy rows to save typing) as an invariant.
+- A refusal path that stops without a stated outcome the user can act on.
+- Declaring convergence yourself instead of letting the critic do it.
+- Running a fifth round because the fourth critic had one more thought. Past the ceiling, remaining
+  defects get reported, not fixed.
+- Creating a seam — exporting a private helper — rather than finding one that already exists.
+- An output seam that only sees the success path, leaving the refusal outcome unassertable.
+- Hunting for seams before the critic has converged, pinning them to a graph still in motion.

package/skills/refac-wrt-business-goal/references/critic.md

@@ -0,0 +1,170 @@
+# Briefing and running the critic
+
+Read this when you reach step 5. It covers what to hand a critic, how many to run, what to ask them
+for, and why the loop is capped.
+
+## What the loop is for
+
+**Every business goal is achieved by a workflow, and the graph represents that workflow.** The
+critic certifies both links:
+
+- **goal → workflow.** Every clause of the 50-word sentence is achieved by a step; every step earns
+  its place from that sentence. Checklist item 1.
+- **workflow → graph.** The drawing and the edge list are a faithful, ordered picture of that
+  workflow, with a start, a run and an outcome. Checklist item 5.
+
+The nodes, edges and graph are not three things — they are one workflow written three ways. The
+remaining checks exist because a workflow that is mis-scoped, at the wrong granularity, or made of
+mechanism cannot be judged against a business goal in the first place.
+
+Say this to the critic in as many words. A critic that is not told what it is deciding falls back on
+generic code-review instincts and returns a list of things it would have written differently.
+
+## What the critic gets
+
+Give it:
+
+- the business goal
+- the node table, **including the rule footnotes** (`R1`, `R2`…)
+- the edge list
+- the graph
+- one paragraph of domain background, so it can make judgment calls about the business
+- the repo, to check a claim against
+
+The critic may read the code. It should not review it. The distinction is the whole job: it is
+deciding whether this model represents the business, and a claim it cannot check is a claim it can
+only test for internal tidiness. A critic that starts listing what it would change about the code has
+drifted — the model is the subject, the code is the evidence.
+
+Be aware that the paragraph of background is written by you, the author of the model under review, so
+it can smuggle in the assumption being tested. That is a second reason the critic needs the repo.
+
+Spawn a **fresh** critic each round. Continuing the previous one anchors it to its own last verdict;
+a new one re-reads with clean eyes and finds different defects.
+
+## Where the rules live
+
+Node cells carry a clause; the rule itself lives in the footnote the cell points at. So a cell
+reading "fills in the quantity the customer asked for, and nothing else (R1, R2)" is judged by R1 and
+R2, not by the cell alone. Footnotes are in scope for every checklist item, and a critic names one by
+its id when the defect is there.
+
+## Round 1: three critics, concurrently
+
+Different critics find different defects. This used to cost five rounds; buy the variety all at once
+instead. **Spawn three critics in a single message containing three tool calls, so they run
+concurrently.**
+
+Give each the whole checklist, but tell each to lead with a different part:
+
+| critic | leads with | checklist items |
+|---|---|---|
+| A | coverage and scope | 1, 6 |
+| B | self-contradiction and mechanism leaks | 2, 3 |
+| C | granularity, graph integrity, hidden assumptions | 4, 5, 7 |
+
+Splitting the emphasis is what stops all three sharing a blind spot, which three identically-prompted
+critics would.
+
+Merge their findings **by defect, not by critic**: two critics naming the same node is one entry, not
+two. The one-line defect format below is what makes this a deduplication rather than a second act of
+synthesis.
+
+**When two critics contradict each other** — one says a node is a mechanism leak, another says it
+carries a real business rule — that is not a merge, and it is not yours to average. Go to the code
+and to the goal sentence and settle which is true. A contradiction between two readers of the same
+model is the loop working: it has found a place where the model is ambiguous enough to support both
+readings, and the resolution belongs in the text so the next reader cannot make the same mistake.
+
+**Check you actually have concurrency.** If you have no subagent tool and are emulating critics with
+separate shell invocations, they will run one after another — and three critics back to back cost
+what three rounds cost while telling you less. In that case spawn **one critic per round**, not
+three.
+
+Round 2 onward is a single critic with no seeded emphasis, judging the whole checklist against your
+revision.
+
+## The checklist
+
+Have the critic work through all seven, whatever it was told to lead with:
+
+1. **Coverage, both ways — does the workflow achieve the goal?** Every clause of the goal is *done*
+   by a step — and no step asserts a rule the goal gives no support for. Check the clause against the
+   step's `decides` and `refuses when` cells and the footnotes they point at, **never against its
+   name**. A step named for a goal clause whose decision does something else passes a name check and
+   fails the business; that is the defect this item exists to catch.
+2. **Self-contradiction.** Does any node's stated invariant survive the inputs it is actually handed?
+   This catches the most valuable class of defect: a commitment step that promises "every line, with
+   its photo" when an upstream filter already removed some.
+3. **Mechanism leaks.** Any node that is really storage, transport, authorization, a vendor, or a
+   file format wearing a business hat.
+4. **Granularity.** One node bundling three rules while another splits one rule across two.
+5. **Graph integrity — is the drawing the workflow?** Every declared input produced by an incoming
+   edge; every step reachable from an external input; every path ending in a stated outcome; the
+   drawing matching the edge list exactly. And is this a workflow at all, or a decomposition wearing
+   arrows — steps with no order between them, or a set of parts of the system rather than a run from
+   input to outcome?
+6. **Scope.** Nothing straying past the stated finish line, nothing stopping short of it.
+7. **Hidden assumptions** a reader would need told.
+
+## What the verdict means
+
+Tell the critic this, or it will never give you one. The bar for TRUE is that **every clause of the
+goal is achieved by a step, every step earns its place from the goal, and the drawing is that
+workflow** — *not* that the model is beyond improvement. Every model is beyond improvement; a critic holding out for that answers FALSE
+forever, and you find yourself on round nine of a loop that was right at round three.
+
+So: if the remaining remarks are things the critic would mention in review but merge anyway, that is
+`VERDICT: TRUE` with the remarks listed under it.
+
+## Response format
+
+Ask for exactly this, and nothing else:
+
+```
+HOLDS: <checklist numbers that pass, and the nodes already right — names only, no explanation>
+
+<checklist#> <subject> — <the defect>
+<checklist#> <subject> — <the defect>
+...
+
+VERDICT: TRUE
+```
+
+`<subject>` is a node name, an edge id (`E4`), a rule footnote id (`R2`), or **`GOAL`** for a defect
+in the goal sentence itself — a clause with no home in any node, a clause the graph contradicts, or a
+rule the graph enforces that the sentence never licenses. Given what this loop is for, `GOAL` defects
+are the most important ones available, and without a subject to file them under they get quietly
+rewritten as complaints about whichever node happened to be nearest.
+
+No preamble, no summary, no restating your model back to you. You wrote it; you don't need it read
+aloud. The verdict is a bare final line.
+
+Two instructions matter as much as the checklist itself:
+
+- **Don't manufacture defects to appear rigorous.**
+- **Name what already passes**, so the next revision doesn't break it. Without the `HOLDS:` line,
+  revisions oscillate and you fix defect 3 while reintroducing defect 1.
+
+## Why the loop is capped
+
+A competent critic can always find *something* to say about a ten-node graph, so "loop until a round
+comes back clean" is a loop with no reliable exit. Runs left open-ended have gone ten rounds and
+taken an hour to land where round three already was.
+
+Two rounds is the normal case; four is the hard ceiling. Don't stop at one — a lone TRUE is as likely
+to mean an agreeable critic as a correct graph, and that holds even when all three round-1 critics
+return TRUE: run round 2 against the merged revision anyway, then take the verdict.
+
+If defects remain when round four ends, that is a genuine finding: report them to the user as open
+questions. It is not an instruction to keep going. Three honestly-recorded open questions are worth
+far more than an hour of polish.
+
+Between the floor and the ceiling, stop as soon as a round raises no defect that would change a node,
+an edge, or a clause of the goal. Wording preferences and "you could also mention" notes are not
+defects.
+
+On FALSE, revise the goal, node and edge text. Most of what a critic finds are internal-consistency
+defects your own notes already answer, and those never need the repo. When it disputes a specific
+factual claim you can't settle from memory, go back — to that one function, not to the codebase.
+Re-reading everything once per round is the most expensive habit available here and it buys nothing.

package/skills/system-resource-triage/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: system-resource-triage
+description: Diagnose why a Linux box is slow, out of memory, or showing high load, explain the cause in two or three lines, propose a fix, offer to apply it, and report a before/after table. Use this whenever the user asks about CPU or memory utilisation, says the machine or dev box feels slow, sluggish or laggy, asks what is eating their RAM or CPU, mentions high load average, full swap, OOM kills, runaway or leaked processes, too many open processes, or zombies — and also when they simply paste top/htop/free/ps output and ask what is going on. It exists because the obvious readings mislead — ps %CPU is a lifetime average rather than current usage, load average is not the same as CPU busy, and per-process views hide problems that only show up in aggregate.
+---
+
+# System resource triage
+
+## What this is for
+
+Someone says "my machine is slow" or "check my CPU and memory". The naive answer is to run `top`,
+read off the first row, and name whatever sits at the top. That answer is usually wrong, and
+confidently wrong, because the default readings on a long-uptime box are averages over the life of
+the process rather than a description of now.
+
+This skill produces a short honest diagnosis, a proposed fix, and — if the user accepts — a
+measured before/after. The value is mostly in not being fooled during the measurement, and in not
+destroying something the user still needs during the fix.
+
+## Shape of the interaction
+
+Five beats, in order. Don't merge them and don't skip the pause.
+
+1. **Measure** — one pass, cheap, read-only.
+2. **Explain** — two or three lines. Not a report.
+3. **Suggest** — the specific fix, and what it will reclaim.
+4. **Offer** — stop and wait for a yes before touching anything.
+5. **Before/after** — a table, from numbers you captured *before* you acted.
+
+The pause at step 4 is the point. Freeing memory means killing processes, and the user is the only
+one who knows whether the thing you're about to kill matters.
+
+## Step 1: Measure
+
+Run `scripts/triage.sh`. It's read-only and takes a few seconds. It gathers everything below in one
+pass, which matters for a reason explained in the next section.
+
+```bash
+bash scripts/triage.sh              # group memory by process name
+bash scripts/triage.sh claude node  # or group by patterns matched against full command line
+```
+
+Pass patterns when process names are uninformative — VS Code's server processes are all called
+`MainThread`, so grouping by name tells you nothing and grouping by `vscode-server` tells you
+everything.
+
+## Reading the numbers without being fooled
+
+These are the traps. Each has bitten a real diagnosis.
+
+**`ps %CPU` is a lifetime average, not current usage.** It is total CPU consumed divided by process
+age. On a box up 64 days, long-lived daemons like `containerd` and `dockerd` routinely show 60-80%
+while using nothing at all right now. If you name them as the culprit you will be wrong. Take
+instantaneous CPU from the *second* sample of `top -bn2`.
+
+**The first row of `vmstat` is also a since-boot average.** Discard it. Always read row two onward.
+
+**Load average is not "CPU busy".** It counts runnable *and* uninterruptible processes. High load
+with high idle means the load is coming from somewhere other than CPU work. Decompose it before
+concluding anything:
+
+- `wa` high, processes in `D` state → I/O or swap thrashing.
+- `r` persistently above core count → genuine CPU contention.
+- both low, `cs` very high → scheduler churn, often just many idle pollers. Frequently harmless.
+- Load average is a decaying 1/5/15-minute mean, so it lags a fix by minutes. Don't judge a fix by
+  it immediately; `free` and `r` respond right away.
+
+**Aggregate before you conclude.** This is the single highest-value move. Forty-five processes at
+340 MB each never appear in `top`'s top ten, but they are 15 GB. Problems that live in the count
+rather than the size are invisible per-process and obvious in aggregate. The script does this
+grouping for you.
+
+**Read swap per process, not just in total.** `free` says swap is full; `/proc/PID/status`'s
+`VmSwap` says who put it there. A process swapped fully out shows near-zero RSS and looks innocent.
+
+**Your own measuring can create the symptom.** A loop that spawns a subprocess per PID across 1500
+PIDs generates tens of thousands of context switches and inflates the run queue — you then read
+that back and diagnose it as the problem. Prefer one `awk` pass over `/proc/*/status` to a shell
+loop, and if you see a run queue spike only while your own diagnostic runs, that's you. Re-measure
+with nothing else running before you believe a churn number.
+
+**Check zombies.** They cost no RAM or CPU, so they never surface in a memory hunt, but a large
+count means a parent isn't reaping and PID slots are leaking. The classic cause is a container
+whose PID 1 is `sleep infinity`, which never calls `wait()`. Group zombies by PPID to find the
+offender; the fix is giving that container a real init (`init: true`), not killing anything.
+
+## Step 2: Explain, in two or three lines
+
+Lead with which resource is actually constrained, name the cause, and give the number that proves
+it. If CPU is fine, say so first — it stops the user chasing it.
+
+> CPU is fine — 63% idle, no iowait. The problem is memory: 26 of 30 GB used and swap completely
+> full. 45 abandoned `claude` sessions, 2-21 days old with no terminal attached, account for
+> 15.5 GB of it.
+
+Resist expanding this. The evidence goes in the table later; anything you cut here the user can ask
+for. If you found something real but off-topic — leaked zombies, a container misconfiguration —
+hold it until after the main fix rather than diluting the headline.
+
+## Step 3: Suggest
+
+Name the specific action and what it reclaims. Prefer the smallest action with the largest return,
+and say what you are deliberately *not* touching, so the user can object.
+
+> Suggest SIGTERM on those 28 detached sessions — should return ~12 GB and drain most of swap. I'd
+> leave the VS Code servers alone since those are likely your live editor windows.
+
+If there are stages, order them most-reclaim-for-least-risk and plan to stop as soon as enough is
+free. Running stage 3 when stage 1 sufficed is how a routine cleanup becomes an outage.
+
+## Step 4: Offer, then act safely
+
+Ask, and wait. Once the user agrees:
+
+**Capture the "before" numbers first.** You cannot reconstruct them afterwards and the table is
+part of the deliverable. `scripts/triage.sh --snapshot /tmp/before.txt` saves them.
+
+**Dry run and show the list.** `scripts/reap.sh --name <pattern>` prints candidates and totals;
+nothing dies without `--confirm`. Let the user see actual PIDs and ages first.
+
+It only ever selects processes that are detached, older than `--min-age-days` (default 2), and
+owned by the current user. Kernel threads, init, other users' daemons, and zombies are excluded —
+a candidate list containing `dockerd` or `systemd` is a bug, and zombies are worth excluding
+because they hold no memory, so counting them inflates the reclaim estimate for no gain.
+
+**Kill the list you showed, verbatim.** Recomputing the candidate set at kill time reintroduces
+everything the review was meant to catch. Paste the reviewed PIDs.
+
+**Never kill your own session.** Walk `/proc/PID/status`'s `PPid` up from `$$` and exclude every
+ancestor. `reap.sh` does this and refuses to run if a protected PID appears in the list. Processes
+with a controlling terminal are attached to something a human is using — exclude those too.
+
+**SIGTERM, wait, then reconsider.** TERM lets sessions flush state to disk. Wait ~10 seconds and
+re-check. `kill -9` only for genuine stragglers, and it's worth asking again first.
+
+**In zsh, `kill $PIDS` fails.** zsh doesn't word-split unquoted variables, so a space-separated PID
+list is passed as one argument and the whole kill is rejected — easy to misread as success if you
+echo a count afterwards. Loop over the list, or use `${=PIDS}`. The scripts here use `bash`
+explicitly to sidestep this.
+
+**Reclaim swap last, and only with headroom.** Swap usually drains on its own as processes exit.
+If stale pages remain, `swapoff -a && swapon -a` forces them back to RAM — which OOMs the box if
+RAM isn't free yet. Verify free RAM exceeds used swap before running it, and skip it entirely if
+swap is already comfortable.
+
+## Step 5: Before/after table
+
+Re-measure and report. Keep it to the metrics that moved.
+
+```markdown
+| | Before | After |
+|---|---|---|
+| RAM used | 26 Gi / 30 Gi | 14 Gi / 30 Gi |
+| Available | 4.6 Gi | 15 Gi |
+| Swap | 4.0 Gi (100%) | 815 Mi (20%) |
+| Load (1m) | 8.30 | 5.91 |
+```
+
+Add one line on what you skipped and why ("swap drained on its own, so I didn't need `swapoff`"),
+and surface any secondary finding you held back.
+
+## Say so when a prediction misses
+
+If you predicted a number would move and it didn't, lead with that rather than letting the table
+quietly omit it. Concretely: context switches staying at 60-80k/s after removing 28 processes
+falsifies "idle pollers cause the churn", and the honest follow-up is a quick check of
+`/proc/interrupts` — high `CAL` and `TLB` on a KVM guest is normal hypervisor overhead, not
+something to chase.
+
+A fix that worked for a reason you got wrong is worth flagging, because the user will otherwise
+apply the wrong lesson next time. It also stops you from proposing the same wrong fix again.
+
+## Scope
+
+This covers diagnosis and reclaiming resources on a machine the user controls. Application-level
+memory profiling (heap dumps, leak hunting inside one process) is a different job — say so and
+stop rather than stretching this to fit.
+
+Two things are worth naming as out of scope even when they'd help, because they change the
+machine's configuration rather than its current state: restarting containers and editing service
+definitions. Report them as findings with the specific fix, and let the user decide.