feat(skill): lineage — backward decision archaeology, with a tool

Ports the technique #11 asked for and ships the script #19 asks for: was this
tried, what killed it, and is the killer still alive.

The RED run did excellent archaeology unaided — fourteen steps, correct verdict,
and it split the proposal into a goal worth keeping and a mechanism that had
failed, which is the finding. What it never ran was `git log -S`, and what it
leaned on hardest was the issue tracker. Both facts shaped the skill.

The GREEN run then broke the tool's central claim, live. Asked about a feature
this repo removed and argued about at length, `lineage.sh "per repo"` printed:

  no trace of "per repo" — that is a real finding: it means this is new here

Flatly wrong; the term simply had a space in it. Worse, the skill's own
anti-pattern table forbids that exact inference — "assuming absence means it was
never considered" — so the tool was printing, in its own voice, the mistake the
skill warns against. A no-match now says it is one string against one repo, and
names the variants to try before anyone concludes novelty. The test asserts the
refusal rather than the old message.

Three more from the same run:

- The tool searched `docs/adr/*` for decision records. This repo has no `docs/`,
  and this estate keeps decisions in the brain and in gitea comments — so that
  section silently searched nothing four times, and its null was indistinguishable
  from a real one. It now names both unsearchable sources on every run, and the
  skill makes `brain_query` a step: the single best artifact in the GREEN run came
  from the brain and nowhere else.
- Step 1 steered readers toward path-scoped log and away from `-S`. Backwards. A
  function deleted from a file that still exists is the dominant removal shape,
  and `-S<identifier>` returns birth and death on one screen while the path search
  buries it. Rewritten to lead with the identifier.
- "Which conditions still hold" had no method, and the run answered it by running
  commands against the live host in twenty seconds. Now a table: one command per
  claim, because "the record says X" and "X is true right now" are different
  answers and only the second is worth giving.

Also fixed: the tool defaulted to the cwd and would return a confident null
against the wrong repo in a worktree-heavy setup. It now prints which repo it
searched, every run.

