jbr870/devwork-skills

Fork 0

requirements/technical-plan: one question round per phase, not four inside eight minutes #42

New issue

Closed

opened 2026-08-14 13:01:48 +00:00 by jbr870 · 1 comment

jbr870 commented

2026-08-14 13:01:48 +00:00

Owner

Rank 5 of 13 in #37 · est. saving ~30m

Evidence

Feature #230 stopped and waited for a human eight times on 2026-08-13, for ~66 minutes total
(excluding the UAT gate, which is meant to be slow):

/requirements asked at 10:47, 10:48, 10:51 and again at 10:55 — four separate stalls inside
eight minutes. The last one cost 24m 30s, the largest stall of the day.
The devcontainer question at 11:43 cost 16m 36s.
Smaller stalls at 09:53 (4m), 12:37 (7m), 17:14 (4m).

Each AskUserQuestion is a full stop: nothing else progresses while it is open.

What happens now

Skills ask as questions arise. /requirements in particular asks during gathering, again after the
adversarial panel, and again for side decisions — each a separate round trip.

Proposed change

One question round per phase where the phase's structure allows it. Specifically: a phase collects
its open questions, and asks them as a single multi-question AskUserQuestion at the point where
the last of them is known. Where a later answer genuinely depends on an earlier one, the phase may
open a second round, but must say why in the prompt.

Related but distinct: #14 covers batching decision resolutions at the /resolve end. This is
about the questions asked during a phase.

Acceptance

/requirements and /technical-plan each ask at most one question round per phase, absent a
stated dependency.
The panel-driven questions are folded into the same round as the gathering questions where the
panel has already run.

**Rank 5 of 13** in #37 · est. saving **~30m** ## Evidence Feature #230 stopped and waited for a human **eight times** on 2026-08-13, for ~66 minutes total (excluding the UAT gate, which is meant to be slow): - `/requirements` asked at 10:47, 10:48, 10:51 and again at 10:55 — **four separate stalls inside eight minutes**. The last one cost **24m 30s**, the largest stall of the day. - The devcontainer question at 11:43 cost 16m 36s. - Smaller stalls at 09:53 (4m), 12:37 (7m), 17:14 (4m). Each `AskUserQuestion` is a full stop: nothing else progresses while it is open. ## What happens now Skills ask as questions arise. `/requirements` in particular asks during gathering, again after the adversarial panel, and again for side decisions — each a separate round trip. ## Proposed change One question round per phase where the phase's structure allows it. Specifically: a phase collects its open questions, and asks them as a single multi-question `AskUserQuestion` at the point where the last of them is known. Where a later answer genuinely depends on an earlier one, the phase may open a second round, but must say why in the prompt. Related but distinct: #14 covers batching **decision resolutions** at the `/resolve` end. This is about the questions asked *during* a phase. ## Acceptance - `/requirements` and `/technical-plan` each ask at most one question round per phase, absent a stated dependency. - The panel-driven questions are folded into the same round as the gathering questions where the panel has already run.

jbr870 added the

labels

2026-08-14 13:01:48 +00:00

jbr870 referenced this issue

2026-08-14 13:02:37 +00:00

Feature-230 time study: 13 ranked pipeline-efficiency changes #37

jbr870 referenced this issue

2026-08-14 13:02:38 +00:00

Feature-230 time study: 13 ranked pipeline-efficiency changes #37

jbr870 referenced this issue from a commit

2026-08-25 09:31:09 +00:00

requirements: batch a step's structured questions into one round

jbr870 closed this issue

2026-08-25 09:31:09 +00:00

jbr870 commented

2026-08-25 09:31:38 +00:00

Author

Owner

/meta-amend outcome — amended

Commit 7879495 on main.

Verified at HEAD (`6aeae6b`)

The finding held for /dev:requirements, and did not hold for /dev:technical-plan:

