validate-v2

Files (5)

• SKILL.md
• artifact-checks.md · references/
• contract-and-forward-compatibility.md · references/
• examples.md · references/
• record-template.md · references/

SKILL.md (first lines)

# validate-v2

**Adaptive, high-signal validation** of whatever was just produced — a unified plan, tasks dossier, code change, workshop, legacy spec, or any artifact.

> **Prove the claims that matter, report only findings likely to change action, and spend extra review agents only when risk or uncertainty earns them.**

Optimise for precision and trust first; raise recall without turning every artifact into a four-agent audit. The validator judges whether the artifact **serves its reason for existing** — locally correct work that does not advance its purpose still fails. It is **read-only through adjudication**; only mechanical, evidence-pinned document repair may follow.

```md
User input:

$ARGUMENTS
# No flags → ADAPTIVE: lead + deterministic proof, one independent critic only for nontrivial work.
# --artifact <path>   validate this file/diff (overrides conversational inference)
# --scope narrow      lead + deterministic checks; at most one critic
# --scope broad       lead + up to three independent critics, one per DISTINCT risk
```

The **lead** (you) owns target detection, contract derivation, commands, history ranking, routing, adjudication, repair authorization, the verdict, and persistence. Workers only *propose* findings — their formatting never establishes truth.

## Pipeline

```text
resolve target + revision → one compact Validation Contract → deterministic proof + cheap history
→ risk-triggered lenses → lead review + critic(s) when useful → verify & disprove every finding
→ +1 specialist only for an unresolved independent risk → compact verdict
→ safe doc repair + targeted re-check (when eligible) → compact sidecar record (when appropriate)
```

Load a reference **only when the target needs it**:
- `references/artifact-checks.md` — per-type deterministic checks (unified plan, legacy spec, tasks, code, workshop, general).
- `references/contract-and-forward-compatibility.md` — proof levels, authority order, history labels, the five compatibility modes, next-phase traversal.
- `references/record-template.md` — sidecar placement + template.
- `references/examples.md` — worked thesis / forward-compatibility examples.

## 1 — Resolve target + boundary

Pick the target in this order: explicit `--artifact` → unambiguous last-produced artifact → current plan/phase output → current git diff (code) → **ask only when no safe target can be inferred**.

- **Code**: establish a concrete `base..head` range or the staged/unstaged boundary.
- **Documents**: identify the target and its nearest authoritative upstream artifacts.

Classify from **content and path**, never from a stage name. The unified planning doc is one `<slug>-plan.md` carrying `## Business Specification` + `## Implementation Plan`; recognise a legacy split `*-spec.md` / `*-plan.md` only as a compatibility case. Per-type checks: `references/artifact-checks.md`.

## 2 — Build one Validation Contract

Derive this **once**, from the user ask and nearest authoritative sources, before any broad search. Roughly 8–12 evidence-bearing lines. Mark inference once; allow `N/A` for fields that genuinely don't apply. Pass each worker only the fields its question needs — **never copy the whole contract into every prompt**.

### Validation Contract
- **Purpose / outcome**: <why this exists + the quoted user/product value>
- **Promise**: <what this artifact must make true for its beneficiary>
- **Proof target**: Orientation | Decision | Contract | Implementation | Integration | Validated Evidence
- **Proof required**: <tests, source match, schemas, examples, traces, commands>
- **Upstream**: <path/id + inherited requirement, or ORIGIN>
- **Consumers**: <named downstream ids + exact needs, or none found>
- **Position**: <public contract/invariants this artifact exposes>
- **Constraints / non-goals**: <only material boundaries>
- **Sources**: <paths/sections used to derive this>

Missing **Purpose/Promise** that prevents judgment is **one HIGH finding** — never invent intent to fill it. This carries thesis + Vector/Position/Outcome semantics without repeated essays. (Proof-level definitions + authority order: `references/contract-and-forward-compatibility.md`.)

## 3 — Gather proof before critique

Select deterministic checks **from the artifact's own claims** — not a ceremonial fixed suite.

