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 -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. + +**Area:** +**Impact:** +**Problem:** +**Options:** + +- **A** —