skills: decompose prove-it into a principle plus four evidence products

corpus/skills/principle-prove-it/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: principle-prove-it
+description: "Apply before any claim about code, systems, or history. No claim without same-turn evidence; a hedge is a trigger to verify, never a place to stop. Routes the four investigation products that build the evidence. Unlike the other principles this one auto-fires: it must intercept a claim as it forms, not be named after the fact."
+---
+
+# Prove It
+
+A claim is settled only when the evidence for it is in the same message.
+Everything else is a hypothesis and must say so.
+
+**Why:** the cheap signal always stands in for the expensive one. A build
+passes and gets reported as "it works." A file exists and gets reported as
+"it's wired up." A name matches and gets reported as "that's the bug." Each
+substitution is individually reasonable and collectively how wrong answers
+reach the user with confidence attached.
+
+## The gate
+
+Before writing any claim of the form "this is fixed," "this works," "the
+cause is X," "it's merged," "N are running" — you must already have, in the
+same message, one of:
+
+1. A command run this turn, with its real pasted output. Not summarized.
+2. A `file:line` read this turn, named with the ref it was read at.
+3. A test name plus its real pass/fail line from the runner.
+
+Otherwise write `UNVERIFIED:` immediately before the claim. There is no
+softer wording. The full evidence rules live in `engine/CLAUDE.core.md` and
+are always loaded; this file is the judgment half plus the routing below.
+
+**A hedge is a trigger.** "I think," "probably," "should work" mean run the
+check now, not lower the confidence and continue.
+
+**Absence of output is not proof of success.** A command that printed
+nothing needs its exit code shown.
+
+## What builds the evidence
+
+The gate says what counts. It does not gather anything. Four product skills
+do that, each fanning out to parallel subagents and returning the shape in
+`corpus/skills/principle-prove-it/references/finding-shape.md`:
+
+| Product | Question | Returns |
+| --- | --- | --- |
+| `how` | How does this work now? | The mechanism you must exercise |
+| `why` | Why is it shaped this way? | The constraint you must not break |
+| `alternatives-considered` | What else could this be? | Options, each labeled considered or invented |
+| `spike-and-validate` | Does the invented one hold? | A throwaway that ran, and its real output |
+
+They compose in that order and each is optional. A one-line fix needs none
+of them. A claim about a subsystem nobody on the team has read needs `how`
+before anything else.
+
+The pairing that matters: `alternatives-considered` **generates**, so it can
+always produce three plausible options and none of them are evidence.
+`spike-and-validate` is its gate. An invented option that reaches a decision
+without a spike is exactly the manufactured evidence this principle exists
+to stop.
+
+## Related
+
+- `prove-it-ship-gate` — the done/shipped auto-route for live side effects.
+- `principle-fix-root-causes` — reproduce before explaining.
+- `principle-sequence-verifiable-units` — end each unit in a check.
+- Mechanical enforcement: `engine/hooks/prove-it-ship-gate`,
+  `engine/hooks/hedge-runs-prove-it`, `engine/hooks/diu-stop`.

corpus/skills/principle-prove-it/references/finding-shape.md

@@ -0,0 +1,45 @@
+# Shared finding shape
+
+Every investigation product (`how`, `why`, `alternatives-considered`,
+`spike-and-validate`) fans out to parallel subagents and merges their
+returns. They share this shape so `principle-prove-it` can consume any of
+them without a per-skill adapter.
+
+This is **not** the judge board in `product/skills/independent-judge-swarm`.
+That board grades a finished artifact (`verdict`, `score`,
+`blocking_issues`). These skills return findings about work that has not
+happened yet, so there is nothing to grade.
+
+## Fields
+
+| Field | Shape |
+| --- | --- |
+| `lens` | string — which angle this subagent owned |
+| `claim` | string — one sentence, the thing found |
+| `grounding` | `read-confirmed` \| `name-matched` \| `inferred` \| `invented` |
+| `evidence` | `file:line` + ref, a command + its real output, or a URL |
+| `ref` | which ref `evidence` was read at: working tree, `HEAD`, `origin/<base>`, installed bundle |
+| `null_result` | string — what was searched and came back empty |
+
+## Rules
+
+- A subagent that found nothing still returns a row with `null_result` set.
+  Silence is not the same as absence, and a skipped source is not a null —
+  see the Evidence rules in `engine/CLAUDE.core.md`.
+- `grounding: read-confirmed` means the subagent opened the actual
+  reference and traced it. `name-matched` means the path or symbol name
+  looked right. A working-tree read under a dirty path is `name-matched`.
+- `grounding: inferred` and `grounding: invented` rows carry no authority
+  on their own. They are hypotheses. Route an `invented` row that matters
+  to `spike-and-validate` before it reaches a decision.
+- The merge step reports disagreement rather than resolving it silently.
+
+## Merge
+
+1. Group rows by `claim`.
+2. Two subagents reaching the same `read-confirmed` claim independently is
+   the strongest signal available here. Check they were not handed the same
+   anchor and prompt first — template-identical attempts converge on the
+   same wrong answer exactly like independent ones agree.
+3. Any `read-confirmed` row beats any number of `inferred` rows.
+4. Report every `null_result` in the output. Do not drop it for brevity.