requirements/SKILL.md said flatly "Ask questions one at a time"; requirements-gathering.md repeated it in Step 2 ("Ask questions one at a time"), in Step 6 ("Ask one at a time"), and in the reference section "One Question Per Message". Nothing distinguished a prose exploration question from an AskUserQuestion tool call, so "one at a time" read as a mandate for N separate stalls.
preq-review.md §3 interactive: "bring them to the human, one at a time" — the panel's concerns are all known at once, and were being asked serially anyway.
/dev:technical-plan asks nothing. Its only AskUserQuestion reference is the note at SKILL.md:363 recording that the old "which out-of-scope items become issues?" prompt moved to /dev:resolve as a scope-disposition Pending Decision. Every choice it faces is routed to the record, not to a stall. That half of the acceptance criterion was already satisfied, so technical-plan is untouched — an amendment there would have been text with nothing to fix.

The amendment

Canonical rule added under requirements-gathering.md → Tool Usage, One question round per step:

Collect a step's structured choice points and ask them as one call at the point where the last is known (AskUserQuestion carries up to four questions per round). More than four independent questions in one step means the step hasn't narrowed its own scope.
A second round only when a later question's options depend on an earlier answer — and the prompt must say so. "I thought of another one" is written up explicitly as not a dependency: it's a round that was sent too early.
The distinction the old text was missing: sequential dialogue ≠ a question round. Step 2's exploration stays one at a time because each answer genuinely steers the next — but in prose, "because a prose question is a reply and a tool call is a stop." Step 2 was rewritten to say so directly.
A countable bar: this procedure owes two rounds — Step 3 (scope/split) and Step 6 (collected open questions), the second being the dependency exception itself, since Step 6's questions can't be enumerated until the PREQ is drafted against the scope Step 3 chose. "A third round in this procedure is a defect."
Step 6 now says collect-then-ask-once explicitly; the reference section's "One Question Per Message" is scoped to the exploration dialogue, with a line noting that four AskUserQuestion calls in a row are its bad example with worse latency, not its good one.
preq-review.md §3 brings the panel's concerns in one round, and absorbs any Step-6 question still open when it runs — that is the fold AC2 asks for, in the only ordering that exists (the panel runs in Phase 2, after gathering, so its concerns cannot join a Phase-1 round; a leftover Phase-1 question can join the panel's).
requirements/SKILL.md's one-line instruction now points at the rule instead of contradicting it.

No change to whether these questions fire — they remain structured decision points, batched rather than suppressed.

Gate

scripts/lint-conventions.sh — clean.

