Product implementation plan

# Product implementation plan

## Goal

Convert an accepted product increment contract into a repository-grounded implementation plan that another engineer or agent can execute without rediscovering the codebase, changing the contract, or hiding risk.

The plan explains the technical path, sequence, verification, observability, and rollback preparation for the single contracted increment. It does not implement the increment.

This is implementation planning. Do not modify application code, tests, configuration, dependencies, schemas, generated files, or lockfiles. Create or update only the product artifacts named below.

Complete the analysis autonomously. Do not stop to ask clarifying questions. When the contract and repository cannot support a safe plan, return `HOLD` or `REVISIT CONTRACT`.

## Prerequisites

Read, in order:

* every applicable `AGENTS.md` and repository instruction file
* `docs/product/increment-contract.md`, `docs/product/increment-contract.yaml`, and `docs/product/increment-contract-changelog.md`
* the source, tests, schemas, migrations, interfaces, configuration, dependency manifests, build and test commands, and operational documentation implicated by the contract
* recent relevant history and the current working-tree status
* any existing `docs/product/implementation-plan.md`, `docs/product/implementation-plan.yaml`, and `docs/product/implementation-plan-changelog.md`

Proceed only when the current contract decision is `CONTRACT` or `CONTRACT NARROWLY`. The plan must inherit the exact contract version and increment ID. If the contract is missing, contradictory, stale relative to material repository changes, or decided `HOLD` or `REVISIT SHAPE`, return `REVISIT CONTRACT`.

Read source deeply enough to trace runtime behavior. Do not assume a directory name proves ownership or that an existing abstraction should be extended.

## Evidence standard

Label every material claim with exactly one:

* `OBSERVED`: directly inspectable in code, tests, configuration, history, or contract evidence
* `DERIVED`: concluded from cited observations; show the reasoning
* `ASSUMED`: unverified but necessary for planning; state the verification step
* `UNKNOWN`: unresolved; state what inspection or decision would resolve it

A likely file is not an impact map. A passing unit test is not evidence that an end-to-end contract criterion passes. An existing pattern is a default only when it still fits the contracted constraints.

## Step 1: Inherit the contract without rewriting it

Create a traceability table for every acceptance criterion, business rule, permission, success measure, protected invariant, and quality bar:

* requirement type and stable ID
* contracted behavior
* relevant current code path
* planned change location
* planned verification
* evidence label
* unresolved dependency or ambiguity

Quote criterion IDs, not paraphrased substitutes. The plan may narrow execution only through a `PLAN NARROWLY` decision; it may not quietly delete a criterion.

## Step 2: Trace the current architecture and behavior

Follow the contracted path from entry point to observable result. Identify:

* components, modules, functions, routes, jobs, interfaces, and data stores involved
* state ownership and lifecycle
* trust and permission boundaries
* external dependencies and failure modes
* tests that currently protect the path
* logging, metrics, tracing, or user-visible recovery already present
* accessibility semantics and performance-sensitive boundaries where relevant

Use repository-relative paths and symbols. Distinguish direct impact from possible adjacency. Do not list broad directories “just in case.”

## Step 3: Choose the smallest technical approach

Describe the planned approach and at least one rejected alternative when the choice is consequential.

The chosen approach must:

* satisfy every inherited criterion, business rule, permission, success measure, invariant, and quality bar in scope
* preserve named invariants and public compatibility
* follow applicable repository patterns unless a deviation is justified
* avoid speculative abstractions and unrelated cleanup
* make failure behavior explicit
* keep data and migration changes reversible where practical
* add only dependencies that are necessary and supportable

If satisfying the contract requires a material new dependency, irreversible migration, breaking interface, security model change, or architecture not contemplated by the contract, return `REVISIT CONTRACT` rather than normalizing it in the plan.

## Step 4: Build the execution sequence

Write an ordered sequence of bounded implementation tasks. For each task include:

* objective and contract IDs served
* exact files or symbols expected to change
* behavior before and after
* prerequisite tasks
* tests to add or update
* local verification command or inspection
* failure and recovery considerations
* explicit stop condition

Sequence schema and interface compatibility before consumers, core behavior before presentation, and instrumentation before any criterion that depends on it. Keep documentation and generated-output updates explicit.

Do not prescribe a bulk rewrite when an incremental path exists. Do not hide “refactor everything nearby” inside a task.

## Step 5: Design the verification matrix

