The evidence-first feature loop

An AI coding-agent workflow for grounding one small feature change in current code, APIs, data contracts, and tests before implementation and user-path verification.

Use when

Use this when a larger feature can be divided into small engineering slices and guessing about APIs, persistence, or user-visible behavior would create avoidable risk.

The loop

Implement one bounded feature slice in [repository]. Read project instructions, the current implementation, relevant services, types, UI, tests, and architecture notes before editing. Report the evidence, risks, affected files, persistence impact, and validation plan; stop for approval if inspection materially changes scope or reveals destructive, production, or silent-persistence behavior. Make the smallest change, preserve unknown data and unrelated work, run relevant checks, and manually verify user-facing states. Stop after this slice and return evidence, limitations, and the next recommended slice.

Steps

• Read the project instructions and inspect the current implementation, dependencies, contracts, tests, and relevant architecture notes.
• State the evidence, risks, files in scope, user-visible behavior, persistence impact, and validation plan for one small slice.
• Stop for approval if inspection invalidates the approach or reveals a material scope, production, destructive, or silent-persistence change.
• Implement only the supported slice while preserving unknown fields, round-trip behavior, and unrelated work.
• Run the relevant repository checks and manually verify loading, error, stale, save, and cleanup states where applicable.
• Stop after the slice and return the evidence, changed behavior, limitations, and next recommended slice.

Verification

One feature slice works and its assumptions are proven by current evidence. The implementation matches observed APIs and data contracts, repository checks pass or have documented pre-existing failures, and the relevant user path is manually verified when one exists.

Why it works

Inspecting real contracts before coding prevents plausible but invented APIs or data behavior from shaping the implementation. Limiting each pass to one feature slice keeps review, verification, and persistence effects understandable.