From 81beabcc7ead00b01f0d69ca53b015d5f0813b81 Mon Sep 17 00:00:00 2001
From: Allen Hutchison <allen@hutchison.org>
Date: Mon, 24 Aug 2026 09:38:21 -0700
Subject: [PATCH 1/2] feat(auto-dev): needs-info questions are decisions, not
 essays
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A maintainer answering a needs-info comment should be able to decide from
one read. The old question template asked only for "specific, numbered"
questions, which drifts toward long context-dumps that restate the issue
back to the person who filed it — and an ask that takes ten minutes to
parse is an ask that sits unanswered, stalling the queue behind it.

Give every question a fixed five-part shape — area, user-facing impact,
the problem, the options with their tradeoffs, and a recommendation —
capped at 300 words each, three questions per comment. Missing-fact asks
with no genuine fork keep the first three parts and name the fact needed
rather than inventing options to fill the slot.

Both triage branches that produce these comments (no-label -> Needs-info
and the Needs-info follow-up) point at the shape, so a revised ask stays
as tight as the first one.
---
 plugins/auto-dev/skills/auto-dev/SKILL.md     |  4 ++
 .../auto-dev/references/comment-formats.md    | 39 +++++++++++++++++--
 .../skills/auto-dev/references/triage.md      | 15 ++++---
 3 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/plugins/auto-dev/skills/auto-dev/SKILL.md b/plugins/auto-dev/skills/auto-dev/SKILL.md
index 2bc6f07..db6cdb3 100644
--- a/plugins/auto-dev/skills/auto-dev/SKILL.md
+++ b/plugins/auto-dev/skills/auto-dev/SKILL.md
@@ -260,6 +260,10 @@ The plan, question, and park-proposal templates the triage pass posts live in
 format lives in [`references/fallback-review.md`](references/fallback-review.md). Read the relevant
 file before posting. Every comment's first line is `config.autoDev.marker`.
 
+Questions are written to be answered in one read: each names the area, the user-facing impact, the
+problem, the options, and a recommendation — and each stays under 300 words. Long context-dumps
+stall the queue; a maintainer who can answer from their phone doesn't.
+
 ## Exit report
 
 Every tick ends by printing a structured report — the scheduled task surfaces it, an interactive
diff --git a/plugins/auto-dev/skills/auto-dev/references/comment-formats.md b/plugins/auto-dev/skills/auto-dev/references/comment-formats.md
index 17075eb..ddc99ee 100644
--- a/plugins/auto-dev/skills/auto-dev/references/comment-formats.md
+++ b/plugins/auto-dev/skills/auto-dev/references/comment-formats.md
@@ -35,19 +35,52 @@ propose the first slice only.
 
 ## Question comment
 
+Each question is a **decision the maintainer makes in one read** — not a request for an essay in
+reply. Keep every question under **300 words** including its options, and give it exactly these five
+parts:
+
+- **Area** — where the problem shows up (file, command, skill, subsystem).
+- **Impact** — what a user experiences because of it; skip if genuinely user-invisible and say so.
+- **Problem** — the ambiguity itself, 1–2 sentences.
+- **Options** — the real choices, one line each with its tradeoff. Two or three; if there is only
+  one real option this isn't a question, it's a plan.
+- **Recommendation** — which one you'd take and why, one sentence.
+
 ```markdown
 <!-- auto-dev -->
 
-Before this can be planned for implementation, a few things need clarification:
+Before this can be planned for implementation, a few decisions need your call:
+
+### 1. <short title of the decision>
+
+**Area:** <file / command / subsystem>
+**Impact:** <what a user sees or loses>
+**Problem:** <the ambiguity, 1–2 sentences>
+**Options:**
+
+- **A** — <option> (<tradeoff>)
+- **B** — <option> (<tradeoff>)
 
-1. <specific question>
-2. <specific question>
+**Recommendation:** A — <one sentence why>
+
+### 2. <short title of the decision>
+
+<same five parts>
 
 ---
 
 Reply here and the next automation pass will pick it up, or add the Skip label to opt this issue out of automation.
 ```
 