- **Docs/plans**: paths, symbols, line refs, requirement/task/AC ids resolve; counts and dependency edges match their sources; required status/gate structures are valid; schemas/examples/commands/contracts match current source; **consume existing G1–G7 results — don't reimplement them**.
- **Code**: read the full diff + relevant unchanged dependencies; run targeted tests / typecheck / lint / build / schema-validation / repro commands when available and **read exit status + material output yourself**; inspect named consumers and changed public contracts; repo-wide search only when the change surface warrants it.

A linter passing does not prove tests pass. **A worker saying a command passed is not proof** unless the lead read the fresh output.

## 4 — Institutional memory (cheap lane)

On every nontrivial repository validation, run **one targeted** history lookup keyed on: target path + plan id; changed symbols/contracts/domains/files; requirement/AC ids; technologies/migrations/failure-modes/operations; named consumers.

Search likely dossiers, plans, tasks, execution logs, workshops, ADRs, reviews, retros, and relevant git history. **Read only the strongest candidates first**; deepen only when history can change the expected contract, expose a known failure, preserve a constraint, explain an odd design, or show a proposed fix failed before.

Label retained history **Authoritative / Applicable / Partial / Superseded / Unclear** (definitions: `references/contract-and-forward-compatibility.md`). `no_material_historical_evidence` is a valid result — never manufacture a history section. Fresh proof and current code outrank historical prose for present behaviour; superseded history explains, it never silently overrides.

## 5 — Risk-triggered lenses (no quotas)

Every run answers exactly three base questions:
1. Does the artifact fulfil its **Promise / Purpose**?
2. Is the **claimed proof level** supported by fresh evidence?
3. Does its **Position** satisfy named consumers and current contracts?

Add a lens **only on evidence in the target**:

| Trigger in the target | Lens | Question |
|---|---|---|
| auth, permissions, secrets, untrusted input | Security & Privacy | Can this expose or bypass a protected boundary? |
| schema, persistence, migration, destructive write | Data & Migration | Is state compatible, recoverable, rollback-safe? |
| async, shared state, locks, retries, hot path | Concurrency & Performance | Can ordering / scale / retry / ownership break the claim? |
| env vars, CI, deployment, config, flags | Operations | Can it deploy, observe, and roll back under the contract? |
| shared types, public API, imports, domain registry | Contract & Domain | Are consumers and dependency direction preserved? |
| user journey, accessibility, interaction/state | User Experience | Does observed behaviour advance the outcome without regression? |
| plans, tasks, workshops, knowledge artifacts | Readiness & Knowability | Can the beneficiary act and verify success with minimal clarification? |

No lens / axis / finding / worker minimum exists. A lens with no trigger does not run.

## 6 — Adaptive reviewer topology

`--scope` sets the ceiling; **no-flag is adaptive**, not broad.

| Mode | Normal topology |
|---|---|
| `--scope narrow` | lead + deterministic checks; **at most one** critic |
| no flag | lead + **one** independent critic for nontrivial work |
| `--scope broad` | lead + **up to three** independent critics, one per distinct risk |

**Zero workers is valid** when direct proof settles a tiny target. Responsibilities (use only these three):
- **Primary Critic** — local truth, Promise alignment, proof sufficiency, assumptions, material edge cases.
- **Contract/Compatibility Specialist** — only for nontrivial consumers, public shape, lifecycle, or cross-phase handoffs.
- **Risk Specialist** — only for one separate high-risk domain (security / migration / concurrency / operations / domain architecture).

**Parallel work requires independent questions** — never send several reviewers over the same files under different names. Launch workers read-only, on the current session model (omit any model override). Worker packet: exact target/revision · one owned question · only the relevant Contract fields · ordered files + commands · selected history · explicit exclusions. **No full conversation transcript.**

## 7 — Worker output + adjudication

Each worker returns **at most five** material findings (a ceiling, not a target):

From AI-Substrate/harness-engineering, MIT.

More from AI-Substrate/harness-engineering