Closes #11
Bump-Type: minor

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "skills",
   "description": "Mathias's engineering skills library, plus the hooks and MCP servers that make it enforceable: TDD, clean code, debugging, specs, discovery, CI, and secret hygiene.",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "author": {
     "name": "Mathias",
     "url": "https://git.d-ma.be/mathias"

SKILLS_INDEX.md

@@ -9,18 +9,20 @@ the SKILL.md, not the table.
 <!-- BEGIN skills-table -->
 | Skill | Description | Use when | Surfaces |
 |-------|-------------|----------|----------|
+| `adr` | Architecture Decision Records — house format, and how to record a decision you cannot make yet | Recording an architectural decision; revisiting one; or deciding between options where the right answer genuinely is not knowable yet | claude-code, library |
 | `atdd` | Acceptance Test-Driven Development workflow | Feature development with acceptance criteria | claude-code, library |
 | `cad-babysit` | Focused human-in-the-loop session working CAD's stuck queue (read-only) | Picking up whatever `cad stuck` flags, with a human present | claude-code, library |
 | `clean-code` | Clean code principles with Go adaptation | Code review, refactoring, new code | claude-code, library |
 | `code-review` | Code smell detection + Go-specific checklist | Pre-merge review | claude-code, library |
 | `cognitive-load` | Cognitive complexity analysis (CLI score) | Identifying hotspots, before refactoring | claude-code, library |
-| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious | claude-code, library |
+| `debug` | Hypothesis-first debugging discipline | Any test failure or bug whose cause is not immediately obvious — or a bug report with no failure text, which this skill refuses rather than guesses at | claude-code, library |
 | `discovery-framing` | Problem-before-solution discovery/framing method | Framing/validating a problem before any solution; opportunity sizing | claude-code, library |
 | `dream` | Reflective consolidation pass over an agent's memory directory | Pruning/merging memory files, rebuilding a memory index | claude-code, library, chat |
 | `experiment-spec` | Rigorous experiment spec — falsifiable hypothesis, quantitative acceptance, null-result protocol | Scoping a research/ML phase instead of a feature | claude-code, library |
 | `feature-spec` | Implementation-level feature spec (tighter than spec-driven-dev) | Scoping one feature inside an already-specced project | claude-code, library |
 | `gitea-ci` | Gitea CI/CD pipeline with act_runner, buildah, k3s, GitHub mirror | Setting up or debugging CI on this infra | claude-code, library |
 | `grill-me` | Structured plan interrogation — Quick Poke, Full Grill, Pre-mortem | Stress-testing a plan before committing; end of Diamond 1; before promoting to pre-prod | claude-code, library, chat |
+| `lineage` | Backward decision archaeology — was this tried before, and does the reason it failed still hold | Before proposing something that feels new; when an idea keeps resurfacing; when you inherit code whose reason is gone | claude-code, library |
 | `own-the-task` | Delegation ownership — Intake → Brief → Plan → Execute | A task is handed over open-ended; \"take this off my plate\"; before a plan exists | claude-code, library, chat |
 | `planning` | Planning and task breakdown | Sprint planning, task decomposition | claude-code, library |
 | `playwright` | Playwright E2E testing — setup, HTMX patterns, SSE streams, CI wiring | Adding browser tests to any project with a web UI | claude-code, library |

skills/adr/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: adr
+surfaces: [claude-code, library]
+summary: "Architecture Decision Records — house format, and how to record a decision you cannot make yet"
+use_when: "Recording an architectural decision; revisiting one; or deciding between options where the right answer genuinely is not knowable yet"
+description: Write an Architecture Decision Record in this estate's format — YAML frontmatter, Status/Context/Decision/Consequences/Validation — including the case where the tradeoff is genuinely context-dependent and forcing a resolution would be worse than preserving the tension. Use when recording or superseding an architectural decision, or when a decision keeps getting re-litigated because nobody wrote down why.
+---
+
+# ADR
+
+## Overview
+
+An ADR is the *record* of a decision — the artifact someone reads in eight months when
+they are about to undo it without knowing why it exists. It does not confer the decision;
+a person with authority does that, and this skill never is that person.
+
+Two things make one useful, and neither is the prose quality: a **format consistent
+enough to grep across repos**, and an honest account of **what was not decided**.
+
+## Before you write
+
+Both of these change what goes in the ADR, so they are not cross-references, they are
+steps:
+
+1. **`lineage`** — was this decided before and reversed? The reason it was dropped is
+   usually the most valuable sentence in your Context, and if an earlier ADR exists,
+   yours supersedes it rather than ignoring it.
+2. **`grill-me`** (Full Grill) — find the hole now. It is cheaper here than in the
+   Consequences section of the ADR that supersedes yours.
+
+## When to Use
+
+- Any choice where a reasonable alternative existed and was not taken
+- Superseding or amending an earlier ADR (never edit the old one — see Status)
+- A decision that keeps getting re-litigated, which means the reasoning was never recorded
+- A tradeoff that is genuinely context-dependent — see *Preserving a productive tension*
+
+**Do not use for:** implementation choices with no alternative worth naming, or anything
+a code comment answers. An ADR per function is an ADR nobody reads.
+
+## The format
+
+**Where it goes:** `docs/adr/NNNN-kebab-slug.md`, zero-padded to four digits, numbered
+sequentially within the repo. Frontmatter you cannot locate is not greppable, and half
+the value of the format is that `docs/adr/*` is a known path in every repo here.
+
+**The number is repo-local.** `cad` ADR-0002 and `infra` ADR-0002 are different
+documents. When referring across repos — including in `supersedes` — qualify it:
+`cad#0002`. Within a repo the bare number is fine.
+
+Frontmatter first. It exists so the corpus is machine-readable — "which ADRs does 0004
+supersede", "what is still `proposed`" — and a bespoke header block, however well
+written, cannot answer those.
+
+```markdown
+---
+adr:           0004
+title:         <the decision, as a sentence — not "database choice">
+status:        proposed | accepted | superseded | amended
+date:          2026-08-29
+deciders:      <who accepted it, by name — or "pending: <name>" while proposed>
+supersedes:    <adr number, or ->
+---
+
+# ADR-0004 — <same title>
+
+## Status
+
+**The frontmatter is authoritative for status and date.** This section exists for the one
+thing the frontmatter cannot hold: *why* it moved — what superseded it and on what
+evidence, or what accepting it was contingent on. If it would only restate the YAML,
+delete it.
+
+## Context
+
+The forces. What is true that makes this a decision rather than a default — constraints,
+the failure that prompted it, what was tried. Name the unknowns explicitly; a decision
+made under uncertainty is not weaker for saying so, it is auditable.
+
+## Decision
+
+One sentence of what was decided, then why *this* option rather than the named
+alternatives. Address the strongest case against, not the weakest.
+
+## Consequences
+
+**Positive:** what this buys.
+
+**Negative / watch:** what it costs, and the specific thing to watch that would tell you
+it was wrong. "Some added complexity" is not a consequence; "the event schema is now the
+coupling surface between cad and every executor — version it deliberately" is.
+
+## Validation
+
+How you will know. A link to the experiment or the metric that proves or kills it, and
+the condition that fires a revisit. An ADR with no validation section is a preference
+with a template around it.
+```
+
+## Preserving a productive tension
+
+Some tradeoffs are not unresolved because nobody thought hard enough. They are
+context-dependent, the context is not settled, and picking now means picking blind.
+Forcing resolution there produces a confident record that is wrong half the time.
+
+Record the tension instead, in the Decision section:
+
+```markdown
+## Decision
+
+Provisional: **<option A>**, on this reasoning: <what makes it safe to pick now>.
+
+<The strongest case for the option you did NOT take, and why it does not win today. The
+plain format demands this and a preserved tension does not get an exemption — the whole
+point is that the loser is still live.>
+
+### The tension, preserved
+
+- **Option A** — <what it assumes, what it costs>
+- **Option B** — <what it assumes, what it costs>
+
+**What we do not know:** <the variable that decides it>
+
+**Preservation strategy:** <what we build now so BOTH stay reachable. This is the
+technical content of the ADR, not a one-liner — enumerate it. It is usually the part both
+options need anyway, which is often most of the work: the schema, the interface seam, the
+idempotency key. Name each piece and say which option it keeps alive.>
+
+**Resolution triggers:** <plural, and one per unknown. Two independent unknowns do not
+collapse into one condition, and a trigger may exist that neither unknown implies.>
+```
+
+Two rules keep this from becoming an excuse:
+
+1. **A preserved tension still ships a decision.** "We will decide later" is not one.
+   Prefer the option whose correctness does not depend on the unknown, say so, and mark
+   it provisional.
+
+   **When no such option exists** — and often none does, because a tension is productive
+   precisely when both options are hostage to the same unknown — do not manufacture a
+   reason that one of them is. That reads as reasoned and will not be re-examined, which
+   makes it worse than an honest arbitrary pick. Fall back, in order: the option that is
+   cheaper to reverse; the one with the lower switching cost given your preservation
+   strategy; the one already built. Then **say that is why you picked it.** "Chosen
+   because it is the cheaper mistake" is a real justification and an auditable one.
+2. **The resolution trigger must be observable by someone who is not you.** "When it
+   becomes a problem" is not a trigger. "When executor count passes five and they are all
+   long-lived services in one cluster" is. A trigger nobody can evaluate is a decision
+   that quietly becomes permanent.
+
+`cad`'s ADR-0001 does this informally under *"Known refinements (recorded, deliberately
+not built yet)"* — sovereignty deferred to a 3-class model *"until a client actually opts
+into an EU provider"*. That clause is the pattern: option, cost, and the event that
+forces the choice.
+
+## Status discipline
+
+- **Never edit an accepted ADR to change its decision.** Write a new one and set
+  `supersedes`. The record of what was believed, and when, is the whole value.
+- **Amend** for corrections that do not change the decision (a broken link, a clarified
+  consequence). Note the amendment inline with its date.
+- **`proposed` is not a parking space.** An ADR that sits proposed for a month *with no
+  named decider* is a decision nobody is making; either accept it provisionally or close
+  it as declined. With a named decider it is a decision waiting on a person, which is a
+  different thing and is chased rather than closed.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|---|---|
+| Consequences that are all positive | Then it was not a decision, it was an announcement |
+| "We chose X because it is better" | Names no alternative and no force; unfalsifiable |
+| Written after the code shipped | Reverse-engineers a justification. Record the reasoning while it is still contested |
+| One ADR amended repeatedly | Destroys the history the format exists to keep |
+| No Validation section | Nothing distinguishes a good decision from a lucky one |
+| A tension "resolved" by picking arbitrarily | The next person re-litigates it, having lost the reasoning |
+
+## Escalation
+
+Writes a file, so it acts — but it decides nothing.
+
+Stop and hand back when: the deciders are not you — which, for an agent, is always. An
+ADR records a decision someone with authority made; writing one to *create* that
+authority is how a preference acquires a document number.
+
+So the deliverable is a draft marked `proposed` with **the person who must accept it named
+in `deciders` as `pending: <name>`**, and that hand-back stated in the response, not left
+implied. Naming the decider is the escalation, not a formality — an unnamed one is how a
+proposal sits for a month.
+
+That is the intended state for an agent-authored ADR, and it is not the parking-space
+failure below: a `proposed` ADR with a named decider is waiting on someone; one without is
+waiting on nobody.
+
+Also stop when the Context cannot be written without inventing a constraint. A missing
+force means the decision has not been thought through yet, and an ADR built on an
+invented one is worse than none: it will be cited.
+
+## Cross-References
+
+- `lineage` and `grill-me` — see *Before you write*; they change the content, so they are
+  steps rather than references.
+- `spec-driven-dev` / `feature-spec` — an ADR is the *why*; a spec is the *what*. If you
+  are describing behaviour, you are writing a spec.