For each acceptance criterion, business rule, permission, protected invariant, and quality bar, name the cheapest reliable level that proves it. For each success measure, show how the implementation makes later observation possible without claiming the outcome occurred:

* static analysis or type checking
* focused unit or component test
* integration or contract test
* end-to-end test
* accessibility inspection
* security or permission check
* performance measurement
* manual inspection only when automation is disproportionate, with exact steps and expected result

Include relevant regression suites and baseline comparisons. Commands must come from repository evidence. Do not invent a command because it is conventional for the framework.

State test-data needs without using production data, live credentials, or personal information.

## Step 6: Plan operability and rollback

Describe, without changing or deploying anything:

* observability added or reused and which criterion or guardrail it serves
* expected healthy and unhealthy signals
* feature-flag, compatibility, or staged-exposure strategy if warranted
* migration ordering and reversibility
* rollback steps at the code, schema, configuration, and data-contract levels
* states that rollback cannot safely reverse
* documentation, support, and release-note updates

If rollback depends on infrastructure or permissions not evidenced in the repository, label it `UNKNOWN` and force `HOLD` when the risk is material.

## Step 7: Desk-test the plan

1. Every in-scope contract criterion, business rule, permission, success measure, invariant, and quality bar maps to implementation work and verification or later observation.
2. Every protected invariant has a regression check.
3. The file and symbol map comes from repository inspection.
4. Tasks are ordered, independently checkable, and free of unrelated cleanup.
5. Accessibility, security, privacy, performance, reliability, and compatibility are proportional to the affected surface.
6. Observability and rollback match the failure risk.
7. Commands and test levels are available and sufficient.
8. No step modifies production, uses secrets, or requires real user data.

Any material failure forces `PLAN NARROWLY`, `HOLD`, or `REVISIT CONTRACT`.

## Decision

Conclude with exactly one:

* `PLAN`: the full contracted increment has an executable, evidenced plan
* `PLAN NARROWLY`: only the named contracted subset can be executed safely now
* `HOLD`: required repository, test, environment, or operational evidence is missing
* `REVISIT CONTRACT`: implementation reality conflicts with the contract or changes its risk materially

Lead with:

“As of [date], implementation plan [plan version] for increment [increment_id] and contract [contract version] contains [N] ordered tasks covering [N/N] in-scope acceptance criteria, with [N] unresolved unknowns; decision [PLAN / PLAN NARROWLY / HOLD / REVISIT CONTRACT].”

## Deliverables

Create or update only:

### 1. `docs/product/implementation-plan.md`

Lead sentence, inherited scope, requirement traceability, architecture trace, chosen and rejected approaches, ordered tasks, verification matrix, operability, rollback, risks, desk-test results, assumptions, unknowns, and sources.

### 2. `docs/product/implementation-plan.yaml`

Include `version`, `status`, `as_of_date`, `decision`, `increment_id`, `contract_version`, `contract_decision`, `traceability`, `business_rules`, `permissions`, `success_measures`, `quality_bars`, `impacted_surfaces`, `approach`, `rejected_alternatives`, `tasks`, `verification`, `observability`, `rollout`, `rollback`, `risks`, `assumptions`, `unknowns`, and `sources`.

Task and criterion IDs must be stable. Unknown values are `null` with an explanation.

### 3. `docs/product/implementation-plan-changelog.md`

Append only. Record version, date, inherited contract version, decision, changes to sequence or approach, and the evidence that caused them.

Version the plan independently. Parse the YAML and confirm that the three files agree with the accepted contract.

## Boundaries

* Do not modify application code, tests, configuration, dependencies, schemas, generated files, or lockfiles.
* Do not deploy, commit, push, open a pull request, or touch production, secrets, or user data.
* Do not rewrite the contract inside the plan.
* Do not invent architecture, test commands, infrastructure, or rollback capability.
* Do not use the increment as permission for adjacent refactors.
* Preserve unrelated work and working-tree changes.

## Done when

* Every in-scope criterion, business rule, permission, protected invariant, and quality bar is traceable to code, a task, and verification; success measures trace to later observation.
* The ordered tasks are bounded enough for another engineer or agent to execute.
* Test, accessibility, security, privacy, performance, reliability, observability, and rollback work are explicit and proportional.
* Contract conflicts and unknowns forced an honest decision.
* No product or test file was changed.
* The Markdown, YAML, and append-only changelog parse and agree.