corpus/skills/principle-prove-it/tests/fires_example.md

@@ -0,0 +1,15 @@
+An agent has just edited a retry handler and is about to write "this fixes
+the duplicate-write bug" into a PR body. Nothing ran this turn: no repro, no
+test, no command output. The agent never types a slash command.
+
+This skill fires on the claim shape itself. Unlike the other `principle-*`
+skills, it does not carry `disable-model-invocation: true`, so its
+`description:` is loaded and the model can match it — which is the whole
+point: a gate that only works when someone remembers to name it is not a
+gate. A fix claim with no evidence in the same message is exactly what the
+description targets, and once loaded the skill supplies both the three
+accepted evidence forms and the routing table that sends the agent to `how`
+to find which artifact to exercise.
+
+The same auto-fire path covers the hedge case: "this should work" is a
+trigger to run the check, not a softer way to state the claim.

corpus/skills/principle-prove-it/tests/stays_silent_example.md

@@ -0,0 +1,12 @@
+A user asks which name reads better for a local variable in a helper they are
+writing, `retryCount` or `attempts`, and the agent gives an opinion.
+
+This skill stays silent. Auto-firing is driven by the presence of a claim to
+hold evidence against, and there is none here: a naming preference asserts
+nothing about behavior, system state, history, or a cause. There is no
+"this is fixed", no "the cause is X", no hedge about code that could be
+checked by running something.
+
+Firing here would be the skill misbehaving rather than working — demanding a
+command run and pasted output before answering a style question is the
+false-positive this fixture exists to pin down.

product/skills/alternatives-considered/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: alternatives-considered
+description: >-
+  Produce the real option set for a decision before committing to the first
+  shape that came to mind. Use before a design, a schema, a naming or format
+  choice, or any change expensive to reverse. Every option is labeled
+  considered (cited) or invented (untested); invented options route to
+  `spike-and-validate` before they can decide anything.
+---
+
+# Alternatives considered
+
+One attempt at a hard design locks in the first shape the model thought of.
+This produces the option set, with each option honest about where it came
+from.
+
+## The asymmetry that governs this skill
+
+`how` and `why` read what exists. They can come back empty, and an empty
+result is informative.
+
+This skill **generates**. It can always produce three plausible options, and
+plausibility is free. Left ungated it manufactures evidence for
+`principle-prove-it` — which is the exact failure that principle exists to
+stop.
+
+So every option carries a label and the label is load-bearing:
+
+| Label | Means | Authority |
+| --- | --- | --- |
+| `considered` | Someone actually weighed this — cite the PR comment, commit, doc, or rejected design | Evidence |
+| `invented` | Produced here, never tried | Hypothesis only |
+
+An `invented` option may not decide anything until `spike-and-validate`
+turns it into a run with real output. Saying "we considered X and rejected
+it" about an option nobody ran is a false claim about the record.
+
+## Step 1. Bound the decision
+
+State in one line: what is being chosen, and what makes it expensive to
+reverse. A decision that is cheap to reverse does not need this skill —
+make it, and move on.
+
+Pull **Avoid** from `why` if it ran. Options already tried and failed are
+`considered` with a citation, not fresh ideas.
+
+## Step 2. Fan out
+
+2–4 subagents, spawned in **one message**, each given the same brief and a
+different constraint to optimize for (fewest moving parts, easiest to
+delete later, best for the caller, cheapest to migrate). Different
+constraints, not different phrasings — same-brief subagents converge.
+
+Each returns rows in the shape at
+`corpus/skills/principle-prove-it/references/finding-shape.md`, with
+`grounding` set to `invented` unless it can cite where the option was
+already weighed.
+
+Give each one its own worktree if it writes anything. Scope wording is not
+filesystem isolation.
+
+## Step 3. Merge into an option set
+
+For each surviving option:
+
+- **Shape** — what the caller writes, first. Then types and boundaries.
+- **Label** — `considered` with citation, or `invented`.
+- **Cost to reverse** — the real question behind most of these decisions.
+- **What would kill it** — the check that would rule it out. This line is
+  the spike brief.
+
+Include the status quo as an option. It is `considered` by definition and
+frequently wins.
+
+## Step 4. Route
+
+- All options `considered` → decide now, cite the record.
+- The leading option is `invented` and expensive to reverse →
+  `spike-and-validate` before committing.
+- Subagents disagree on which constraint matters → that is the real
+  decision. Surface it instead of picking quietly.
+
+## Do not
+
+- Pad the set. Two real options beat four where two are strawmen.
+- Present an `invented` option as prior art.
+- Run this on a reversible decision.

product/skills/alternatives-considered/tests/fires_example.md