skills/debug/SKILL.md

@@ -2,8 +2,8 @@
 name: debug
 surfaces: [claude-code, library]
 summary: "Hypothesis-first debugging discipline"
-use_when: "Any test failure or bug whose cause is not immediately obvious"
+use_when: "Any test failure or bug whose cause is not immediately obvious — or a bug report with no failure text, which this skill refuses rather than guesses at"
-description: Systematic hypothesis-first debugging. Generate 3-5 ranked hypotheses with verification steps before suggesting any fix. Use when encountering a bug, test failure, or unexpected behavior.
+description: Systematic hypothesis-first debugging. Requires the failure itself — error text, stack, run id or log — and names what it needs and stops if the report has none, rather than hypothesising into a vacuum. Given evidence, generates 3-5 ranked, falsifiable hypotheses with verification steps before suggesting any fix. Use when encountering a bug, test failure, or unexpected behavior.
 ---
 
 # Debug
@@ -12,7 +12,7 @@ description: Systematic hypothesis-first debugging. Generate 3-5 ranked hypothes
 
 Debugging is hypothesis generation, not fix generation. The first instinct — "try this and see if it works" — wastes time and teaches nothing. A disciplined debug session produces a small set of ranked, falsifiable hypotheses, each with a concrete verification command. The fix comes after one hypothesis is confirmed, not before.
 
-**Core principle:** A hypothesis you cannot verify in one command is not a hypothesis — it is a guess.
+**Core principle:** A hypothesis you cannot verify with a single bounded, decisive observation is not a hypothesis — it is a guess. In a repo that observation is usually one command. Above one it may be an instrumented run, or partitioning the last twenty CI runs by trigger type; what makes it a hypothesis is that the observation *discriminates*, not that it fits on one line.
 
 ## When to Use
 
@@ -25,6 +25,27 @@ Debugging is hypothesis generation, not fix generation. The first instinct — "
 - Compile errors with clear messages (just fix the typo)
 - Already-diagnosed bugs where you know the cause (go straight to TDD with a regression test)
 
