/verification-planning

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.

Set a verification budget

At the final state, state the distinct claims, assign one owner to establish or refute each, and choose the minimum non-duplicative evidence that covers the claims and important boundaries. Reuse evidence only while its relevant code, inputs, environment, and state remain valid. Required repository and release checks still apply; broaden or repeat verification only when a stated condition justifies it.

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.