Desk-check against the originating scenario (verity #230, 2026-08-13)

Recorded: /requirements stalled at 10:47, 10:48, 10:51 and 10:55 — four rounds in eight minutes, the last costing 24m 30s (the largest stall of the day). Under the amended text:

Recorded	Amended
two early asks, ~1 min apart (exploration)	prose dialogue — replies, not stops
scope/approach ask	Step 3, round 1 (only one of the three branches ever fires)
open-questions ask	Step 6, round 2 — collected in one call, permitted by the stated dependency on Step 3's scope
—	panel concerns: one round in Phase 2, absorbing any Step-6 leftover

Four AskUserQuestion stalls become two in Phase 1 plus one in Phase 2, and the exploration pair stops being tool calls at all. AC1 holds for /requirements (one round per step, the only second round being the dependency the text names) and holds already for /technical-plan; AC2 holds in the ordering that exists.

What validates it next

The next interactive /dev:requirements run — count AskUserQuestion calls in Phase 1. Two is correct, three is the defect the text now names. The thing to watch is Step 6: the rule only pays off if the walk for open questions is genuinely completed before the first call, and that is a discipline the text asks for but cannot enforce mechanically.

## /meta-amend outcome — amended Commit `7879495` on `main`. ### Verified at HEAD (`6aeae6b`) The finding held for `/dev:requirements`, and did **not** hold for `/dev:technical-plan`: - `requirements/SKILL.md` said flatly *"Ask questions one at a time"*; `requirements-gathering.md` repeated it in Step 2 (*"Ask questions **one at a time**"*), in Step 6 (*"Ask **one at a time**"*), and in the reference section *"One Question Per Message"*. Nothing distinguished a prose exploration question from an `AskUserQuestion` tool call, so "one at a time" read as a mandate for N separate stalls. - `preq-review.md` §3 interactive: *"bring them to the human, one at a time"* — the panel's concerns are all known at once, and were being asked serially anyway. - **`/dev:technical-plan` asks nothing.** Its only `AskUserQuestion` reference is the note at SKILL.md:363 recording that the old *"which out-of-scope items become issues?"* prompt **moved to `/dev:resolve`** as a `scope-disposition` Pending Decision. Every choice it faces is routed to the record, not to a stall. That half of the acceptance criterion was already satisfied, so technical-plan is untouched — an amendment there would have been text with nothing to fix. ### The amendment Canonical rule added under `requirements-gathering.md` → Tool Usage, **One question round per step**: - Collect a step's structured choice points and ask them as **one** call at the point where the last is known (`AskUserQuestion` carries up to four questions per round). More than four independent questions in one step means the step hasn't narrowed its own scope. - A **second** round only when a later question's *options* depend on an earlier answer — and the prompt must say so. *"I thought of another one"* is written up explicitly as **not** a dependency: it's a round that was sent too early. - **The distinction the old text was missing:** sequential dialogue ≠ a question round. Step 2's exploration stays one at a time because each answer genuinely steers the next — but **in prose**, "because a prose question is a reply and a tool call is a stop." Step 2 was rewritten to say so directly. - **A countable bar:** this procedure owes **two** rounds — Step 3 (scope/split) and Step 6 (collected open questions), the second being the dependency exception itself, since Step 6's questions can't be enumerated until the PREQ is drafted against the scope Step 3 chose. *"A third round in this procedure is a defect."* - Step 6 now says collect-then-ask-once explicitly; the reference section's *"One Question Per Message"* is scoped to the exploration dialogue, with a line noting that four `AskUserQuestion` calls in a row are its bad example with worse latency, not its good one. - `preq-review.md` §3 brings the panel's concerns in **one** round, and **absorbs any Step-6 question still open when it runs** — that is the fold AC2 asks for, in the only ordering that exists (the panel runs in Phase 2, after gathering, so its concerns cannot join a Phase-1 round; a leftover Phase-1 question can join the panel's). - `requirements/SKILL.md`'s one-line instruction now points at the rule instead of contradicting it. No change to *whether* these questions fire — they remain structured decision points, batched rather than suppressed. ### Gate `scripts/lint-conventions.sh` — clean. ### Desk-check against the originating scenario (verity #230, 2026-08-13) Recorded: `/requirements` stalled at 10:47, 10:48, 10:51 and 10:55 — four rounds in eight minutes, the last costing 24m 30s (the largest stall of the day). Under the amended text: | Recorded | Amended | |---|---| | two early asks, ~1 min apart (exploration) | prose dialogue — replies, not stops | | scope/approach ask | Step 3, round 1 (only one of the three branches ever fires) | | open-questions ask | Step 6, round 2 — collected in one call, permitted by the stated dependency on Step 3's scope | | — | panel concerns: one round in Phase 2, absorbing any Step-6 leftover | Four `AskUserQuestion` stalls become two in Phase 1 plus one in Phase 2, and the exploration pair stops being tool calls at all. AC1 holds for `/requirements` (one round per step, the only second round being the dependency the text names) and holds already for `/technical-plan`; AC2 holds in the ordering that exists. ### What validates it next The next interactive `/dev:requirements` run — count `AskUserQuestion` calls in Phase 1. Two is correct, three is the defect the text now names. The thing to watch is Step 6: the rule only pays off if the walk for open questions is genuinely completed **before** the first call, and that is a discipline the text asks for but cannot enforce mechanically.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

jbr870/devwork-skills#42

No description provided.

Rows
Columns