+### Is it actually diagnosed?
+
+That last exclusion is the one people get wrong, because a confident wrong diagnosis feels
+exactly like a right one. It is diagnosed if you can state the mechanism *and* name the
+observation that would have proved it wrong. If the evidence is "we changed X and it got
+better", that is correlation with a deployment, and this skill applies.
+
+The strongest tell is a run of failed fixes — see below. Three plausible fixes that did
+not eliminate the symptom is not bad luck, it is the diagnosis being wrong.
+
+### Intake: what you need before hypothesising
+
+Before generating anything, confirm you have the failure itself — the error text, the
+stack, the failing run's id, the log. If the report is "it's flaky again" with no
+artifact, **name the specific thing you need and stop**. Iron Law 1 forbids "try X and
+see"; hypothesising into a vacuum is the same failure with better grammar, and it is
+worse because the output looks like analysis.
+
+This is the rule `cad-babysit` already enforces from the other side: read the issue's own
+comments and the job log *first*.
+
 ## Iron Laws
 
 1. **Never suggest "try X and see what happens."** Every hypothesis must have a specific expected outcome if correct.
@@ -36,8 +57,9 @@ Debugging is hypothesis generation, not fix generation. The first instinct — "
 A system with boundaries (CI → build → signing, API → service → database) hides the
 question "which component is wrong?" behind the question "why is the output wrong?".
 Specify, as a pre-step, what to log entering and leaving **each** boundary, plus
-whether config and environment actually propagated. One run of that narrows the search
+whether config and environment actually propagated. One run *that reproduces the failure* narrows the search to a
-to a single component.
+single component. On an intermittent fault a passing run narrows nothing, so leave the
+instrumentation in across several runs rather than concluding from one.
 
 This does not suspend Iron Law 2. Still emit 3-5 hypotheses — the boundary spec comes
 first in the output, and each hypothesis says which boundary observation would kill it.
@@ -53,6 +75,10 @@ than fixes that partially worked.) Each one has been narrowing a window rather t
 closing it, and a fourth guess buys another tenth of the rate plus a layer of
 interacting guards nobody can reason about.
 
+Intake still gates this section. A report of three failed fixes with no artifacts fires
+both rules at once, and intake wins: you cannot aim hypotheses at a premise you have no
+evidence about either. Ask for the log, then aim.
+
 Say that explicitly — the refusal is the finding, not a preamble to it. Then aim the
 hypotheses one level up: the premise those fixes share is itself the thing to falsify.
 This is not an exemption from the output format. It is the format, pointed at the
@@ -76,18 +102,28 @@ For each hypothesis, capture three things:
 - **Verification:** the single command or file inspection that confirms or denies it
 - **Expected outcome if correct:** the specific output you would see
 
-Order by likelihood. The most likely cause is hypothesis 1.
+Order by likelihood, most likely first. **The ordering is the ranking — do not also
+attach `high`/`medium`/`low` labels.** With five slots and three labels the labels stop
+discriminating (two hypotheses are genuinely both "high" and the label cannot say which
+comes first), and a reader then has two orderings that can disagree. Position already
+carries it.
+
+Where you can say *why* one outranks another — a prior brain entry, a matching symptom,
+a recent change in that area — say that instead of a label. That is information; a label
+is a restatement of the order it sits next to.
 
 ### Step 3: Output
 
 Use this format:
 
 ```
-HYPOTHESIS 1 (likelihood: high): <mechanism in one sentence>
+HYPOTHESIS 1: <mechanism in one sentence>
-VERIFY: <exact command or file:line to inspect>
+WHY FIRST: <what makes it likeliest — a matching symptom, a recent change, a brain entry>
+VERIFY: <exact command, or the bounded observation that discriminates>
 EXPECTED IF CORRECT: <specific output, value, or condition>
 
-HYPOTHESIS 2 (likelihood: medium): <mechanism>
+HYPOTHESIS 2: <mechanism>
+WHY FIRST: <or why it ranks here rather than first>
 VERIFY: <exact command>
 EXPECTED IF CORRECT: <specific output>
 
@@ -109,15 +145,15 @@ End with the recommendation, not a fix.
 **Output:**
 
 ```
-HYPOTHESIS 1 (likelihood: high): parser indexes into pages[0] before checking len(pages) > 0; empty PDFs produce a zero-page document
+HYPOTHESIS 1: parser indexes into pages[0] before checking len(pages) > 0; empty PDFs produce a zero-page document
 VERIFY: rg -n 'pages\[0\]' internal/parser/
 EXPECTED IF CORRECT: at least one site reads pages[0] without a preceding length check
 
-HYPOTHESIS 2 (likelihood: medium): the test fixture is a zero-byte file rather than a valid empty PDF; pdf library returns nil pages slice instead of empty
+HYPOTHESIS 2: the test fixture is a zero-byte file rather than a valid empty PDF; pdf library returns nil pages slice instead of empty
 VERIFY: ls -la testdata/empty.pdf && file testdata/empty.pdf
 EXPECTED IF CORRECT: file size 0 bytes or "data" rather than "PDF document"
 
-HYPOTHESIS 3 (likelihood: low): a recently changed dependency reordered the page-extraction API; pages[0] now refers to metadata, not content
+HYPOTHESIS 3: a recently changed dependency reordered the page-extraction API; pages[0] now refers to metadata, not content
 VERIFY: git log --oneline -10 -- go.sum | grep -i pdf
 EXPECTED IF CORRECT: a pdf-library bump in the last few commits
 
