Implementation Strategy

Implementation Strategy

Workflow

1. Identify the surface you are changing or reviewing: released public API, unreleased branch-local API, internal helper, persisted schema, wire protocol, CLI/config/env surface, or docs/examples only.
2. When released compatibility is relevant, determine the latest release tag from origin first, falling back to local tags only when remote tags are unavailable. Reuse an already verified baseline within the task unless new release evidence or changed scope makes it stale:

   BASE_TAG="$(.agents/skills/final-release-review/scripts/find_latest_release_tag.sh origin 'v*' 2>/dev/null || git tag -l 'v*' --sort=-v:refname | head -n1)"
   echo "$BASE_TAG"
   

   Report a local-tag fallback as potentially stale.
3. Record the implementation scope contract below before coding.
4. Identify the nearest existing implementation pipeline and the functions, types, or modules that are the source of truth for each affected concern. Prefer adapting the required input into that pipeline over creating parallel schema, metadata, validation, naming, or execution machinery.
5. Choose the smallest coherent change using the core decision rules. Add compatibility machinery only for a required supported boundary.
6. Revisit the review gate when feedback changes supported behavior, compatibility, ownership, protocol paths, implementation shape, or test permutations, or triggers a complexity reset. Otherwise retain the scope contract and proceed with the focused fix.
7. Before handoff, run the effectiveness check. If any answer is no, revise the design.

Implementation scope contract

Record these four items in the existing plan or working notes, and update them before widening or narrowing the implementation. A local fix can use one concise paragraph; mark unaffected dimensions as not applicable rather than inventing unsupported cases or creating another document:

1. Required behavior: The smallest user-visible scenario that must work.
2. Compatibility requirements: Supported released behavior or a durable boundary that must remain usable.
3. Intentionally unsupported cases: Nearby inputs or shapes to reject, including when and how rejection occurs.
4. Supported alternative: An existing wrapper, override, adapter, configuration, or lower-level API; state none when absent.

If the intentionally unsupported cases cannot be stated clearly, do not start by adding a general resolver. First define a narrower behavior contract. If no adequate supported alternative exists, add one only when the task requires it; do not invent one speculatively.

A released-version reproducer proves reachability, not support. Treat the exact shape as a compatibility requirement only when intentionally covered by public documentation, examples, tests, or typing; required by a durable boundary; or backed by concrete user reliance or maintainer intent. Otherwise record the risk and prefer early rejection with an existing supported alternative.

Review-feedback gate

Use this checkpoint only when feedback changes the scope contract or implementation shape. Reuse unchanged evidence instead of reconstructing it:

Review checkpoint:
- Root cause and required behavior:
- Compatibility evidence and unsupported cases:
- Source of truth:
- Behavior-space change: narrows / unchanged / widens