From b0786a12209ef02046503388031c24dfc72f76cd Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:23:32 -0800 Subject: [PATCH 1/2] chore(quest): claim quest/m0/dialog-options.md Quest-Claim: 825e2f4e4bc23915 From ceccde83755dddc1874b5e6e75899e8d398a1155 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 21 Nov 2026 23:27:11 -0800 Subject: [PATCH 2/2] Mold common maintainer answers into dialog rules Add "Explain it first" to decision, plan, and follow-up dialogs, a standard option set for steps only the user can take, and "Drop" on /quest-plan's goal prompt. /quest-review asks the pick with /quest-merge's options instead of its own stale list. Co-Authored-By: Claude Opus 5.5 --- assets/AGENTS.md | 3 +++ assets/skills/merge.md | 1 - assets/skills/plan.md | 2 +- assets/skills/review.md | 7 ++---- quest/m0/agent-and-question-hooks.md | 3 +-- quest/m0/dialog-options.md | 36 ---------------------------- 6 files changed, 7 insertions(+), 45 deletions(-) delete mode 100644 quest/m0/dialog-options.md diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 849a3a9c..3a6d1b8a 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -241,6 +241,9 @@ Recommend in every prompt, a multiple-choice list included: mark each option you An answer such as "whatever you recommend" picks your recommendations; act on them without asking again. Do not use asynchronous question tools. +A dialog for a decision, plan, or follow-up offers concrete choices and keeps one option for "Explain it first", which walks the user through the problem, current behavior, and each choice's trade-offs, then asks again without it. +A dialog for a step only the user can take offers, in this order: the agent taking it, such as by driving the browser, when it plausibly can; "Done / I'll do it now"; "Not at my PC (defer)", which keeps the wait and skips it for the session; and "Drop the wait", which a tool holding fewer options leaves to the user's typed answer. + If no blocking tool is available, or it returns without an answer, put the question and numbered choices in your final reply and end the turn. Resume when the user answers; do not bury the question in a progress update or wait with sleeps or timed polls. Silence, elapsed time, and a preselected recommendation are not answers or approval. diff --git a/assets/skills/merge.md b/assets/skills/merge.md index 442bf3a1..b9db299e 100644 --- a/assets/skills/merge.md +++ b/assets/skills/merge.md @@ -43,6 +43,5 @@ A PR that left the queue unmerged shows why under `landing-stopped` in `quest st Never close a PR to unstick it, and never work around a refused merge; ask instead. Ask the user for the pick with your recommended action, one of `/quest-merge`, `/quest-iterate`, skip, or delete, plus `/quest-merge` when you recommend another, "Explain it first", and "Rethink it". -"Explain it first" walks them through the change and its open choices; ask again without it. "Rethink it" starts a fresh background sub-agent, given the PR, its reviews and threads, and its quest's Goal, Plan, and evidence (read the deleted file on the base), not your recommendation, to start from scratch: brainstorm other approaches to the problem, decide whether this PR is the best path forward, and recommend merging it, iterating toward a named alternative, or dropping it. Ask again without it, its recommendation beside yours, and where they differ. diff --git a/assets/skills/plan.md b/assets/skills/plan.md index 1a97cf20..5f0973d6 100644 --- a/assets/skills/plan.md +++ b/assets/skills/plan.md @@ -9,7 +9,7 @@ Search by the code and behavior the work touches, not only its keywords: a quest Show any overlap in the first round. Interview the user with the grill skill. -The goal is the root of its tree, so the first round asks only it: restate the observable outcome, why it matters, and its boundaries and non-goals in one sentence, and get that confirmed before any other question. +The goal is the root of its tree, so the first round asks only it: restate the observable outcome, why it matters, and its boundaries and non-goals in one sentence, and get that confirmed before any other question, with "Drop" among its options for work not worth planning. Choose the structure yourself rather than asking: one quest per independently completable outcome, an epic for related ones, an edit to an existing quest that already owns the work, and the milestone each new quest joins, by its urgency and by any milestone rule the user has stated, such as "CI and flakes join m0". Show that structure in the summary, with each quest's size and milestone and the reason for the milestone, so the user can correct it in the PR's review. diff --git a/assets/skills/review.md b/assets/skills/review.md index c4514546..2d7a5a64 100644 --- a/assets/skills/review.md +++ b/assets/skills/review.md @@ -52,11 +52,8 @@ Once the reset passes or the login is restored, the item has cleared: whoever fi Push, resolve each `duplicate` line `quest status ` then prints as the guide's Creation describes, then mark the PR ready for review: with `quest ready `, which also drops its `## Waiting` section, or with `gh pr ready ` for a draft you reviewed without a hold. Summarize the review, with its last round's score and rationale, and CI from `quest status `. -Name any decisions the review raised without answering them, then ask the user for the pick as `/quest-merge` describes, recommending one of: -- `/quest-merge`: the PR is landable as `/quest-merge` defines it, or will be once fixed with no decision left for the user, such as failing checks or unaddressed automated review findings; `/quest-merge` runs `/quest-iterate` on it first. -- `/quest-iterate`: the review raised significant issues or decisions, which it settles with the grill skill's interview. -- skip: the PR should not be merged yet. -- delete: the quest should be deleted. +Name any decisions the review raised without answering them, then ask the user for the pick with `/quest-merge`'s options. +Recommend `/quest-merge` when the PR is landable as it defines, or will be once fixed with no decision left for the user, such as failing checks or unaddressed automated review findings, since `/quest-merge` runs `/quest-iterate` first; recommend `/quest-iterate` when the review raised significant issues or decisions. While its required checks are still running, report that instead of asking; `/quest-run` asks once they finish. diff --git a/quest/m0/agent-and-question-hooks.md b/quest/m0/agent-and-question-hooks.md index c8d6ee7d..bc4c3a8d 100644 --- a/quest/m0/agent-and-question-hooks.md +++ b/quest/m0/agent-and-question-hooks.md @@ -7,7 +7,7 @@ Move two recurring agent mistakes from prose into `quest hook` (`src/cli/hooks.t 1. **Block stalls on running background agent/wait tasks:** Extend `Stop` and `SubagentStop` in `src/cli/hooks.ts` / `src/cli/rules.ts` to refuse ending a turn while background `quest agent` (`start` or `resume`) or `quest wait` commands started by that session are still running, matching the existing `quest gate` refusal. 2. **Enforce `(Recommended)` on blocking question dialogs:** Add a `PreToolUse` hook check on `AskUserQuestion` (Claude Code) and `request_user_input` (Codex) that denies any multi-option question (2 or more options) when no option ends with `(Recommended)`, naming the fix in the denial reason, and update `quest setup`'s hook matchers accordingly. Trim the now-enforced recommendation reminder from always-loaded prose where hooks run (keeping it in `CHECKED_CONTEXT` or non-hook guidance). -Non-goal: checking option text semantics beyond `(Recommended)` (such as requiring `"Explain it first"`), which remains judgment-based in [Mold common maintainer answers into dialog rules](/quest/m0/dialog-options.md). +Non-goal: checking option text semantics beyond `(Recommended)`, such as requiring `"Explain it first"`, which the guide's Questions section leaves to judgment. ## Plan @@ -34,4 +34,3 @@ Agent's choices, for the implementer to revisit: ## Related - [Mistake audit](/quest/m0/mistake-audit.md) - tracks stalls and recommendation rates weekly -- [Mold common maintainer answers into dialog rules](/quest/m0/dialog-options.md) - prose dialog rules that complement the `(Recommended)` hook diff --git a/quest/m0/dialog-options.md b/quest/m0/dialog-options.md deleted file mode 100644 index e5668536..00000000 --- a/quest/m0/dialog-options.md +++ /dev/null @@ -1,36 +0,0 @@ -# [M] Mold common maintainer answers into dialog rules - -## Goal - -Update `assets/AGENTS.md` (`## Questions`) and `assets/skills/` so blocking question dialogs reflect the maintainer's most common free-text answers and stop offering contradictory or unused options: - -1. Every non-trivial decision, plan, or follow-up dialog reserves an option for `"Explain it first"` (preferring 2 to 3 concrete choices plus `"Explain it first"` within the 4-option limit), and `/quest-plan` Goal prompts include a `"Drop"` option. -2. `Maintainer:` wait and manual-action dialogs (a step only the maintainer can do, with no choice to make) standardize on: Agent handles or drives the browser (when plausible), Done / I'll do it now, `"Not at my PC (defer)"`, and Drop wait. -3. `assets/skills/review.md` removes its stale option list (`- /quest-iterate`, `- skip`, `- delete`) so merge picks follow `#768`'s option set in `assets/skills/merge.md` everywhere. - -Non-goal: enforcing `(Recommended)` in a `PreToolUse` hook (tracked in [Block agent stalls in Stop hook and missing recommendations in PreToolUse](/quest/m0/agent-and-question-hooks.md)), or changing follow-ups from one question per follow-up (`#636`). - -## Plan - -Decided 2026-11-21 (maintainer, `/quest-plan`, from a 22-day transcript audit across three of the maintainer's hosts: 10,733 dialog answers, 1,356 true free-text custom answers after filtering multi-selects): - -- Which dialog option rules should be added to `assets/AGENTS.md` and the merge/review skills? - - ✅ Adopt all three dialog rules: universal `"Explain it first"` + `"Drop"` on plan goals, standardized `Maintainer:` wait options, and `review.md`/`merge.md` alignment (recommended) - - Rejected: universal Explain + merge/review cleanup only (skip Wait and Drop rules); also adding a `"Defer to later milestone"` option on follow-up prompts - -Evidence from the 2026-11-21 audit: - -- Requests for context or explanation (`idk`, lacking context, asking to explain, or a clarifying question) appeared in 538 custom answers over 22 days (256 since 2026-11-11, and 192 on dialogs that offered no Explain option). PR `#768` added `"Explain it first"` only to merge picks, whereas most confusion occurred in `/quest-plan`, coordinator decisions, and follow-up prompts. -- Dropping, skipping, or rejecting work appeared in 136 custom answers (56 since 2026-11-11), often on `/quest-plan` Goal prompts that only offered `Yes` / `Adjust`. -- Asking the agent to do a manual step or drive the browser appeared in 62 custom answers (28 since 2026-11-11), and deferring because the maintainer was away from their PC appeared 13+ times during travel. -- Since 2026-11-15, 94.2% of 558 merge picks chose `/quest-merge`. Both `#768` options (`"Explain it first"` and `"Rethink it"`) were already used in their first 4 days, while `assets/skills/review.md` still listed `- /quest-iterate`, `- skip`, and `- /quest-delete` (picked 1 to 2% when recommending merge), causing agents to keep offering them. - -This quest edits `assets/AGENTS.md` and `assets/skills/`, which the maintainer asked for by planning it. - -Agent's choices, for the implementer to revisit: - -- `"Explain it first"` does not apply to those wait and manual-action dialogs: their four fixed options already fill the 4-option limit, and a manual step needs no explanation of trade-offs. A `Maintainer:` item that is a decision (it gives options and a recommendation) is a decision dialog and follows rule 1 instead: 2 to 3 concrete choices plus `"Explain it first"`. -- Keep the additions in `assets/AGENTS.md` (`## Questions`) and `assets/skills/plan.md` concise per `quest guide prompting`, and define `"Explain it first"` once in `## Questions` (walk through the problem, current behavior, and concrete trade-offs, then re-ask without it) so `merge.md` does not repeat it. -- Keep `"Rethink it"` on merge picks in `assets/skills/merge.md`, and update `assets/skills/review.md` so it delegates its pick options wholly to `/quest-merge` without restating a conflicting bullet list. -- For `Maintainer:` wait dialogs, note that `"Not at my PC (defer)"` leaves the `## Waiting` item in place and skips it for the current session without re-asking. -- Check `test/skills.test.ts` and `INLINE_LIMIT` after edits so every composed skill stays well under 30,000 characters.