@@ -131,6 +167,7 @@ RECOMMENDED NEXT STEP: Run VERIFY for hypothesis 1 first.
 | "Maybe try restarting the service" | Not a mechanism. Not falsifiable. Teaches nothing if it works. |
 | "Could be a race condition" | Mechanism without specifics. Which two operations race? On what state? |
 | "Let me add some print statements and see" | Skips hypothesis generation. Generates noise, not understanding. |
+| Answering "what's the fix?" from a report with no artifact | Hypothesising into a vacuum. The output looks like analysis, which is what makes it worse than saying "I need the log". |
 | Single hypothesis presented as fact | If you are sure, write the regression test, do not run a debug skill. |
 | Mixing hypotheses with fix suggestions | The skill is diagnose-only. The fix is a TDD task on its hypothesis. |
 
@@ -139,7 +176,8 @@ RECOMMENDED NEXT STEP: Run VERIFY for hypothesis 1 first.
 The brain holds prior debug sessions across the project. Use it to skip rediscovering known failure modes.
 
 **At debug start:**
-- Run `brain_query` with the error message snippet + the package name. Past sessions may have logged identical or similar failures with their resolved hypotheses.
+- Run `brain_query` with the error message snippet + the package name. On an intake stop you have neither — query the symptom and the component instead ("signed artifact missing CI"), which is worth doing precisely because it may name the artifact to ask for. Past sessions may have logged identical or similar failures with their resolved hypotheses.
+- **A hit is evidence, so cite it inline in the hypothesis it informs** — `(brain: <entry-name>)` — rather than mentioning it once at the top. If a prior entry is why a hypothesis ranks first, the reader needs that at the hypothesis, not in a preamble. If a prior entry contradicts your ranking, say so and rank it anyway if the evidence here is better; the brain records what was true then.
 
 **After a hypothesis is confirmed:**
 - Run `brain_write` with the failure signature → confirmed mechanism. Future debug sessions on the same area get the answer immediately.
@@ -156,7 +194,12 @@ treats `pass` as success, `fail` as failure, `skip` as neither.
 **At end of each phase:**
 - `session_log` with `{session_id: "<this session's id>", skill: "debug", phase: "<phase-name>", final_status: "pass" | "fail" | "skip", message: "<one-line summary>", project_root: "<absolute path>"}`
 
-**Phases for this skill:** read-failure, generate-hypotheses, output
+**Phases for this skill:** intake, read-failure, generate-hypotheses, output
+
+`intake` exists so that refusing correctly is recordable. A run that stops for want of a
+run id has done the right thing and logs `intake` / `pass`; without that phase the
+refusal logs as a failed `read-failure`, and a metric that penalises the skill's best
+behaviour teaches the next model to hypothesise into the vacuum instead.
 
 **Status semantics:**
 - `pass` — the phase's intended outcome was reached.
@@ -179,7 +222,9 @@ Techniques kept in `debug/references/`, inherited from the deleted
 - `defense-in-depth.md` — load after a root cause is confirmed, to decide which layers
   should have caught it.
 - `condition-based-waiting.md` — load whenever a timeout appears anywhere in the report,
-  including as one of the fixes already tried. A bumped timeout is a symptom.
+  including as one of the fixes already tried. A bumped timeout is a symptom. Not during an
+  intake stop: if you are not analysing yet, a symptom-analysis reference is on the wrong
+  side of the gate.
 - `find-polluter.sh` — run when a test passes alone and fails in the suite, or when
   something in the tree appears that no test admits to creating.
 

