---
title: OKSTRA Implementation Planning Input - {{TASK_KEY}}
id: {{FM_ID}}
tags: {{FM_TAGS}}
status: ready-for-agent
aliases: {{FM_ALIASES}}
date: {{TASK_DATE}}
task-id: "{{TASK_ID}}"
task-group: "{{TASK_GROUP}}"
project-id: "{{PROJECT_ID}}"
taskType: "{{FM_TASK_TYPE}}"
---

# OKSTRA Implementation Planning Input

## Identity

- Project ID:
- Task Group:
- Task ID:
- Related Tasks:
- Issue / Ticket:
  - If left empty, workers fall back to the `Task ID` (without a prefix, like `8852`). When a single run handles multiple tickets at once, separate them with commas (`TICKET-123, TICKET-456`). If neither can be identified, `unknown` is allowed.
- Task Type: `implementation-planning`
- Requested Outcome:

## Requirement Summary

- What needs to change?
- Why is this work required?
- What result must be achieved?

## Current State

- Current behavior:
- Known limitations:
- Existing related implementation:
- Related code paths:
- Previous reports in the same task history:

## Constraints

- Business constraints:
- Technical constraints:
- Delivery constraints:
- Backward compatibility concerns:

## Out of Scope

- Adjacent areas deliberately excluded from this plan:
- Items that look related but must be planned in a separate task:
- Reason for exclusion (deadline, risk, separate owner, distinct decision):

> Analysers MUST NOT expand option candidates, file lists, or step plans into items listed here. If an analyser believes an excluded item must be addressed to satisfy the requirement, it is reported as a recommended follow-up task in the final report — never silently folded into a candidate option. If this section is left empty, analysers treat any change beyond what `Requirement Summary` explicitly demands as out of scope by default.

## Planning Concerns

- Selected direction realization concerns:
- Legacy-only implementation options and trade-offs:
- Dependencies or migrations:
- Validation approach:
- Rollback approach:

## Config and Deployment Expectations

- Relevant config files:
- Relevant deployment manifests:
- Expected target values or invariants:
- Values that must remain unchanged:

## Open Questions

- What is still unclear in the requirement?
- What could block implementation?
- What must be confirmed before coding?

## Questions for Analysers

When `selected-direction.json` is present:

1. Which files, interfaces, and stages realize the snapshot without changing its direction?
2. How does every file, stage, validation, and rollback link to the original requirements?
3. Does current evidence require `direction-invalidated`?

Legacy candidate-comparison questions apply only when the snapshot is absent:

1. What is the safest implementation direction?
2. What are the main trade-offs between options?
3. What should be validated before, during, and after implementation?
4. Which adjacent changes did you consider and **deliberately exclude** from this plan, and why must each be a separate task instead of being folded in here?
5. If a candidate option's file list grew beyond the explicit requirement, justify each extra file or remove it.

## Required Plan Deliverable

### Selected-direction input contract

When `instruction-set/selected-direction.json` is present, read it and the original requirements first. Concretize only the selected direction's files, interfaces, stages, validation, and rollback. Link every file and stage bidirectionally to the original requirements. If code evidence invalidates the direction, return `direction-invalidated` and stop. Candidate comparison and user selection are outside this contract.

### Legacy candidate-comparison input contract

When no selected-direction snapshot exists on a compatibility rerun, the final report retains every section below.

1. **Option Candidates** — at least two viable options, each with the exact list of files to create or modify and the principal change per file.
2. **Trade-off Matrix** — comparison of the candidates across complexity, risk, reversibility, performance impact, scope, and required test surface.
3. **Recommended Option** — selected option with explicit rationale referencing the trade-off matrix.
4. **Stage Map** — `## 5.5 Stage Map` plus one `## 5.5.<i> Stage <i>:` section per stage. Each stage is a thin vertical slice with `Slice value:`, `Acceptance:`, the three `Test case (success|boundary|failure):` lines, `Conformance tests:` or `Conformance exemption:`, the four required subsections, and a RED/GREEN step order unless a `TDD exemption:` line applies (which also waives the test-case lines).
5. **Dependency and Migration Risk** — schema, data, ordering, feature-flag, and cross-service risks that the recommended option introduces.
6. **Validation Checklist** — pre-execution, mid-execution, and post-execution checks (commands, expected outputs, observability points).
7. **Rollback Strategy** — exact reverse procedure or compensating action for each significant step.
8. **Scope Boundary** — an explicit list of adjacent areas, files, refactors, or quality improvements that this plan **does NOT** cover, each with a one-line reason (deferred, separate owner, separate decision, out of requirement). Any item the analysers were tempted to fold in but chose to exclude MUST appear here. An empty list is allowed only when the analysers explicitly state "no adjacent expansion was considered" — silence is not acceptable.
9. **Approval frontmatter** — the legacy final report's YAML frontmatter MUST emit `approved: false` and `implementation-option:`. Do NOT create a `User Approval Request` body block; the next `implementation` run reads only the frontmatter gate.

## Phase Boundary

- This task type produces a plan only. Source code MUST NOT be modified, builds/migrations/deployments MUST NOT be executed, and follow-up phases MUST NOT be started inside the same run.
- If workers detect that the plan cannot be completed without further error analysis or new requirements, record that in the final report and recommend re-routing to `error-analysis` or `requirements-discovery` rather than guessing.

## Conversion Note

- This input can be used as a planning draft before creating `okstra-task-brief.md`.
- Reuse the same `Task Group` and `Task ID` if this plan belongs to the same long-lived task.

## Stage Output Shape (reference)

This run's final report MUST emit `## 5.5 Stage Map` and `## 5.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative Stage Map tables:

### Shape A — single stage (small work)
| stage | title | depends-on | step-count | exit-contract-summary |
|-------|-------|-------|-------|-------|
| 1 | tiny rename | (none) | 2 | src/foo.ts:renamedFoo |

### Shape B — three stages, two parallel
| stage | title | depends-on | step-count | exit-contract-summary |
|-------|-------|-------|-------|-------|
| 1 | foo API skeleton | (none) | 4 | src/foo/api.ts:exportedFoo |
| 2 | baz settings split | (none) | 2 | src/baz/settings.ts, env BAZ_MODE |
| 3 | bar integration | 1, 2 | 3 | src/bar/use-foo.ts, GET /bar |

Stages 1 and 2 in Shape B are `depends-on (none)` → can be run by two parallel `implementation` runs.