--- title: OKSTRA Task Brief - {{TASK_KEY}} id: {{FM_ID}} tags: {{FM_TAGS}} status: new aliases: {{FM_ALIASES}} date: {{TASK_DATE}} task-id: "{{TASK_ID}}" task-group: "{{TASK_GROUP}}" project-id: "{{PROJECT_ID}}" taskType: "{{FM_TASK_TYPE}}" --- # OKSTRA Task Brief ## Identity - Brief Title: - Project ID: - Task Group: - Task ID: - Task Key: `::` - Related Tasks: - Issue / Ticket: - If the value is empty, the worker falls back to `Task ID` (without a prefix, like `8852`). If a single run handles multiple tickets at once, separate them with commas (`TICKET-123, TICKET-456`). If it cannot be identified either way, `unknown` is allowed. - Task Type: - Requested Outcome: - Owner: ## Request Summary - What is being requested or changed? - Why is this work being started now? - Is this a new task, a continuation, or a reopened task? - What decision should this run help make? ## Current Context - Current behavior or state: - Desired behavior or outcome: - Existing related implementation: - Related code paths: - Existing documents, tickets, or prior reports: ## Evidence and Source Materials - Primary problem statement: - Existing analysis or notes: - Related raw samples or logs: - Screenshots or reports: - Previous reports in the same task history: ## Task-Type Focus - If `Task Type` is `requirements-discovery`: - What classification or routing uncertainty must be resolved? - Why might this be a bugfix, feature, refactor, or ops task? - What evidence still blocks confident phase selection? - If `Task Type` is `error-analysis`: - What is the visible symptom? - What are the expected vs actual results? - What are the current hypotheses and missing evidence? - If `Task Type` is `implementation-option-selection`: - Is this a comparison among possible directions or validation of one preselected direction? - Which stable `EB-NNN`, `PB-NNN`, and `EO-NNN` requirements form the coverage denominator? - Which mechanism, architecture boundary, preservation rule, or implementation constraint must each direction address? - If `Task Type` is `implementation-planning`: - Which validated selection report and `selectedDirectionRef` authorise this new plan? - Which mechanism, architecture boundary, invariants, and user constraints must the plan preserve? - Which dependencies or migrations matter while realizing that one direction? - What validation and rollback approach is expected? - If `Task Type` is `implementation`: - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim? - What is the authoritative file list and step order copied from that plan? - Which validation and TDD commands must be executed and recorded with actual output? (Rollback is human-run — record the revert path for reference; do not require executing it.) - If `Task Type` is `final-verification`: - What was delivered? - What acceptance criteria must pass? - What residual risks or blockers remain? ## Constraints and Risks - Business constraints: - Technical constraints: - Delivery constraints: - Approval or review checkpoints: - Known risks: - Things that are still uncertain: ## Out of Scope - Adjacent areas deliberately excluded from this run: - Items that look related but must be handled in a separate task: - Reason for exclusion (deadline, risk, separate owner, distinct decision): > Workers MUST NOT expand into items listed here. If a worker believes an excluded item must be addressed to satisfy the requirement, the worker records it as a recommended follow-up task in the final report and stops — it does not silently include the work. If this section is left empty, workers treat any change beyond what `Request Summary` and `Current Context` explicitly demand as out of scope by default. ## Configuration References and Expected Values - Which config files matter for this task? - Which current or observed values should be checked? - Which expected values or invariants must hold for this task? - Which values are still uncertain and must be confirmed? ## Deployment Manifests and Expected Values - Which deployment manifests matter for this task? - Which expected image / env / resource / routing values must hold? - Which rollout or deployment invariants must be preserved? - Which deployment-side values are still uncertain and must be confirmed? ## Questions for Workers 1. 2. 3. ### Standing Ticket-Tagging Rule (always applied by every worker) - Specify a ticket on every item and table row. Tables use a `Ticket ID` column; bullet/numbered lists and section headers use a `[TICKETID: ]` tag. The fill priority, fallback, and multi-ticket rules follow the Ticket Tagging section of the `team-contract` SKILL. ### Standing Scope-Discipline Questions (always answered by every worker) - Which adjacent changes did you consider and **deliberately exclude** from this run? List each with a one-line reason. - Did any part of your output go beyond what `Request Summary` and `Out of Scope` define for this run? If yes, move it to a `Recommended Follow-up Tasks` section and remove it from the main answer. ## Expected Outputs - Root cause candidates / plan options / final blockers: - Missing information: - Risks: - Recommended next actions: ## Task Continuity Notes - Should the same task key continue to be used after this run? - What is the likely work category for this task right now? - Which lifecycle phase should probably happen next after this run? - What prior decision or report should the Okstra lead compare against? - What related tasks should the Okstra lead keep in mind but not merge with this task? - Which config files and deployment manifests carry the expected state for this task? ## Phase Boundary - This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run. - Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.md`). The lead and every worker stay inside that boundary. - "proceed to the next step" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`. - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories. - For `implementation-option-selection` specifically: compare or validate implementation directions without editing source, running tests/builds, or writing exact file lists, stage maps, and test commands. Only directions with 100% requirement coverage and 100% scope precision may be displayed. - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase. ## Available MCP Servers The MCP servers available to this run are declared in `.okstra/project.json`'s `mcpServers` array and rendered into the Okstra lead's launch prompt under `## Available MCP Servers`. The lead is responsible for forwarding the rendered list verbatim into worker prompts (Phase 2) so each assignment can determine whether its selected runner exposes the named tools. To declare servers, add entries shaped `{ "name": "", "description": "...", "tools": ["..."], "notes": "..." }` to that array. If the array is empty or absent, treat MCP as unavailable for this run. How to invoke (worker-by-worker): - **Native-session assignments**: invoke an MCP tool directly by its tool name (e.g. `mcp____`) only when the selected host adapter exposes it. Do not call an MCP tool name through a shell. - **CLI-wrapper assignments**: use only the MCP or tool configuration explicitly supported and forwarded by that provider wrapper. If the wrapper has no matching MCP configuration, record `MCP not available in this CLI` in `Missing Information or Assumptions`; do not attempt a shell fallback. - All workers: cite the exact server, tool, and SELECT (or `WHERE` filters) used in the result file. Tool-call failures must be logged in the worker's `*-errors.json` (commandKind `mcp_call`) so the lead can decide whether to retry under a different worker. Usage policy: - **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output. - **`implementation` phase**: read-only MCP queries are permitted as cross-checks; MCP MUST NOT be used as a write path even if a write tool becomes available — schema/data mutations belong in the codebase migration files reviewed by humans. - **CLI-wrapper workers**: can use these MCP servers only if their provider CLI configuration mirrors the same servers. If not configured, the worker should record `MCP not available in this CLI` in `Missing Information or Assumptions` rather than guessing. - **Forbidden**: connecting to non-listed databases, running anything that mutates state (server is read-only — flagged write attempts are a contract violation), persisting query results outside the run's own artifact directories. - **Limits**: `maxRows: 1000` per query (server-enforced). For larger scans, page via `WHERE` predicates and document the strategy. If MCP evidence contradicts a claim sourced from documentation, code, or prior reports, flag the conflict explicitly in the final report and prefer the live MCP evidence unless the brief says otherwise. ## Notes for Okstra Lead - Which workers should be used? - Should all workers receive the same brief or different emphasis? - What should the final synthesis optimize for?