skills/lineage/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: lineage
+surfaces: [claude-code, library]
+summary: "Backward decision archaeology — was this tried before, and does the reason it failed still hold"
+use_when: "Before proposing something that feels new; when an idea keeps resurfacing; when you inherit code whose reason is gone"
+description: Backward decision archaeology. Find out whether an idea was already tried here, why it was dropped, and whether that reason still applies — using git history, decision records and the issue tracker rather than asking whoever is still around. Use before proposing a change that feels novel, when inheriting unexplained code, or when the same idea keeps being re-litigated.
+---
+
+# Lineage
+
+## Overview
+
+Most "new" ideas in an established codebase are revivals. The valuable question is never
+"is this a good idea" in the abstract — it is **"was this tried, what killed it, and is
+the killer still alive?"**
+
+A past failure is not evidence against trying again. It is context for trying again
+differently, and the difference between those two readings is usually one commit message.
+
+## When to Use
+
+- Before proposing something that feels new in a codebase older than you
+- When an idea keeps resurfacing and being re-argued from scratch
+- When you inherit code and cannot tell whether a constraint is load-bearing or vestigial
+- Before writing an ADR — the reason a thing was dropped belongs in your Context section
+
+**Do not use for:** code you wrote this week, or a question the current code answers.
+Archaeology on a live construction site is just reading.
+
+## The tool
+
+```sh
+skills/lineage/lineage.sh <term> [repo-path]
+```
+
+Runs the searches people skip because they are fiddly to type. In particular
+`git log -S<term>`, which finds commits where the term's **occurrence count changed** —
+so it surfaces the *removal* as well as the introduction. A plain `--grep` never finds a
+deletion, and the deletion is the whole point.
+
+It also lists files that once carried the term and no longer exist, and names the two
+sources it cannot search for you.
+
+**A no-match is not a finding.** The first version of this tool said a null meant "this is
+new here"; a pressure test caught it asserting exactly that about the most-discussed
+removed feature in this repo — the search term merely had a space in it. One string
+against one repo proves nothing. Try at least three variants (the identifier name, a
+one-word form, the name it would have had) and the brain and tracker searches before
+telling anyone an idea is novel. This is the same rule as the anti-patterns table below,
+and it is there because the tool broke it.
+
+Note also that `--grep` takes a regex and `-S` takes a literal string, so a term
+containing `.`, `[`, `*` or `+` matches differently in the two halves of the output.
+
+## The sequence
+
+**1. Search on the identifier, not the concept.** If the thing had a name in the code —
+a function, a flag, a config key — `git log --all -S<name>` typically returns exactly two
+commits, its birth and its death, on one screen. That is the fastest path to the answer in
+this whole sequence.
+
+Path-scoped log (`git log --all -- <file>`) is the weaker move and it is the one people
+reach for: a function deleted from a file that still exists is the *dominant* removal
+shape, and the path search buries it under every other commit that touched the file.
+
+Concept words are the fallback, and they are lossy — a term with a space in it will miss
+the record entirely. Try several spellings before you conclude anything.
+
+**2. Read the removal commit's full body, not its subject.**
+
+```sh
+git log -1 --format=%B <sha>
+git show --stat <sha>
+```
+
+This is where the answer almost always is. A subject line says *what*; the body says
+*why*, and the why is what you came for. Read the diff too — what was removed alongside
+it tells you how load-bearing it was.
+
+**3. Search outside git — that is where this estate keeps its reasoning.** Two sources,
+both routinely decisive, neither reachable from a commit log:
+
+- **The brain** (`brain_query`). Postmortems and generalized rules live there. In the run
+  that shaped this skill, the single best artifact — the rule abstracted from the incident,
+  with detection one-liners — came from the brain and from nowhere else.
+- **The issue tracker, including comments.** The commit records *that* something was
+  removed; the argument for it is usually in a comment. Search closed issues especially —
+  a closed issue is where a decision usually is.
+
+A git-only search finds the what and misses the why.
+
+**4. Test whether the failure conditions still hold — empirically, not from the record.**
+This is the step that makes the whole exercise worth doing, and it is the one that gets
+hand-waved. Write the conditions down as separate claims, then **run a command per claim**:
+
+| Claim from the record | How you check it today |
+|---|---|
+| "absolute links break across two path roots" | `readlink` one, `test -e` it on this host |
+| "it is gitignored, so nobody sees the rot" | `grep` the ignore file |
+| "the detector does not cover it" | `grep` the detector for the path it scans |
+
+Twenty seconds each, and it converts *"the record claims X"* into *"X is true right now"* —
+which is the only form of the answer worth giving. A constraint that has since been
+removed turns a dead idea live; one that is still true kills a revival on the spot.
+
+**5. Separate the mechanism from the goal.** A revival proposal usually bundles both, and
+they can have opposite verdicts: the goal is still worth wanting, the mechanism is the one
+that failed. Splitting them is often the whole finding — you end up agreeing with the
+proposer and rejecting their implementation, which is a far more useful answer than yes
+or no.
+
+## What "it was tried and failed" can mean
+
+| Reading | Tell | What to do |
+|---|---|---|
+| **Structurally impossible** | The removal commit says *why* it cannot work, not that it broke | Believe it. Look for a different mechanism for the same goal |
+| **Failed under conditions that changed** | The blocker names a version, a host, a tool that has since moved | Re-open it, citing what changed |
+| **Failed on execution** | It broke, was reverted, nobody diagnosed it | Genuinely undecided. The revival is legitimate; budget for the diagnosis |
+| **Never actually tried** | Discussed, an issue exists, no commit | There is no evidence either way. Say so rather than inheriting someone's pessimism |
+| **Still there, in a different shape** | The idea returned under another name | The most missable one — check before you build it twice |
+
+## Output
+
+Answer the question that was asked, then show your work:
+
+- **Verdict** — tried / not tried / tried and later restored differently
+- **The decisive artifact** — commit sha, issue number, or ADR, so the reader can check
+- **What killed it**, quoted from the source rather than paraphrased
+- **Whether that still applies**, per condition, not as a single yes or no
+
+If the decisive evidence is one commit message, quote it. A conclusion that makes the
+reader re-run your search has not saved them anything.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails |
+|---|---|
+| `--grep` only | Finds discussion, misses deletions. The deletion is the evidence |
+| Reading the commit subject and stopping | Subjects say what; you need why |
+| Treating a past failure as a verdict | Conditions change. That is the entire question |
+| Git-only search | The argument is usually in the issue tracker |
+| "It was tried and it failed" with no sha | Unverifiable, and it will be re-litigated next quarter |
+| Assuming absence means it was never considered | It may have been rejected in a conversation. Say what you searched |
+
+## Escalation
+
+Read-only. Reports what the record says; changes nothing and revives nothing.
+
+Stop and hand back when: the record is genuinely silent — no commit, no issue, no ADR.
+State what you searched and that nothing exists, rather than inferring intent from
+absence. Someone deciding not to build a thing and nobody ever considering it look
+identical in git, and only one of them is an argument.
+
+Also stop when the answer turns on why a *person* did something and the record does not
+say. Ask them. Reconstructing a colleague's reasoning from a diff is how a guess acquires
+a citation.
+
+## Cross-References
+
+- `adr` — what you find here belongs in the Context section of the ADR you are about to
+  write. If the thing was decided before, your ADR supersedes that one; say so.
+- `debug` — the same discipline aimed at a failure rather than a decision: evidence
+  before hypothesis, and the removal commit is evidence.

