|
|
@@ -0,0 +1,103 @@
|
|
|
+---
|
|
|
+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 release-specific validation, use
|
|
|
+`release-smoke-test`; for larger multi-phase work, let this skill establish the
|
|
|
+evidence path that later work follows.
|
Alvin