# summary

Open a clarification question from a developer or qa phase.

# description

Suspends the active developer or qa phase with status `awaiting_clarification` and records a clarification question directed to a PO or architect.

Appends a JSON Lines clarification entry to `.setup-agents/state/clarifications.jsonl` and updates the workflow run record in `.setup-agents/state/workflow-runs.jsonl`.

Use `setup-agents workflow clarify-respond` to record the answer and resume the phase.

# flags.run.summary

Workflow run id.

# flags.run.description

The id of the active workflow run containing the phase to suspend.

# flags.from.summary

Role opening the clarification.

# flags.from.description

The phase role requesting clarification. Must be `developer` or `qa`.

# flags.to.summary

Role receiving the clarification.

# flags.to.description

The role that should answer the clarification. Use `po` for Product Owner or `architect` for Architect.

# flags.question.summary

Clarification question text.

# flags.question.description

The question to be answered before the phase can continue.

# examples

- Open a clarification from developer to architect:

  <%= config.bin %> <%= command.id %> --run wf-123 --from developer --to architect --question "Should we use batch or queueable for this async job?"

- Open a clarification from qa to po:

  <%= config.bin %> <%= command.id %> --run wf-123 --from qa --to po --question "Is field X required in the acceptance criteria?"

# errors.run-not-found

Workflow run not found: %s

# info.created

Clarification opened: %s → %s (%s)

# info.respond-hint

To respond, run: sf setup-agents workflow clarify-respond --run %s --clarification %s --answer "<your answer>"