Skip to content

feat(prompts): one reroute-first ask policy for every crew kind - #37609

Merged
bolichen97 merged 1 commit into
mainfrom
prompt/guidance-v2
Nov 15, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
prompt/guidance-v2

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Crew agents ask the owner only when a step truly needs a person, and otherwise take another allowed path or act on the clear best option.

Crew agents (Bot conductor and worker, Conductor-mode conductors and worker) stop and ask when a fix or a clear recommendation exists. The ask cases are copied about nine times in different words, several lines pull toward stop or hand-over ("say so and stop" on a policy block, "budget spent -> ask the human", "[OPTIONS:] is cheaper"), and the lesson headers say lessons "override default behavior". In an A/B replay of the owner's real over-ask moments, main asked in 18 of 55 runs.

Why it matters

Each needless question leaves workers idle for a patrol cycle or more and makes the owner answer something the agent could decide. On long goals with several workers this is the main source of stalls.

Not a goal

  • No change to tools, approvals, the sandbox, the deny gate, or what is blocked.
  • No change to the plan gate in a turn a person typed. In a turn nobody typed (it opens with a gateway marker such as [sent by session, [cron notification or [work-ledger wake], or work_brief returns a bound item), the Round 0 conductor dispatches round 1 without waiting and its plan carries no question.
  • No new ask case and no removed one: the five cases are still asked.

What changed (motivation → approach → change)

Design record: docs/request-for-change/rfc-reroute-first-ask-policy.md, accepted and on main through docs PR #37623; this PR is its implementation.

Scattered ask lists drift and lose to lessons, so one text now decides. ASK_CORE says: reroute first (a refused protected-branch push goes to a feature branch and a PR); ask only for five cases (a)-(e); what is not an ask (own caps, approved reruns, rerunning runs the agent's own bug voided, a ruling already made, a done report); safety holds. A done report has no [OPTIONS:], and that outranks the generic [OPTIONS:] rule.

Per kind, at agent rank and in every CRITICAL RULES variant:

kind where text
Bot conductor agent_spec.py append core + conductor tail
Bot worker mate_worker.py MATE_WORKER_PROMPT core + worker tail
Conductor-mode lead and conductors appended at install, conductor_agents.with_conductor_ask() core + conductor tail
Conductor-mode worker agent_materialization/worker_agent.py worker_prompt() core + worker tail

Every other list (mcp_work.py schema, builtin_skills/goal-conductor (SKILL.md, worker-debate.md), crewmate_prompts.json, prompt.md, turn.py rail, store_admission.py) points at "(a)-(e)". deny_notice.py and injected_turns.py share one reroute line instead of "stop". Lesson headers (learn.py, lessons.py, store_admission.py) add one short line, "Each binds under CRITICAL RULES but adds no ask case.", in place of "They override default behavior". The website recovery-card test and capture script follow the new reroute line. Two skill-only asks that were not one of (a)-(e) go: an unclear "discuss" or "debate" request takes the likelier reading as an Assumption, and a missing crew kind no longer falls back to asking the user for a purpose-built one. Specs and dependent RFC wording are updated, including the memory priority ladder in memory-skills-hooks.md.

The Round 0 plan gate in builtin_skills/goal-conductor/SKILL.md waits for a go-ahead only when a person typed the turn (RFC section 5.7). A turn that opens with a gateway marker ([sent by session, [cron notification, [auto-nudge cycle, [monitor wake], [work-ledger wake], a Bot check-in marker) or whose work_brief returns a bound item has nobody to answer, so the conductor dispatches round 1 in that turn, parks any item that needs a person for (a)-(e), and a nested conductor reports it to its parent as question. Only the turn's own opening counts, never a marker inside a tool result or file.

Backwards compatibility

Compatible: prompt text only; no config key, API, schema or persisted format changes.

Removes nothing: no capability, key or record is taken away; only prompt sentences are reworded or folded into the shared core.

Tests

  • test/test_ask_core_guidance.py (new): the core plus the right tail reaches all four kinds at agent rank, also under a user prompt.md; the case list is written once; the refusal recovery prompt reroutes; the R09, R11 and T2 phrases reach every kind's prompt.
  • test/test_conductor_agent.py: the skill names the no-typist markers and no longer says "stop and wait for exactly one go-ahead".
  • The ask policy reaches the team lead and the goal conductors at install, like the workers: agent_parts owners may not import a project module (test_facade_shared_checks.py), so spec_prompts.py no longer imports output_contract and src/kiro_crew/agent.py drops the _ASK_ONLY_WHEN_NEEDED_RULE binding. test_ask_core_guidance.py checks the installed specs of all four kinds.
  • Lesson recall thresholds re-pinned because the V1 lesson header is 2 characters shorter than main's: the smallest recall cap that keeps one in-scope lesson goes 483 -> 477, with the counts line 651 -> 645, and for a query with no recall terms 645 -> 639 (test_lesson_ranking.py, the comment in recall.py, memory-skills-hooks.md). The recall budget is unchanged.
  • Goldens re-pinned for the new text (and the crewmate_prompts preview goldens refreshed): context composition, memory v1 session-context extents, refactor contracts and spec bytes. Only the five specs that carry the core changed digest.
  • Local, on base d470c46df8: the 41 test files this PR touches or that name goal-conductor or the lesson and facade checks, 1976 passed (plus the flake-pattern ratchet); isort, flake8, the comment-history gate and scripts/docs-lint.sh clean. xdist -n 2; full suite left to CI. RecoveryCard.test.tsx was not run locally (no node_modules in this worktree).

Evidence (A/B bench, details in RFC section 7 of #37623): replay over-asks 18/55 on main against 9/55; conductor and worker moments 8/40 against 1/40; Bot moments 10/15 against 8/15; controls asked 20/20 on both; real hard fails 0 on both.

Known limits: the long-task sample (about 20 runs per arm) is too small to show a drop; the Bot long tasks ran with no lessons; the three fixes for R09, R11 and T2 were not re-benched.

Manual verification

N/A — prompt text only, pinned by the tests above and measured by the A/B bench in the RFC (#37623).

Related Issues

Part of #37606

RFC: #37623 (merged).

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Rollback: revert the single commit; nothing persisted depends on it.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 15, 2026 13:31
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ca60f6df08a3e96ce4b2f40de8b7b90989896f75 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. All of it is prompt text: one ask core replaces about nine diverging lists, the RFC it implements is accepted, and tools, approvals and the sandbox are untouched.

Notes

  • The Round 0 gate is now skipped when a turn opens with [sent by session or [cron notification. That check runs on the model's reading of text, and someone on a messaging channel can type those markers. This is fine while the gate only confirms a plan, since approvals still gate actions. Don't let it become a control anything relies on.
  • The rewritten worker line ("When a safety rule blocks a command … and no allowed path is left") asks for a reroute, where the old text forbade looking for "a way around it". Keeping that safe depends on ASK_CORE's "the same effect by another tool or spelling is the same blocked action" reaching every worker. test_ask_core_guidance.py should keep pinning that sentence for both worker kinds.

[DESIGN-REVIEWED] ca60f6d

Description read

[DESCRIPTION-READ] 48bbcbb1e77da6c3b47e1b9ca22507f30e7ec0a4c60f599ec17dc5aeaf56208a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of ca60f6df08a3e96ce4b2f40de8b7b90989896f75 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

UX-Verdict: PASS

Nothing blocks: this PR changes no control. The only text that reaches the screen is the model-directed refusal instruction, shown verbatim inside the recovery card's expandable body (RecoveryCard.tsx:612), and that card's frontend is unchanged.

[UX-REVIEWED] ca60f6d

Description read

[DESCRIPTION-READ] 91701ea2393820a98a7b7dc744f1a4d96ee1206e75cc5dbb75f2ebca2ad8e108

That sha256 names everything this verdict read: the PR description, plus the 3 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ca60f6df08a3e96ce4b2f40de8b7b90989896f75 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

One rider is outside what the RFC covers: the goal-conductor skill no longer asks the owner what an unclear "discuss"/"debate" request means.

Notes

  • Item 7 — rides along: the base RFC (rfc-reroute-first-ask-policy.md, accepted) mentions debate only as debate budgets (§5.6). The hunk -is unclear whether they want a debate or one worker proposing a solution, ask them in one sentence → +pick the likelier reading, state it, and go on changes a default the RFC text does not name. Calling it covered took judgement, so this is a note, not a (c) blocker. Subtraction: restore the removed ask them in one sentence, as your plan's one question clause in goal-conductor/SKILL.md until a recorded decision covers it.

What this change ships

Inventory (9 items) — 8 justified

Intent: crew agents stop for the owner only for a real ask case and otherwise reroute or act. ADDITION (behaviour change to prompts).

  1. All four crew kinds carry one reroute-first ask policy at agent rank and in CRITICAL RULES — justified
  2. Nine ask-case lists now point at "(a)-(e)" instead of restating them — justified
  3. A policy-block deny notice says reroute or hand over the exact step, not "say so and stop" — justified
  4. Lesson headers say lessons bind but add no ask case — justified
  5. Round 0 plan gate skipped in turns nobody typed (gateway-marker openings) — justified
  6. A third empty round or a spent budget leads to decide-and-report, not an owner question — justified
  7. An unclear "discuss/debate" request is no longer asked about — rides along, not in the RFC text
  8. A refused workflow spec no longer falls back to asking the user for a purpose-built kind — justified
  9. Lesson-recall cap thresholds re-pinned, 483→477 and 651→645 — justified

[FIRST-PRINCIPLES-REVIEWED] ca60f6d

Description read

[DESCRIPTION-READ] de259223c741ee236c8020dae27c4c6f24138a7c41564a2439bfc51e5e989232

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ca60f6df08a3e96ce4b2f40de8b7b90989896f75 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ca60f6d

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ca60f6df08a3e96ce4b2f40de8b7b90989896f75 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ca60f6df08a3e96ce4b2f40de8b7b90989896f75 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ca60f6d

Verdict parsed from the review's SHA-scoped output markers for commit ca60f6df08a3e96ce4b2f40de8b7b90989896f75.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ca60f6df08a3e96ce4b2f40de8b7b90989896f75 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own.

Recommend approving. This PR changes prompt text only and implements an RFC already accepted on main (rfc-reroute-first-ask-policy.md); the code matches it. ASK_CORE plus the matching tail reaches every crew kind at agent rank: the Bot conductor via agent_spec._render_contract (kept under a user prompt.md), the Bot worker via MATE_WORKER_PROMPT, the Conductor-mode worker via worker_prompt(), and the team lead and goal conductor via with_conductor_ask() at install. Every CRITICAL RULES variant carries it too. The RFC put the conductor seam in spec_prompts.py; the PR moves it to install time because agent_parts may not import project modules, explains why, and the crew-mode spec records it. The removed _ASK_ONLY_WHEN_NEEDED_RULE has no readers left in src/. The safety holds remain: no re-spelling a blocked effect, no asking to loosen a rule or the sandbox. The removed Bot line about permission cards is covered by ASK_CORE's "or ask to loosen a rule", which every crew kind reads. Trust: the Round-0 gate is now skipped on text markers, but anyone who can type to a conductor could already skip it with "go ahead", and tool approvals are unchanged; the RFC records and accepts this risk. L

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit ca60f6df08 · 986 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 15, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 15, 2026
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 15, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
Crew asked the owner too often when a fix or a clear recommendation
existed. The ask cases were stated about nine times in different words,
several lines pulled toward stop, ask or hand-over, and the lesson
headers said lessons "override default behavior".

One text now says when to stop for a person. ASK_CORE in
context_assembly/output_contract.py states reroute first (a refused push
to a protected branch goes to a feature branch and a pull request), the
five ask cases (a)-(e) once, what is not an ask (own time or round caps,
reruns inside an approved count, rerunning runs the agent's own bug
voided, a ruling already made, a done report even when the next step is
the person's) and the safety holds (another spelling of a blocked effect
is the same block; the reroute path must not hit (a)-(e) itself; no
bypassing an approval or review; no asking to loosen a rule, sandbox or
approval mode). A done report carries no [OPTIONS:], and that outranks
the generic [OPTIONS:] rule. CONDUCTOR_ASK_TAIL makes a worker's ask a
claim the conductor checks; WORKER_ASK_TAIL makes a worker try an
allowed path before blocked or question.

Every CRITICAL RULES variant carries the core, and the four crew kinds
carry it again at agent rank: the Bot conductor through a new append in
agent_spec.py, the Bot worker in MATE_WORKER_PROMPT, the Conductor-mode
lead and conductor through the spec_prompts alias, and kirocrew-worker
in worker_prompt().

Every other ask list (work_report schema, goal-conductor skill,
worker-debate guide, Bot conductor and worker pieces, prompt.md, the
ask_question rail) points at "(a)-(e)". The third empty round and a spent
debate budget are the conductor's own decision. The policy deny notice
and the dashboard refusal recovery prompt share one reroute line
(deny_notice.POLICY_REROUTE_TEXT) instead of "say so and stop". The
lesson headers say a lesson that forbids an action still binds and one
that says to wait or ask adds no ask case.

The design record is docs/request-for-change/rfc-reroute-first-ask-policy.md,
shipped in the same change at the repository owner's request.

Goldens re-pinned: context composition, memory v1 session-context
extents, refactor contracts (conductor, team lead and worker prompts)
and spec bytes (conductor, ledger conductor, team lead, worker and mate
worker specs). test_ask_core_guidance.py pins the core at agent rank for
all four kinds, the single case list, the rerouting refusal prompt, and
the not-an-ask phrases in every kind's prompt.

Part of #37606
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Nov 15, 2026
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@bolichen97
bolichen97 merged commit 88dc33c into main Nov 15, 2026
98 of 99 checks passed
@bolichen97
bolichen97 deleted the prompt/guidance-v2 branch November 15, 2026 20:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

This merged while my review of ca60f6d was still running, so here is the one finding as a follow-up item rather than a change request.

builtin_skills/goal-conductor/references/worker-debate.md:276: line 268 now runs "The human's ruling" only when a debate is stuck on an ask case (a)-(e), and line 276 replaced "ask back once; never guess" with "pick the likeliest reading, state it, apply it". So when a debate is stuck on (c), for example deleting another contributor's branch, and the owner's reply is unclear, the conductor applies its own guess as the ruling and does not ask again. That goes against this PR's Not-a-goal ("the five cases are still asked"), RFC section 6 ("never defaulted") and the SKILL.md needs-human checklist ("do not pick a default for it"). Restoring main's sentence ("If it is unclear which objection it rules on, or what it wants, ask back once; never guess.") fixes it, since this step now only runs for (a)-(e).

Also worth the same follow-up: config/prompt.md:95 now says "Never choose a driver or write its arguments from memory" and then "work without it", which contradict each other, and that line reaches every session, not only crew agents.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants