feature-implementation-plan git:20261016.c769bd8A

Immutable. This exact content never changes and is served at /api/v1/blob/3e5d19ddb2e2e3da.

---
name: feature-implementation-plan
description: >
  Assembling everything established about a feature into one document another engineer could
  execute without re-deriving the architecture: the resources in dependency order, the schema,
  contract, configuration and security changes named individually, the test strategy per
  resource, the migration, deployment and rollback story, and acceptance criteria a test can be
  written from. Use once the decisions are taken and before implementation starts, when a plan
  is a list of file names, when the plan and the code have drifted apart, when a feature is being
  handed to someone else or resumed after a break, or when the rollback story is discovered
  during the rollback. Does not produce the breakdown it orders (feature-decomposition), does not
  execute it (feature-execution), does not track status against it
  (feature-progress-tracking), and does not invent dates or effort estimates
  (estimation-under-uncertainty).
---

# Feature Implementation Plan

## Purpose

The plan is the hand-off artefact. It is read by whoever implements the feature — a different
person, a different agent, or the same agent after the context is gone — and its test is
whether they can proceed without asking what was decided or reading the analysis again.

It is also the artefact that goes stale fastest, so the second half of this skill is about
keeping it true rather than about writing it well the first time.

## Workflow

1. **Assemble, do not re-decide.** Relevant sections use existing artifacts or accepted session evidence:
   scope, impact map, decisions, resources, risks. If a section needs a new decision, the plan
   is incomplete for dependent work — route that decision while assembling independent parts.
   Check cited paths, contract/toolchain revisions and validation entrypoints against the current
   repository. Inspect the relevant caller/registration and build definitions to locate the real
   change point: distinguish source inputs, generated outputs and files to create. A matching path
   alone does not establish that the affected behavior is wired or tested. If an input cannot be
   inspected, record the verification gap; a failed search does not establish absence.
   Separate accepted inputs from proposals, incidental implementation patterns and
   assumptions. If accepted inputs conflict or implementation has drifted, identify affected
   resources and resolve from available decision history; ask the responsible owner only when
   that evidence cannot settle the issue. A newer file alone does not supersede an accepted decision.
2. **Order the resources** from their dependencies, and mark which arrows are forced. The order
   is a dependency graph, not necessarily one chain. Validate IDs and cycles between the required
   milestones: name what must exist or pass before implementation, validation or release can proceed.
   An accepted contract may permit implementation before the real producer is ready. If the work
   relies on a fixture, cite the contract revision and behavior it models, its coverage limits,
   and any resource that must first create or update it. Producer conformance and applicable
   integration/release gates still wait for evidence. For a handoff, identify the delivered
   artifact/revision, producing resource or owner, and the consumer's acceptance check; a team's
   general completion status does not establish that this prerequisite is available.
   Shared-file ownership also constrains parallel work.
3. **Name every change of kind** — schema, contract, configuration, security, observability,
   messaging — in a discoverable section or compact labelled entry. These are the entries
   people search for, and a change buried in a resource description is not found.
4. **State the test strategy per resource kind**, not as a paragraph. What level, against what,
   and what it must establish. Name the executable check or manual procedure and its prerequisites;
   when a test or fixture must first be created, link the responsible resource rather than implying
   that the check already exists or has passed. For automated checks, inspect build profiles, task
   bindings and filters to establish that the command selects them. Carry the required environment and
   expected test/report identity so a skipped or empty run cannot be mistaken for verification.
5. **Write migration, deployment and rollback as sequences**, with the ordering constraint
   spelled out. "Deploy then migrate" and "migrate then deploy" are different plans. For material
   operational steps, carry accepted prerequisites, success/stop conditions, recovery checks and
   responsible roles. Missing criteria remain unresolved for the affected step; do not invent
   thresholds or block independent preparation.
6. **Assemble, do not author, acceptance.** Carry applicable accepted `BAC-*` from Product and
   `TC-*` from Engineering. Check both directions: each selected criterion maps to `RES-*` and
   planned `EV-*`; each resource has an accepted scope/criterion justification. Include shared
   checks for behavior no resource alone can establish. A command name is insufficient without
   the setup, observable result and accepted boundary it checks. Missing criteria or decisions
   needed to make them checkable return to the owning stage; do not repair intent in the plan.
7. **Distinguish inapplicable from unresolved.** Use `none, because <reason>` only for established
   inapplicability; unknown decisions/evidence name the affected resources and next action. A Light
   plan can stay inline with scope, resource, validation and relevant constraints.

## Decision rules

