Skip to content

Implementation Plan

Purpose

The Implementation Plan is the build sequencing and execution-readiness artifact. Its unique job is to translate governing story, technical design, and test-plan context into bounded implementation slices with dependencies, validation gates, and closeout evidence.

It is not the tracker. The runtime owns issue state and execution. This artifact defines the intended build shape so the runtime can execute the plan directly without inventing scope, ordering, or validation rules. Work items are optional; follow workflows/references/work-item-first.md. Readiness alone does not authorize implementation.

Example

Show a worked example of this artifact
---
ddx:
  id: example.implementation-plan.depositmatch
  authoring:
    home: repo
  depends_on:
    - example.technical-design.depositmatch.upload-csv
    - example.story-test-plan.depositmatch.upload-csv
---

# Build Plan

## Scope

Build the US-001 upload slice for DepositMatch CSV import. This plan covers
database migration, upload service, API route, UI upload flow, and story test
handoff. It does not cover column mapping, row validation, import confirmation,
or match generation.

**Governing Artifacts**:

- `example.user-story.depositmatch.upload-csv`
- `example.technical-design.depositmatch.upload-csv`
- `example.story-test-plan.depositmatch.upload-csv`
- `example.contract.depositmatch.import-session-api`
- `example.solution-design.depositmatch.csv-import`

## Shared Constraints

- API-001 is normative.
- Reuse coverage mapped in STP-001; add failing tests for missing behavior where useful.
- Raw CSV row values must not appear in logs.
- Storage failure must not leave partial session metadata.
- Build slices should stay small enough for review and rollback.

## Implementation Slices

| Slice | Story / Area | Governing Artifacts | Depends On | Validation Gate | Notes |
|-------|---------------|---------------------|------------|-----------------|-------|
| B-001 | Database migration and repository | TD-001, STP-001 | None | `pnpm test -- importSessionRepository` | Establish persistence contract first |
| B-002 | Source-file storage adapter and upload service tests | TD-001, STP-001 | B-001 | `pnpm test -- importUploadService` | Add red tests before service implementation |
| B-003 | API route and contract tests | API-001, TD-001, STP-001 | B-001, B-002 | `pnpm test -- importSessions` | Proves success and problem-details errors |
| B-004 | React upload UI and component tests | US-001, TD-001, STP-001 | B-003 | `pnpm test -- ImportSessionUpload` | Uses API response `next.href` directly |
| B-005 | P0 E2E smoke and closeout | US-001, STP-001 | B-004 | `pnpm test:e2e -- upload-csv` | Final story evidence |

## Execution Contract

The user authorizes implementation separately from plan readiness. Execute the
ordered slices through their verification gates and the goal's exit criteria.
A slice is a reviewable change, not necessarily a separately scheduled issue.
Stay within Scope; stop for authority conflicts, missing authorization, or
concrete blockers requiring a decision. Ordinary debugging remains in scope.

## Continuation Evidence

On interruption, record plan revision, completed slice IDs with evidence,
remaining slices, decisions, blockers, and the next action alongside this plan.
On resume, reconcile the record with the diff and tests before continuing.
When tracking is explicitly selected, its store owns claims and live status.

## Optional Tracking

Use work items only when requested or required by the active execution contract.
Prefer one item for this goal; split for independent scheduling, ownership,
parallel execution, or deferred work. Follow the selected runtime's acceptance,
dependency, audit, and closure requirements. Do not discover tracker binaries.

## Validation Plan

- [ ] Existing coverage and missing behavioral proof are identified for each slice.
- [ ] B-001 passes repository tests.
- [ ] B-002 passes upload service tests and log-redaction assertions.
- [ ] B-003 passes API-001 contract tests.
- [ ] B-004 passes UI component tests.
- [ ] B-005 passes Playwright upload smoke test.
- [ ] `pnpm test`, `pnpm test:coverage`, and `pnpm test:e2e -- upload-csv`
  pass before closing the story.

## Risks and Rollbacks

| Risk | Impact | Response | Rollback |
|------|--------|----------|----------|
| Multipart upload implementation buffers files in memory | H | Add memory regression test and stream files to storage | Revert B-002/B-003 before UI slice lands |
| API/UI validation drift | M | API contract tests remain authoritative; UI validation stays advisory | Disable `csvImportV1` UI entry point |
| Storage failure leaves partial data | H | Wrap metadata commit after storage success; test failure injection | Revert service slice and drop draft sessions created in test only |

