needs_attention is a tri-state in the dashboard and a two-state on the CLI #496

New issue

Open

opened 2026-09-01 15:32:48 +00:00 by mph · 1 comment

mph commented

2026-09-01 15:32:48 +00:00

Owner

Found triaging IW-436 (LESSONS.md entry 9). This is a design question about the field's contract, not a defect.

The CLI can only reach two of three states

ReviewStateCliParser.scala's --needs-attention call sites (in parseWriteArgs and parseUpdateArgs) can only produce Some(true) or None. --clear-needs-attention removes the key (core/model/ReviewStateUpdater.scala:103, :106-107), which is None again.

The dashboard implements three

dashboard/jvm/src/domain/PendingAct.scala:126-129 distinguishes three states deliberately: an explicit false withdraws the claim outright, while absence leaves activity to speak.

So a workflow that wants "definitely not waiting for the human, whatever the activity says" has no way to say it.

Measured

Of the 37 cards under project-management/ that carry the key, 37 hold true and none holds false.

The question

Should the CLI gain a way to write an explicit false — a --no-needs-attention flag, or honouring a value on --needs-attention — or should the dashboard's tri-state collapse to the CLI's two? Either answer is coherent; the current split is not.

Scope note

This is not IW-436 defect 1. Defect 1 was that --needs-attention false was accepted silently and wrote true; IW-436 Phase 3 fixed that with a hard refusal (exit 1) and a remedy pointing at --clear-needs-attention. That refusal is correct under either answer here.

Found triaging IW-436 (LESSONS.md entry 9). This is a design question about the field's contract, not a defect. ## The CLI can only reach two of three states `ReviewStateCliParser.scala`'s `--needs-attention` call sites (in `parseWriteArgs` and `parseUpdateArgs`) can only produce `Some(true)` or `None`. `--clear-needs-attention` removes the key (`core/model/ReviewStateUpdater.scala:103`, `:106-107`), which is `None` again. ## The dashboard implements three `dashboard/jvm/src/domain/PendingAct.scala:126-129` distinguishes three states deliberately: an explicit `false` **withdraws the claim outright**, while absence leaves `activity` to speak. So a workflow that wants "definitely not waiting for the human, whatever the activity says" has no way to say it. ## Measured Of the 37 cards under `project-management/` that carry the key, **37 hold `true` and none holds `false`.** ## The question Should the CLI gain a way to write an explicit `false` — a `--no-needs-attention` flag, or honouring a value on `--needs-attention` — or should the dashboard's tri-state collapse to the CLI's two? Either answer is coherent; the current split is not. ## Scope note This is not IW-436 defect 1. Defect 1 was that `--needs-attention false` was **accepted silently** and wrote `true`; IW-436 Phase 3 fixed that with a hard refusal (exit 1) and a remedy pointing at `--clear-needs-attention`. That refusal is correct under either answer here.

mph referenced this issue from a commit

2026-09-01 15:36:36 +00:00

workflow: Triage lessons for IW-436

mph referenced this issue

2026-09-01 15:36:57 +00:00

IW-436: review-state CLI — fix five flag-parsing and update-semantics defects #499

claude commented

2026-10-15 21:56:01 +00:00

Member

Intake: needs-input

1. Should a user be able to write `needs_attention: false` from the CLI, or should the dashboard treat false the same as no value?

The dashboard has three states. An explicit false withdraws the claim, whatever the activity says. No value lets the activity decide. review-state write and review-state update can only set true or remove the field. But iw's own commands already write an explicit false: phase-start, and phase-merge on a merged card. So the gap is only in the CLI flags.

Lowering the flag is a decision, so an explicit false withdraws the claim whatever the activity says. Absence is not a decision, so it leaves the activity to speak.

https://code.iterative.works/iterative-works/iw-cli/src/branch/main/dashboard/jvm/src/domain/PendingAct.scala#L154-L162
https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/model/ReviewStateCliParser.scala#L73-L85
https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/commands/PhaseStart.scala#L167
https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/commands/PhaseMergedCard.scala#L39

a) The CLI gets a flag that writes an explicit false, for example --no-needs-attention. The CLI then agrees with the dashboard and with iw's own commands. --needs-attention continues to refuse a value, as IW-436 decided. Cost: one flag, its parser tests and its documentation.
b) The dashboard reads false the same as no value. The three-state rule goes away. Cost: the false that phase-start and phase-merge write stops withdrawing the claim, so a card with activity waiting can show up in a lane again. Those commands and their tests must change too.
c) Make no change and close the issue. All 37 cards that have the field hold true, so no workflow has asked for false yet. Cost: the CLI and the dashboard stay inconsistent.

Recommended: a) — iw's own commands already write an explicit false, so the three states are already in use and only the CLI flags lack the third.

Answer in a comment on this issue, per number, for example "1: a", or in your own words; intake reads it on its next iteration.

Intake: needs-input ### 1. Should a user be able to write `needs_attention: false` from the CLI, or should the dashboard treat false the same as no value? The dashboard has three states. An explicit false withdraws the claim, whatever the activity says. No value lets the activity decide. `review-state write` and `review-state update` can only set true or remove the field. But iw's own commands already write an explicit false: `phase-start`, and `phase-merge` on a merged card. So the gap is only in the CLI flags. > Lowering the flag is a decision, so an explicit `false` withdraws the claim whatever the activity says. Absence is not a decision, so it leaves the activity to speak. https://code.iterative.works/iterative-works/iw-cli/src/branch/main/dashboard/jvm/src/domain/PendingAct.scala#L154-L162 https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/model/ReviewStateCliParser.scala#L73-L85 https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/commands/PhaseStart.scala#L167 https://code.iterative.works/iterative-works/iw-cli/src/branch/main/core/commands/PhaseMergedCard.scala#L39 - **a) The CLI gets a flag that writes an explicit false, for example `--no-needs-attention`.** The CLI then agrees with the dashboard and with iw's own commands. `--needs-attention` continues to refuse a value, as IW-436 decided. Cost: one flag, its parser tests and its documentation. - **b) The dashboard reads false the same as no value.** The three-state rule goes away. Cost: the false that `phase-start` and `phase-merge` write stops withdrawing the claim, so a card with activity `waiting` can show up in a lane again. Those commands and their tests must change too. - **c) Make no change and close the issue.** All 37 cards that have the field hold `true`, so no workflow has asked for false yet. Cost: the CLI and the dashboard stay inconsistent. **Recommended: a)** — iw's own commands already write an explicit false, so the three states are already in use and only the CLI flags lack the third. Answer in a comment on this issue, per number, for example "1: a", or in your own words; intake reads it on its next iteration.

claude added the

needs-input

label

2026-10-15 21:56:01 +00:00