```text
IF a section would require a decision to fill
THEN mark dependent work not ready and route the decision. A draft may name the unknown;
     it must not present a placeholder as an accepted design or block unrelated ready work.

IF a resource has no validation
THEN it is not planned yet, whatever else is written about it.

IF the dependencies form a cycle
THEN check whether implementation and later validation milestones were conflated. If a real
     prerequisite cycle remains, route the missing shared contract or inseparable breakdown
     to its owner; do not delete an edge or invent a serial order to declare readiness.

IF the plan names a file that does not exist and is not created by a resource
THEN the file list is wrong. Every path is either created here or exists today.

IF the change touches persisted data
THEN the plan states the compatibility window: what runs against old data, what
     runs against new, and whether they overlap.

IF the rollback story is "revert the commit"
THEN check it against the schema section. Once a migration has run, reverting the
     code is not reverting the change.

IF implementation contradicts the plan
THEN distinguish a code defect from evidence invalidating the plan. For a defect, record the
     required correction against the accepted contract for feature-execution or the existing
     execution workflow, carrying affected resources, evidence and current authorization.
     For an invalidated plan, revise affected artifacts and readiness with existing authority
     or obtain a genuinely missing decision. Do not reapprove unchanged work. A planning-only
     request stops at the plan/findings.

IF the feature spans sessions
THEN the plan must be readable cold. Assume the reader has none of the conversation.
```

## Constraints

- **Do not invent dates or effort estimates.** `estimation-under-uncertainty` owns forecasts.
  Preserve operational facts that constrain execution — migration windows, batch limits,
  retention periods, rollout intervals, and externally committed deadlines — and label their
  provenance instead of deleting them from the plan.
- **Do not reopen accepted design.** Link an accessible, revision-qualified decision record
  instead of duplicating its argument. When accepted decisions exist only in session context,
  retain the minimum accepted rationale, decisive constraint and provenance needed by the next
  reader in the plan; do not require a separate ADR. Missing rationale stays unknown, not invented.
  A conversation reference alone is insufficient for a reader who cannot access that conversation.
- **Preserve selected scope.** Executable resources come from the accepted delivery baseline.
  Optional or Recommended classification alone does not select an item for implementation;
  keep unselected suggestions as proposals outside the execution order.
- **The plan is a living artefact.** It is amended during implementation, not preserved as a
  historical curiosity and quietly ignored.
- Cite the implementation baseline: repository/input revisions, relevant working-tree changes,
  compiler/runtime and dependency/contract versions. Preserve accepted compatibility constraints;
  planning does not authorize upgrades. Planned evidence is not an observed test result.

## Keeping it true

Amend the plan whenever any of these happens, and say so in the execution log:

| Event                                    | Amendment                                                                          |
| ---------------------------------------- | ---------------------------------------------------------------------------------- |
| A resource turns out to need another one | Trace to accepted scope or resolve a scope change, then add RES-* and dependencies |
| A resource turns out to be unnecessary   | Mark it cancelled with the reason; do not delete                                   |
| A decision is superseded                 | Update affected `RES-*`/`CT-*`/`TC-*` and the record pointer                       |
| A file turns out not to need changing    | Correct the file list                                                              |
| Implementation reveals a risk            | Add it to the register and, if it needs work, a resource                           |

Keep a current authoritative plan with dated revision-impact entries and preserved history.
Readers must not reconstruct the executable state by mentally applying every old amendment.
For a semantic input change, follow its traced dependents, including fixtures and shared checks.
Identify stale assumptions, planned validation and existing `EV-*` that no longer support the new
revision; name the checks to create or rerun and affected readiness gates. Preserve historical
evidence and unaffected work. Updating the plan is not evidence that those checks have run.
Synchronize affected resource links with the existing progress record rather than creating a
competing status source.

## Output

Read `references/plan-template.md` when assembling or revising a plan for its section shapes,
repository-grounding example, dependency milestones and acceptance-check guidance. Before calling
the plan ready, walk its next ready resource from the current checkout through the proposed change
to its check. Resolve or expose any unstated generation step, profile, producer artifact or ownership
handoff the executor would otherwise have to discover. This walkthrough does not execute the plan.
The plan is
ready for its declared phase and scope when applicable decisions are resolved, dependencies, paths and
acceptance agree, and planned validation names executable checks and prerequisites. Return draft
status with affected blockers when that cannot yet be established; omit irrelevant template sections.
Preserve existing gate evidence and authority: readiness to implement does not establish passing
integration evidence or authorize deployment, and writing a plan does not execute its steps.