| 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.
