---
name: okstra-user-response
description: >-
  Use this to answer an okstra task's open clarification questions in-session without hand-editing a report or sidecar. It projects the available tasks and one report as fixed text, reads cited context before asking, asks one question at a time in the user's language with each option's outcome, confirms the user's exact answers, and publishes only the user-owned user-responses sidecar through a typed transaction. NOT for starting a run, inspecting a finished task, or generating a brief.
---

# OKSTRA User Response

Use this skill for open `C-*` clarification items and explicit plan decisions. The user alone selects or writes every answer. Never infer an answer or approval.

The model-facing commands are fixed text reads and typed transaction writes:

| Command | Purpose |
|---|---|
| `user-response list-view` | Show tasks that still await user input. |
| `user-response show-view` | Show questions, choices, why asked, linked plan items, cited artifacts, resolved context, and current response state. |
| `user-response begin` | Open a sidecar transaction for one report identity. |
| `user-response answer` | Add or replace one validated clarification answer. |
| `user-response plan-decision` | Record an explicit plan decision in the transaction. |
| `user-response legacy-report-authoring` | Record legacy report-authoring permission for report contract 2.0 only. |
| `user-response finalize` | Atomically merge and publish the user-owned sidecar. |

Do not use the automation-oriented `list` or `show` commands. Do not open a report record to select fields. Question text and `options[]` come only from the fixed views. Cited files listed in `show-view` are read only to explain those options.

## Step 0: Preflight

Use the registered host ID that the current harness declares for this session. Do not infer it from an executable or `PATH`. Do not substitute `claude-code`.

<!-- BEGIN FRAGMENT: bash-invocation-rule -->
Run one Bash tool call, starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match):
<!-- END FRAGMENT: bash-invocation-rule -->

```bash
okstra preflight --runtime <host-runtime>
```

On `Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. On `Okstra preflight: ready`, carry the fixed `Project root`, `Project ID`, `Runtime`, and `Relay contract` lines as literal values.

<!-- BEGIN FRAGMENT: preflight-outdated-cli -->
If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary).
<!-- END FRAGMENT: preflight-outdated-cli -->

Resolve the installed home:

```bash
okstra paths --field home
```

<!-- BEGIN FRAGMENT: python-bootstrap-note -->
Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
<!-- END FRAGMENT: python-bootstrap-note -->

## Host picker

Every choice this skill asks — the task pick, each clarification, an explicit plan decision, and the final record confirmation — uses the same host picker as `okstra-run`.

Read the absolute path in the fixed `Relay contract` line. In that file, take the `Wizard interaction relay` JSON. Intersect its `semanticFunctions` with the functions this session can actually call, using each `interactions` kind's `function` field. The live harness does not expose tools named `native_single_select`. Keep `native-single` only when `native_single_select` is in that intersection. Keep `nativeLimits`. If `Relay contract` is `-`, native-single is unavailable.

- When `native-single` is available and the option count fits `nativeLimits` (unique labels, within min/max): call `interactions.native-single.function` once with one question and every option as `{label, description}` in original order. Do not print a numbered list in chat while the native tool is available. Claude Code's function is `AskUserQuestion`, Grok's is `ask_user_question`, Codex's is `request_user_input` — copy the relay field; do not substitute one name for another.
- Otherwise render a 1-based numbered Markdown list and wait for the next message. Do not drop options to force the native tool.

Copy the view's `Picker:` `- Label:` / `Description:` pairs into that function in that order. Do not rebuild labels from the `Options:` dump. `--option-number` is the 1-based `Option N:` index, which is the same order as `Picker:`. The HTML report's `<select>` uses the same `option.answer` values.

Pass only the choices this step already owns — the `list-view` `Picker:` rows, the report `Picker:` rows, or the two confirmation labels. Do not append `Enter directly`. Claude Other, Grok `z`, and Codex's free-form row already collect a custom answer; that row is `Enters an answer`. When native-single is unavailable, a next message that is not a listed label or its 1-based number is the same `Enters an answer`. Do not ask a second question for the custom value.

Never invent a picker function. Never ask the user to type a number when the native tool is available.

## Step 1: Select a task from the fixed list view

```bash
okstra user-response list-view --home <resolved-home> --project <projectId> --limit 3
```

The view gives `Task key`, `Task type`, `Report`, open-item counts, and readability status. If the count is zero, answer `No task has open clarification items.` and stop. Do not continue with an unreadable entry.

Present up to three task choices through the host picker. A host free-text row or unmatched next message is the report path or task key.

## Step 2: Read the fixed report view

```bash
okstra user-response show-view --report <reportPath> --project-root <projectRoot>
```

The view contains the report identity, contract version, every open clarification question, its expected form, its current response and disposition, its options, a `Picker:` block, approval context, plan option candidates, current plan decision, resolved context, why the row is asked, linked plan items, and cited artifacts. Question text and `options[]` come only from this view. Do not open a report record to select fields.

Each entry in `options[]` corresponds to `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. Put the `recommended` option first and suffix its label with `(Recommended)`. Then put the alternatives in view order.