+Cut anything that isn't one of the five parts: no restating the issue back to the maintainer, no
+background they already have, no code excerpts, no "as discussed above". Three questions is the
+practical ceiling for one comment — if there are more, ask the ones that block planning and leave
+the rest.
+
+A question with no genuine options is still a question — a pure missing-fact ("which account does
+this run as?") keeps Area / Impact / Problem and replaces Options / Recommendation with the specific
+fact needed. The word cap applies the same way.
+
 ## Park proposal comment
 
 Use this when an issue can't move forward because it needs a maintainer decision the skill can't
diff --git a/plugins/auto-dev/skills/auto-dev/references/triage.md b/plugins/auto-dev/skills/auto-dev/references/triage.md
index 78bb78f..ad733cb 100644
--- a/plugins/auto-dev/skills/auto-dev/references/triage.md
+++ b/plugins/auto-dev/skills/auto-dev/references/triage.md
@@ -12,9 +12,11 @@ Assess whether the issue contains enough to plan from (clear problem, scoped out
 design fork):
 
 - _Plannable_ → draft an implementation plan, post it as a comment, add the Planned label.
-- _Not plannable, and the gap is missing facts the maintainer can supply_ → post one comment asking
-  the specific missing questions (numbered, concrete — not "please clarify"), add the Needs-info
-  label.
+- _Not plannable, and the gap is missing facts or a call the maintainer can supply_ → post one
+  comment asking the specific missing questions (numbered, concrete — not "please clarify"), add the
+  Needs-info label. Frame each one as a decision the maintainer can make in a single read — area,
+  user impact, problem, options, recommendation — and keep it under 300 words; see the Question
+  comment template in `comment-formats.md`.
 - _Not plannable because it needs a maintainer decision the skill can't make_ — a design fork that's
   theirs to resolve, a dependency on still-open work, or the issue body itself signals deferral
   ("not actionable yet", "revisit once X lands") → post a **park proposal**: name the blocker, offer
@@ -30,9 +32,10 @@ comment?
 - _Yes, and it says to park_ ("park it", "hold", "not now", "park", or a 👍 on a park proposal) →
   swap label to Parked.
 - _Yes, and it resolves the questions_ → draft and post the plan, swap label to Planned.
-- _Yes, but it raises new ambiguity_ → ask the follow-up (stay Needs-info) — but if this would be the
-  third unanswered round-trip, stop asking and either propose parking or leave a final note that the
-  issue needs maintainer attention.
+- _Yes, but it raises new ambiguity_ → ask the follow-up (stay Needs-info), in the same five-part,
+  under-300-words shape as the first ask — but if this would be the third unanswered round-trip,
+  stop asking and either propose parking or leave a final note that the issue needs maintainer
+  attention.
 
 ## Planned
 

From 06985244251e7d2022ad025488a70a6e7ea190a2 Mon Sep 17 00:00:00 2001
From: Allen Hutchison <allen@hutchison.org>
Date: Mon, 24 Aug 2026 09:51:27 -0700
Subject: [PATCH 2/2] fix(auto-dev): keep design forks on the park-proposal
 branch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The question branch said "missing facts or a call the maintainer can
supply", which made an unlabelled design fork match both it and the
park-proposal branch immediately below — two different outcomes for the
same issue, with nothing to break the tie. Design forks route to park
proposals; that boundary predates this PR and shouldn't be blurred by it.

Back to "missing facts". The five-part framing and the 300-word cap are
unaffected — they describe how a question is written, not which issues
become questions.
---
 plugins/auto-dev/skills/auto-dev/references/triage.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/plugins/auto-dev/skills/auto-dev/references/triage.md b/plugins/auto-dev/skills/auto-dev/references/triage.md
index ad733cb..873c031 100644
--- a/plugins/auto-dev/skills/auto-dev/references/triage.md
+++ b/plugins/auto-dev/skills/auto-dev/references/triage.md
@@ -12,11 +12,11 @@ Assess whether the issue contains enough to plan from (clear problem, scoped out
 design fork):
 
 - _Plannable_ → draft an implementation plan, post it as a comment, add the Planned label.
-- _Not plannable, and the gap is missing facts or a call the maintainer can supply_ → post one
-  comment asking the specific missing questions (numbered, concrete — not "please clarify"), add the
-  Needs-info label. Frame each one as a decision the maintainer can make in a single read — area,
-  user impact, problem, options, recommendation — and keep it under 300 words; see the Question
-  comment template in `comment-formats.md`.
+- _Not plannable, and the gap is missing facts the maintainer can supply_ → post one comment asking
+  the specific missing questions (numbered, concrete — not "please clarify"), add the Needs-info
+  label. Frame each one as a decision the maintainer can make in a single read — area, user impact,
+  problem, options, recommendation — and keep it under 300 words; see the Question comment template
+  in `comment-formats.md`.
 - _Not plannable because it needs a maintainer decision the skill can't make_ — a design fork that's
   theirs to resolve, a dependency on still-open work, or the issue body itself signals deferral
   ("not actionable yet", "revisit once X lands") → post a **park proposal**: name the blocker, offer