## Exit Criteria

Plan readiness requires defined scope, ordered slices, shared constraints, and
explicit verification gates. These planning checks do not establish completion.
Execution is complete only when:

- [ ] US-001 upload succeeds end to end; governed rejection and storage-failure paths pass STP-001 tests.
- [ ] Every required slice validation gate and the final integration gate pass.
- [ ] Acceptance evidence is recorded; no required step or material blocker remains.
- [ ] Required canonical documentation and review are complete.
- [ ] Any explicitly selected runtime's audit and closure requirements are met.

## Diagnostic Evidence Sequencing

A diagnostic adoption slice requires its own story, Contract and Story Test Plan
before implementation. Sequence logger/capture wiring, actual OTel receiver and
privacy/failure proof, then service/CLI agent diagnosis. Runtime closeout records
run/attempt, safe manifest/receiver evidence, verification outcome and capture
limits. This example defines sequencing and does not report pilot completion.

Reference

ActivityBuild — Implement against the specs and tests. Capture the implementation plan that scopes the work.
Default locationdocs/helix/04-build/implementation-plan.md
RequiresNone
EnablesNone
InformsRelease Notes
Deployment Checklist
Generation prompt
Show the full generation prompt
# Build Plan Generation Prompt

Create the canonical build plan for the Build activity. Keep it short, but preserve the sequencing, issue boundaries, and verification rules needed to execute implementation against the test plan and technical designs.

## Purpose

The Implementation Plan is the **build sequencing and execution-readiness
artifact**. Its unique job is to translate governing story, technical design, and
test-plan context into bounded implementation slices with dependencies,
validation gates, and closeout evidence.

It is not the tracker. The runtime owns issue state and execution. This artifact
defines the intended build shape so the runtime can execute the plan directly
without inventing scope, ordering, or validation rules. Work items are optional;
follow `workflows/references/work-item-first.md`. Readiness alone does not
authorize implementation.

## Reference Anchors

Use this local resource summary as grounding:

- `docs/resources/google-small-cls.md` grounds small, reviewable,
  rollback-friendly implementation slices with related tests.

## Active Concerns

For each concern selected in `docs/helix/01-frame/concerns.md`, apply its declared
`## Artifact Impact` (from `workflows/concerns/<name>/concern.md`) to THIS build plan — realize the
IMPLEMENTATION_PLAN-level obligations it names (relational-data-modeling -> migration steps; resilience -> guard wiring; usage-metering -> metering wired on the real path). A selected concern whose Artifact Impact names IMPLEMENTATION_PLAN
but leaves no trace here is drift (reconcile-alignment Concern->Artifact Realization check).

## Storage Location

`docs/helix/04-build/implementation-plan.md`

## Required Inputs

- `docs/helix/03-test/test-plan.md` and `docs/helix/03-test/test-plans/TP-*.md`
- `docs/helix/02-design/technical-designs/TD-*.md`
- project-level design constraints

## Include

- scope and governing artifacts
- build order and dependencies
- execution authorization, completion conditions, and stop conditions
- token estimates grounded in existing usage evidence and a total spending
  ceiling in the existing execution contract, following
  `workflows/references/work-item-first.md`; no separate estimate artifact
- concise continuation evidence and optional tracking rules
- quality gates and closeout criteria
- risks that should refine upstream artifacts

Do not derive build dependencies or closeout criteria from product uptake
targets. Verify engineering completion against capabilities and readiness;
record explicit funding or authorization constraints separately with their
source and affected action.

## Boundary Test

| If you are writing... | Put it in... |
|---|---|
| Product or feature behavior changes | PRD / Feature Specification / User Story |
| Design or interface decisions | Solution Design / Technical Design / Contract / ADR |
| Exact story tests and fixtures | Story Test Plan |
| Build slice order, dependencies, and validation gates | Implementation Plan |
| Assignee, live status, claim, execution logs | runtime work item or issue |

## Template

`workflows/activities/04-build/artifacts/implementation-plan/template.md`
For tracker conventions see the runtime's install guide.

## Boundary Gate Sequencing

For source projects, apply `modularity-and-encapsulation`: sequence baseline
adoption, boundary mapping and the actual project checker before dependent feature
work. Name the single command used locally, in pre-commit, and CI, plus allowed
and forbidden import negative controls. Include supported cycle/private-access
checks and named semantic review obligations. Bounded adoption work may proceed
before the gate exists; feature work may not. Inventory existing violations
individually with owners and remediation; do not enlarge baselines to hide new debt.