Contract 3.0 options also expose `reach` and `scopeEffects`. Contract 3.0 approval-blocking rows expose `approvalContext`.

When an axis says `not stated in the report`, repeat that text. Do not infer missing report-owned impact. The skill must **never invent it**.

## Step 2b: Investigate cited context before asking

Do not present a picker from the raw field dump. For each still-open item, read the investigation list the view printed:

1. Every `Cited artifacts:` `path:line` — open that file under the project root from preflight. The line number is the starting point, not a license to skip the surrounding function or section.
2. Every `Linked plan items:` definition and every `Context:` definition.

Stop at that list. Do not search the rest of the repository for extra files. If a cited path is missing or unreadable, say so in the question; do not guess its contents.

Investigation explains. It never adds an option, drops an option, or changes the answer that `--option-number` will record.

## Step 3: Ask one clarification at a time

Ask in the user's language. Do not lead with `Kind`, `Blocks`, `Expected form`, or `C-NNN`. The question body is:

1. Why this is being asked (`Why asked`, restated so a non-author of the report can follow it).
2. What is already decided (`Context` and linked plan items, in one or two sentences).
3. The fork (`Question`, restated as a choice the user can act on).
4. What stays blocked if they do not answer (`Blocks=approval` → the plan cannot be approved; `Blocks=next-phase` → the next phase cannot start cleanly).

Keep the row id at the end of the question, in parentheses, so the later transaction can name it.

Use one single-select question per clarification, through the host picker. Each option description uses this order:

> If you pick this: `<addedWork>`. What it reverses: `<directionChange>`. Scope: `<reach or scopeImpact>`. Why it is on the board: `<rationale>`.

When investigation quoted a cited file, add one more sentence that names the path. That sentence does not replace a `not stated in the report` axis.

Use the displayed values to confirm the user's choice. Do not copy a predefined option's answer, disposition, reach, or scope effects into command arguments. The typed command resolves those report-owned fields from its option number.

| User action | Value | Disposition |
|---|---|---|
| Selects an option | that option's `answer` | that option's `disposition` |
| Enters an answer | the user's text verbatim | `answer` |
| Asks for the item to be presented again | the user's request verbatim | `reframe` |

Copy `kind` from the view. A `reframe` does not satisfy the gate. If the user asks what an item means, explain from the view plus the cited files already read, then ask the same item again.

## Step 4: Confirm the complete response

Echo each clarification ID, kind, disposition, value, and rationale. Include any explicit plan decision or legacy report-authoring decision. Ask through the host picker, two options:

1. `Record as shown` (Recommended)
2. `Change an answer`

Do not start a transaction until the user picks `Record as shown`. If they pick `Change an answer`, show the complete response again and reconfirm with the same picker. Do not ask them to type `confirmed`.

## Step 5: Begin the typed transaction

```bash
okstra user-response begin --report <reportPath> --task-key <taskKey>
```

Carry the returned opaque `transaction` value exactly. Do not decode it or inspect its state file.

For a predefined option, pass only its one-based number from the fixed view:

```bash
okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --option-number <N>
```

Every value, rationale, and reason body file must be a regular file under `<projectRoot>/.okstra/tmp/user-response/`; do not use an external file or a symbolic link. For a direct user answer, write the exact value there. Write the rationale to a separate Markdown file only when present. Then run:

```bash
okstra user-response answer --transaction <transaction> --clarification-id <C-NNN> --kind <kind> --disposition <disposition> --value-file <value.md> [--rationale-file <rationale.md>]
```

The two answer forms are mutually exclusive. The command validates that the clarification ID and kind exist and remain open in the selected report. Repeating the same answer command is safe.

## Step 6: Record an explicit decision when present

When the user explicitly approved a plan:

```bash
okstra user-response plan-decision --transaction <transaction> --status approved [--implementation-option <name>]
```

For `revision-requested` or `rejected`, write the user's reason verbatim to a Markdown file in that same temporary directory and pass it:

```bash
okstra user-response plan-decision --transaction <transaction> --status <revision-requested|rejected> --reason-file <reason.md>
```

Never infer a plan decision from the user's tone.

Only for a report whose fixed view says `Report contract: 2.0`, an explicit legacy report-authoring decision may be recorded. A reason file in that same temporary directory is always required:

```bash
okstra user-response legacy-report-authoring --transaction <transaction> --status <approved|denied> --reason-file <reason.md>
```

Report contract 3.0 rejects this command because report inputs have separate owners.

## Step 7: Finalize once

```bash
okstra user-response finalize --transaction <transaction>
```

Only `finalize` publishes the sidecar. Report the returned `sidecar` path. A retry with the same transaction returns the same published result.

Leave this guidance in the final answer:

> This answer was recorded in the `user-responses/` sidecar (`<sidecar path>`). Re-running this task with `/okstra-run` attaches the answer to the next eligible phase.

## Output rules

- Keep responses in the user's language.
- Never edit a rendered report, report record, approval ledger, lead events, team state, convergence state, or report-writer narrative.
- Never edit a `user-responses/` sidecar directly. Publish it only with `user-response finalize`.
- Never create or parse structured state for these commands. Pass scalar arguments and Markdown body files only.