@@ -0,0 +1,12 @@
+A user is designing a cache key format for a service and says: "this is
+expensive to change once it's in production — what are our real options
+here?"
+
+This skill fires. It is a design decision that is expensive to reverse,
+which is the stated trigger, and the user is explicitly asking for the
+option set rather than a recommendation. Step 2 fans out subagents each
+optimizing a different constraint (fewest moving parts, cheapest to migrate,
+best for the caller), and Step 3 labels every returned option `considered`
+with a citation or `invented`. Because the leading option is expensive to
+reverse, Step 4 routes it to `spike-and-validate` before it can decide
+anything.

product/skills/alternatives-considered/tests/stays_silent_example.md

@@ -0,0 +1,8 @@
+A user asks the agent to rename a local variable inside one function from
+`res` to `response`, and confirms the function is not exported.
+
+This skill stays silent. The decision is cheap to reverse — a rename inside
+one unexported function is a single edit undone by a single edit — and the
+skill's Step 1 says a cheap-to-reverse decision does not need it. There is
+no option set worth generating, and producing three labeled alternatives for
+a local rename would be the padding its own "do not" list forbids.

product/skills/how/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: how
+description: >-
+  Trace how a subsystem actually works before changing it. Use for "how does
+  X work", a walkthrough before an edit, or placement questions ("where
+  should this live", "which package owns this"). Fans out read-only
+  explorers for a subsystem, one explainer for a narrow question. Use `why`
+  for motivation, `alternatives-considered` for options.
+---
+
+# How
+
+Build a working mental model of code you are about to change. The output is
+the mechanism, not annotated source.
+
+Feeds `principle-prove-it`: you cannot exercise the real artifact until you
+know which artifact is real.
+
+## Step 1. Size the question
+
+State your reading of the scope in one line, then proceed. The user can
+redirect.
+
+- **Narrow** — one module, one function, one file. No fan-out. Read and
+  explain in a single pass. Go to Step 3.
+- **Broad** — a subsystem across files or packages, a cross-cutting flow, an
+  architectural overview. Fan out first. Go to Step 2.
+
+When it is ambiguous, take the narrow path. A second pass is cheaper than
+four subagents answering a question that had one file in it.
+
+## Step 2. Fan out (broad only)
+
+Split the question into 2–4 angles that do not overlap. Spawn all explorers
+in **one message** so they run concurrently:
+
+- `subagent_type: Explore` (or `general-purpose` where Explore is absent)
+- read-only; no edits, no worktree needed
+
+Each explorer owns one angle and returns rows in the shape at
+`corpus/skills/principle-prove-it/references/finding-shape.md`.
+
+**Prompt hygiene:** give each explorer the question and the entry points,
+not your working theory. A primed explorer finds roughly what you already
+suspected.
+
+**Every explorer states grounding per row.** `read-confirmed` means it
+opened the actual import or call site and traced it. `name-matched` means
+the path looked right. Two files can hold the same symbol name; a subagent
+reasoning by name-proximity hands back a confident wrong file.
+
+## Step 3. Explain
+
+Merge the rows and write the explanation yourself. Sections, dropping any
+that do not apply:
+
+- **Overview** — what this does, in two sentences.
+- **Runtime flow** — the actual call path, entry point to effect.
+- **Key types** — the data structures the logic is written against.
+- **Where things live** — `file:line` per claim, with the ref.
+- **Gotchas** — the non-obvious parts, and what looks wrong but isn't.
+- **Not traced** — every angle that came back empty or was not covered.
+
+Do not drop the last section for brevity. A gap you name is a gap the reader
+can fill; a gap you omit reads as coverage.
+
+## Hand-off
+
+When `how` precedes a change, end with the mechanism that must still work
+afterward, phrased as a command or check. That line is what
+`principle-prove-it` will demand output from later.
+
+## Do not
+
+- Explain from a grep hit. A name match is not a read.
+- Fan out on a question one file answers.
+- Report a flow you inferred from function names as if you traced it.

product/skills/how/tests/fires_example.md

@@ -0,0 +1,11 @@
+A user is about to add a new notification channel and asks: "how does the
+dedupe path work before I touch it? is there an n+1 when we look up
+subscribers?"
+
+This skill fires. The question is a mechanism question about a subsystem the
+agent has not read, asked ahead of an edit — the skill's stated trigger. It
+spans more than one file (dedupe plus subscriber lookup), so Step 1 sizes it
+broad and Step 2 fans out read-only explorers on non-overlapping angles.
+Each returned row carries `read-confirmed` or `name-matched` grounding, and
+the merged explanation ends with the mechanism that must still work after
+the change — the line `principle-prove-it` will later demand output from.

product/skills/how/tests/stays_silent_example.md

@@ -0,0 +1,10 @@
+A user asks to bump a timeout constant from 30 to 60 seconds in a file they
+are currently looking at, and pastes the line. The agent makes the one-token
+edit.
+
+This skill stays silent. There is no mechanism to trace: the target is a
+single literal in a file already in context, the user supplied the code, and
+nothing about the change depends on understanding a call path. Step 1 would
+size this narrow and the skill's own "do not" list rules out fanning
+subagents at a question one file answers. Running `how` here would spend
+subagents to re-explain a line the user just read.