halilneed
TREN

scar

scar mines the session logs Claude Code, Codex CLI and Gemini CLI already keep on your disk for failures that recur across separate sessions, drafts a rule, test brief or fix for each one, and later measures whether the lesson held. It makes no network calls and never writes into your repo on its own.

Error families
16
Verdicts
held, recurred, too recent, no evidence
Agents read
Claude Code, Codex CLI, Gemini CLI
Network calls
none
Licence
MIT

Example output

This is abridged from a real run of --mine --days 90 on the machine this site was built on. Rows that named private projects are left out and long error lines are truncated. The counts are what the miner printed. The scan made no network calls.

# scar — recurring failures

Source note: 156 sessions scanned (all, 90d) · 305 failure episodes
             · 6 low-confidence signatures dropped · 16 scars

| Id             | cost | sessions | projects | family            | artifact | error                        |
|----------------|------|----------|----------|-------------------|----------|------------------------------|
| `scar-0eqc684` |   68 |       14 |        5 | shell-quoting     | rule     | unexpected EOF while looki…  |
| `scar-0qkezmw` |   42 |        8 |        4 | edit-precondition | rule     | <tool_use_error>String to…  |
| `scar-12srzqa` |   36 |        6 |        5 | not-a-git-repo    | rule     | fatal: not a git repositor…  |
| `scar-08kw0mp` |   12 |        2 |        2 | timeout           | rule     | Command timed out after 2m…  |
| `scar-0w2b7dp` |   12 |        2 |        2 | compile-error     | test     | Build failed. Use dotnet b…  |

## What to do

`node scar.mjs --draft scar-0eqc684` → rule

The ranking is by cost rather than raw count: separate sessions × 3, projects touched × 2, repeats capped, and +4 when more than one agent hit the same wall. One bad afternoon of retries counts as a single episode. The 16 families that classify each scar are a pattern list you can open, and the next step is printed under the table.

Install

# once
> /plugin marketplace add halilneed/plugins

# the plugin
> /plugin install scar@hailneed

# and try it
> /scar:mine

The marketplace id is hailneed, which is why the install line ends in @hailneed.

  • Claude Code and Node.js 18 or newer.
  • No dependencies, no API key, no quota spent.
  • It also runs standalone: node scripts/scar.mjs --mine --md --lang en
  • For CI, --verify --out verify.json has a stable output format. Gate on written[].verdict.

Commands

/scar:mine

Recurring failures, ranked by what they cost: which error came back in how many separate sessions and projects, the commands that failed, and what worked right after. When most episodes end with a different tool succeeding, the report says so, because the lesson is then a tool choice and not a better command.

/scar:write <id>

The durable lesson: a rule, a regression-test brief, an environment fix or a decision record. Each carries an evidence line and a scar marker so the result can be measured later. It shows you the draft and asks before it writes anything into your repo.

/scar:verify

Checks whether the lesson held. For every marked artifact, it gives the failure’s recurrence count before and after the artifact was written. There are four verdicts: held, recurred, too recent, no evidence. A “recurred” verdict means the rule did not stop the failure.

What it does and does not do

  • It makes no network calls and writes nothing into your repo. Drafts go to stdout, scar.mjs contains no fetch and no sockets, and you decide what lands in the repo.
  • There are 16 families and no model judgement. scars.mjs is a pattern list you can read, and --selftest runs it without touching your data.
  • Retry loops do not inflate the ranking. An episode is one run of consecutive failures plus the first success after it, so twenty attempts in one session is one lesson.
  • verify depends on the marker. It counts recurrences before and after the marker’s date, so a rule without a marker cannot be measured.
  • Unreadable sessions and dropped low-confidence signatures are counted in the source note.
  • MIT-licensed (LICENSE). No account, no signup, no telemetry.

Planned

A hosted version, scar Cloud, is planned. The plugin stays free and local.

  • Team-wide scar pool: a failure one person hit becomes a rule for the whole team.
  • Rule-effectiveness time series: which lessons hold across the team, and which quietly stopped working.
  • Onboarding summary: the known traps in this repo, for new team members.

To hear when it exists, subscribe on the writing page.