---
name: verification-planning
description: Verification planning for non-trivial coding work. Use before implementing a feature, bug fix, refactor, cross-system change, or high-confidence behavior change that needs a credible project-specific evidence path.
---

# Verification Planning

## Build an evidence path

Before changing a non-trivial system, build an **evidence path**: a
project-specific route from the claim being made to evidence that can establish,
limit, or refute it.

The purpose is not to select a familiar technique. The purpose is to decide how
this system can reveal the truth of this particular change.

## 1. Frame the claim

State the behavior that needs to become true and the conditions that could make
a confident conclusion wrong.

Consider what must change, what must remain true, where the behavior crosses a
boundary, and which failure would matter most.

**Complete when:** the claim, its meaningful uncertainty, and its important
failure modes are concrete enough to investigate.

## 2. Design the evidence path

Derive possible evidence paths from the system itself: its controllable inputs,
observable effects, state transitions, invariants, boundaries, artifacts, and
ability to repeat or reverse a scenario.

Generate alternatives before choosing. Prefer the path that produces a
trustworthy conclusion with proportionate cost, safety, and effort.

**Complete when:** there is a preferred path, its limitations are understood,
and a weaker or stronger alternative is available if circumstances change.

## 3. Create a verification affordance when needed

When the existing system leaves the decisive truth too indirect or ambiguous,
extend the evidence path with a **verification affordance**: the smallest
capability that makes the relevant state controllable, observable, repeatable,
and diagnosable for an agent.

Ask what capability would let an agent establish the claim directly, repeat the
scenario from a known state, and explain a failure without inference. Prefer an
affordance that strengthens directness, determinism, agent-legibility,
isolation, resetability, or future reuse.

Treat the affordance as part of the evidence path, not an automatic product
feature. Decide deliberately whether it is temporary or durable before building
it.

**Complete when:** the chosen path can establish the claim directly enough for
its stakes, and any needed affordance has a defined lifecycle.

## 4. Research when the path is unknown

When the right evidence path depends on an unfamiliar dependency, framework,
external service, or rapidly changing capability, ask `@librarian` for focused
research before committing to an approach.

Ask for official or project-specific facilities, constraints, and trade-offs
that affect this exact verification problem. Use existing project evidence
directly when it already resolves the choice.

**Complete when:** the chosen path rests on known capabilities and real
constraints rather than assumption.

## 5. Make the path runnable

Prepare only the support needed to follow the evidence path reliably. Keep the
support narrow, repeatable, and safe to inspect.

Decide whether that support has recurring value or exists only to resolve the
current uncertainty. Retain durable value deliberately; remove temporary
support once it has served its purpose.

Ask before introducing dependencies, persistent diagnostic surfaces, or
structural changes whose sole purpose is evidence gathering.

**Complete when:** the path can be followed without guessing about setup,
state, or interpretation.

## 6. Close the evidence path

After implementation, follow the planned path and interpret the resulting
evidence against the original claim.

Report whether the claim was established, limited, or refuted; distinguish
known facts from remaining uncertainty.

**Complete when:** a future reader can see what supports the conclusion and
what remains outside its reach.

## Scope

Use this skill proportionately. Small mechanical changes can follow ordinary
project checks directly. For larger multi-phase work, let this skill establish
the evidence path that later work follows.