## Diagnostic Evidence Sequencing

When `o11y-otel` applies, follow the template's diagnostic sequencing and include
its TEST_PLAN obligations in the project Test Plan and exact tests in Story Test
Plans. Sequence Contract adoption, instrumentation/capture, actual OTel receiver
proof and diagnostic pilot. Runtime work items carry safe evidence references,
verification outcome and coverage/loss limits; do not dump whole logs into them.
Template
Show the template structure
---
ddx:
  id: implementation-plan
  authoring:
    home: repo
---

# Build Plan

## Scope

**Governing Artifacts**:
- [docs/helix/01-frame/...]
- [docs/helix/02-design/...]
- [docs/helix/03-test/...]

## Shared Constraints

- [Constraint from requirements, design, architecture, or security]

## Implementation Slices

For handwritten source, put boundary adoption/map and checker scaffolding before
feature slices that depend on them. Name the project-local boundary command and
its local/pre-commit/CI wiring; identify allowed/forbidden import controls.

| Slice | Story / Area | Governing Artifacts | Depends On | Validation Gate | Notes |
|-------|---------------|---------------------|------------|-----------------|-------|
| [B-001] | [US-XXX or area] | [TP/TD refs] | None | [Command/evidence] | [Why first] |
| [B-002] | [US-XXX or area] | [TP/TD refs] | [Dependency] | [Command/evidence] | [Why next] |

## Execution Contract

The user authorizes implementation separately from plan readiness. Execute the
ordered slices through their verification gates and the goal's exit criteria.
A slice is a reviewable change, not necessarily a separately scheduled issue.
Stay within Scope; stop for authority conflicts, missing authorization, or
concrete blockers requiring a decision. Ordinary debugging remains in scope.
State the token range and usage basis (or unknown), total spending ceiling, and
runtime metering or enforcement limits here; include verification and review.
Follow `workflows/references/work-item-first.md`; reaching the ceiling requires
a disposition with remaining work, not an automatic budget increase.

## Continuation Evidence

On interruption, record plan revision, completed slice IDs with evidence,
remaining slices, decisions, blockers, and the next action alongside this plan.
On resume, reconcile the record with the diff and tests before continuing.
When tracking is explicitly selected, its store owns claims and live status.

## Optional Tracking

Use work items only when requested or required by the active execution contract.
Prefer one item for this goal; split for independent scheduling, ownership,
parallel execution, or deferred work. Follow the selected runtime's acceptance,
dependency, audit, and closure requirements. Do not discover tracker binaries.

## Validation Plan

- [ ] Existing coverage and any missing behavioral proof are identified
- [ ] All required tests pass before reporting goal completion
- [ ] Behavior changes update canonical documents
- [ ] Code review is complete before activity exit

## Risks and Rollbacks

| Risk | Impact | Response | Rollback |
|------|--------|----------|----------|
| [Risk] | [H/M/L] | [Action] | [How to reverse or disable] |

## Exit Criteria

Plan readiness requires defined scope, ordered slices, shared constraints, and
explicit verification gates. These planning checks do not establish completion.
Execution is complete only when:

- [ ] [Observable implemented goal and its acceptance evidence]
- [ ] Every required slice validation gate and the final integration gate pass.
- [ ] Acceptance evidence is recorded; no required step or material blocker remains.
- [ ] Required canonical documentation and review are complete.
- [ ] Any explicitly selected runtime's audit and closure requirements are met.

## Diagnostic Evidence Sequencing (when applicable)

For selected `o11y-otel` practices, sequence Contracts before dependent wiring,
then real receiver/conformance and failure proof before the service/CLI diagnostic
pilot. Each closeout names run/attempt, safe evidence location, verification
outcome and capture limits. A quiet console is not verification evidence.
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/build/implementation-plan.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:cab66874…9d15a20d

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/build/implementation-plan/",
        "digest": {
          "alg": "sha256",
          "value": "cab66874f80293e499ee66785088945a69c667cecb8e84585d3cd0409d15a20d"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "-0kyc7vyYWNyYPMVlwcTekZ0ie8hIOHQdg776AoQ-UIj4rFFg0elwP25f-n3QMwoFgmYn_n9BKkNyLYJbKEkDQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}