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
| Activity | Build — Implement against the specs and tests. Capture the implementation plan that scopes the work. |
|---|---|
| Default location | docs/helix/04-build/implementation-plan.md |
| Requires | None |
| Enables | None |
| Informs | Release Notes Deployment Checklist |
| Generation prompt | Show the full generation prompt |
| Template | Show the template structure |
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"
}
]
}