skills/lineage/lineage.sh

@@ -0,0 +1,99 @@
+#!/bin/sh
+# lineage.sh — decision archaeology for one term.
+#
+# Answers "why does X exist, was it tried before, and is this 'new' idea a
+# revival?"
+#
+# Its real value is that it makes you run `git log -S` at all — that is a nudge,
+# not a capability. -S finds commits where the term's occurrence COUNT changed,
+# so it surfaces a removal; --grep only finds people talking about one. On an
+# identifier name (`wire_claude_repo`) -S typically returns exactly two commits,
+# birth and death, which is the fastest path to the answer in this whole file.
+#
+# Note the two searches do not match the same way: --grep takes a regex, -S takes
+# a literal string. A term containing . [ * + behaves differently in each.
+#
+# Usage: lineage.sh <term> [repo-path]
+#
+# Read-only: nothing here writes, and it never touches the index or worktree.
+
+set -u
+
+[ $# -ge 1 ] || { echo "usage: lineage.sh <term> [repo-path]" >&2; exit 2; }
+TERM_=$1
+REPO=${2:-.}
+
+git -C "$REPO" rev-parse --git-dir >/dev/null 2>&1 || {
+  echo "lineage: $REPO is not a git repository" >&2; exit 2; }
+
+# Say which repo, always. The default is the cwd, and in a worktree-heavy setup
+# that is routinely not the repo the caller means — a confident null against the
+# wrong tree is the worst thing this tool can produce.
+TOPLEVEL=$(git -C "$REPO" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$REPO")
+printf 'searching: %s   term: "%s"\n' "$TOPLEVEL" "$TERM_"
+
+FMT='%h  %ad  %an  %s'
+DATE='--date=short'
+found=0
+
+section() { printf '\n== %s ==\n' "$1"; }
+
+# 1. Commits whose MESSAGE mentions it — the stated reasoning.
+msgs=$(git -C "$REPO" log --all -i --grep="$TERM_" --format="$FMT" $DATE 2>/dev/null || true)
+if [ -n "$msgs" ]; then
+  found=1
+  section "Commits that talk about it (message)"
+  printf '%s\n' "$msgs"
+fi
+
+# 2. Commits where the term was ADDED or REMOVED — the actual history.
+#    -S counts occurrences, so a deletion shows up here and nowhere else.
+picks=$(git -C "$REPO" log --all -S"$TERM_" --format="$FMT" $DATE 2>/dev/null || true)
+if [ -n "$picks" ]; then
+  found=1
+  section "Commits where it appeared or disappeared (-S)"
+  printf '%s\n' "$picks"
+  printf '\n   Oldest is the introduction. Anything after it that removed the term is\n'
+  printf '   the interesting one: read that commit before proposing this again.\n'
+fi
+
+# 3. Files that once contained it and no longer exist.
+deleted=$(git -C "$REPO" log --all --diff-filter=D --name-only --format='%h' -S"$TERM_" 2>/dev/null \
+  | grep -v '^[0-9a-f]\{7,\}$' | grep -v '^$' | sort -u || true)
+if [ -n "$deleted" ]; then
+  found=1
+  section "Files deleted that carried it"
+  printf '%s\n' "$deleted"
+  printf '\n   Recover one with: git -C %s show <sha>^:<path>\n' "$REPO"
+fi
+
+# 4. Decision records naming it.
+docs=$(git -C "$REPO" grep -l -i "$TERM_" -- 'docs/adr/*' 'docs/decisions/*' 'docs/*.md' 'ADR*' 2>/dev/null || true)
+if [ -n "$docs" ]; then
+  found=1
+  section "Decision records naming it"
+  printf '%s\n' "$docs"
+fi
+
+# This estate keeps most of its reasoning OUTSIDE the repo, so the two searches
+# this tool cannot run are usually the decisive ones. Say so every time rather
+# than letting their absence read as a null result.
+section "Not searched here — do these by hand"
+printf 'brain:  brain_query "%s" — decisions and postmortems live there, not in docs/\n' "$TERM_"
+printf 'gitea:  closed issues and their COMMENTS. The argument for a removal is\n'
+printf '        usually in a comment; the commit only records that it happened.\n'
+
+if [ "$found" -eq 0 ]; then
+  printf '\nno match for the exact string "%s" in %s.\n' "$TERM_" "$TOPLEVEL"
+  printf 'This is NOT evidence the idea is new. It is one string against one repo.\n'
+  printf 'Before concluding anything, try: the identifier or function name; a\n'
+  printf 'one-word variant (spaces and punctuation break the match); the name it\n'
+  printf 'would have had; and the brain and issue searches above.\n'
+  exit 0
+fi
+
+printf '\n-- what this cannot tell you --------------------------------------------\n'
+printf 'Why it was removed, if it was. The commit subject is a summary; read the\n'
+printf 'body, the PR, and the issue it closed. A past failure under conditions that\n'
+printf 'no longer hold is not evidence against trying again — it is context for\n'
+printf 'trying again differently.\n'

skills/tdd/SKILL.md

@@ -365,7 +365,7 @@ Before marking work complete:
 - [ ] Tests use real code (mocks only if crossing a system boundary)
 - [ ] Edge cases and errors covered
 
-Can't check all boxes? You skipped TDD. Start over.
+Can't check **or deliberately strike** all boxes? You skipped TDD. Start over. A box struck with a stated reason is answered; a box left hanging is not.
 
 ## When Stuck
 
@@ -374,7 +374,7 @@ Can't check all boxes? You skipped TDD. Start over.
 | Don't know how to test | Write wished-for API. Write assertion first. Ask Mathias. |
 | Test too complicated | Design too complicated. Simplify interface. |
 | Must mock everything | Code too coupled. Use dependency injection. |
-| Test setup huge | Extract helpers with `t.Helper()`. Still complex? Simplify design. |
+| Test setup huge | Extract helpers (`t.Helper()` in Go, a local `__tracebackhide__ = True` in Python). Still complex? Simplify design. |
 
 ## Debugging Integration
 

tests/lineage_test.sh

@@ -0,0 +1,90 @@
+#!/bin/sh
+# Tests for skills/lineage/lineage.sh — the decision-archaeology helper.
+#
+# The techniques this automates are the ones people skip because they are
+# fiddly to type: `git log -S` to find when a thing was introduced AND removed,
+# --diff-filter=D to find files that once existed, and grepping decision records
+# for the term. A skill that only *describes* those is a skill that gets read and
+# not run (#11, #19's "small robust tools over prose").
+
+set -u
+
+ROOT=$(CDPATH= cd -- "$(dirname -- "$0")/.." && pwd)
+SUT="$ROOT/skills/lineage/lineage.sh"
+
+pass=0
+fail=0
+WORK=${TMPDIR:-/tmp}/lineage_test.$$
+
+if [ ! -f "$SUT" ]; then
+  printf 'FAIL: %s does not exist\n' "$SUT"
+  exit 1
+fi
+
+cleanup() { rm -rf "$WORK"; }
+trap cleanup EXIT INT TERM
+
+# A repo where a thing was built, written about, and then removed.
+mkdir -p "$WORK/repo/docs/adr"
+cd "$WORK/repo" || exit 1
+git init -q .
+git config user.email t@example.com
+git config user.name test
+
+printf 'func WidgetCache() {}\n' > cache.go
+git add -A && git commit -qm "feat: add WidgetCache for lookup speed"
+
+printf -- '---\nadr: 0001\ntitle: use a WidgetCache\n---\nWe chose WidgetCache over a database index.\n' > docs/adr/0001-widgetcache.md
+git add -A && git commit -qm "docs: record the WidgetCache decision"
+
+git rm -q cache.go
+git commit -qm "revert: drop WidgetCache, it went stale under concurrent writes"
+
+cd - >/dev/null || exit 1
+out=$(sh "$SUT" WidgetCache "$WORK/repo" 2>&1)
+
+check() {
+  if printf '%s' "$out" | grep -q "$1"; then
+    pass=$((pass + 1)); printf '  ok   %s\n' "$2"
+  else
+    fail=$((fail + 1)); printf '  FAIL %s\n       output had no %s\n%s\n' "$2" "$1" "$out"
+  fi
+}
+
+check 'add WidgetCache'            'finds the commit that introduced it'
+check 'drop WidgetCache'           'finds the commit that removed it — the revival question'
+check '0001-widgetcache.md'        'finds the decision record naming it'
+check 'cache.go'                   'names the file that no longer exists'
+
+# A no-match must NOT be reported as evidence the idea is new. The first version
+# of this tool said "it means this is new here" and a pressure test caught it
+# asserting exactly that about the most-discussed removed feature in this repo —
+# the search term simply had a space in it. That is the inference the skill's own
+# anti-pattern table forbids, printed in the tool's voice.
+out=$(sh "$SUT" NeverExisted "$WORK/repo" 2>&1)
+if printf '%s' "$out" | grep -q 'NOT evidence the idea is new' \
+   && printf '%s' "$out" | grep -qi 'identifier'; then
+  pass=$((pass + 1)); printf '  ok   a no-match refuses to imply novelty and suggests other terms\n'
+else
+  fail=$((fail + 1)); printf '  FAIL a no-match refuses to imply novelty and suggests other terms\n%s\n' "$out"
+fi
+
+# The repo actually searched is always stated — a confident null against the
+# wrong tree is this tool's worst failure mode, and the default is the cwd.
+out=$(sh "$SUT" WidgetCache "$WORK/repo" 2>&1)
+if printf '%s' "$out" | grep -q "searching: "; then
+  pass=$((pass + 1)); printf '  ok   names the repo it searched\n'
+else
+  fail=$((fail + 1)); printf '  FAIL names the repo it searched\n%s\n' "$out"
+fi
+
+# The sources it cannot reach are named every run, so their absence never reads
+# as a null result.
+if printf '%s' "$out" | grep -q 'brain_query' && printf '%s' "$out" | grep -qi 'closed issues'; then
+  pass=$((pass + 1)); printf '  ok   names the sources it cannot search\n'
+else
+  fail=$((fail + 1)); printf '  FAIL names the sources it cannot search\n%s\n' "$out"
+fi
+
+printf '\nlineage: %d passed, %d failed\n' "$pass" "$fail"
+[ "$fail" -eq 0 ]