Repository navigation
refactor(goal-conductor): move rare paths to references/, one pointer each - #37832
Conversation
… each goal-conductor/SKILL.md (903 -> 808 lines) keeps what every turn needs and points, at the step where each path starts, to a file read only on that path: - references/dashboard-contract.md: board page fields (needs_you, asks, panel_publish) - references/acceptance-kinds.md: each kind's object and verdicts, the draft refusal - references/manual-dispatch.md: the four-step dispatch without work_dispatch, the message refusal, why bind comes before the seed - references/accept-eval-fallback.md: handing the evaluator a filtered document, the quoted-heredoc shell fallback, resolving the skill dir - references/rare-cases.md: pending_overdue, settling a human_approval item - references/ledger-fields.md: the read flags and the accept_eval answer fields - references/worker-debate.md gains "When to offer a debate" The skill keeps one line of each safety rule it moves (never an unfiltered accept_batch, a quoted heredoc only, never invent an answer, always set repo, no "run this command" kind). Tests that pinned moved text now read the file it lives in; a new parity test fails when the skill names a reference it does not ship.
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns. The refactor uses the same Notes
[DESIGN-REVIEWED] 3c277ce Description read[DESCRIPTION-READ] 7cbb6e0f12f0347f8bccae9ed6d465c23aafa107269ce56c0d38f0d0efdec0ba 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Text moves only; no default, tool or schema changes. One moved sentence now exists twice. Notes
What this change shipsInventory (8 items) — 7 justifiedIntent: make each conductor turn load less of the skill by moving rarely used paths into files read only when needed. This is a refactor (an ADDITION of files, no change in behaviour).
[FIRST-PRINCIPLES-REVIEWED] 3c277ce Description read[DESCRIPTION-READ] 7fdcecf6a633c52a27d2104242a304fbc5da652fe78b0d6e6783e03c6f5f73ec That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: A person should decideWhy: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, but it changes 436 lines, more than the 400 it may approve on its own. This PR only moves text out of the goal-conductor skill. Rarely used paths go into reference files under references/, and SKILL.md keeps a pointer at each place a conductor needs one. Each moved safety rule still has a line in SKILL.md pointing to its new file. All three agents that read the skill (kirocrew-conductor, kirocrew-mate-conductor and kirocrew-team-lead) have the skill mapped and fs_read, and worker-debate.md and remote-dispatch.md are already read the same way. I found nothing else in src/ that cuts sections out of SKILL.md or quotes the moved text, apart from the tests the PR updates. Those tests now read the new files and check the pointers, a new test fails if a named reference file doesn't ship, and CI passed. Only minor wording drift and one repeated sentence remain. 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 |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approved. On this head the review checked these points. The moved blocks match the base SKILL.md text, apart from headings and punctuation. All three conductor agents still read goal-conductor references through fs_read, and setup.cfg ships the new files. No runtime code changed. Every pin on moved text was re-pointed to its new file, and the heredoc safety test now scans both pages. PR Readiness is green.
Done well: each pointer names both the file and when to read it. The new test_every_reference_the_goal_conductor_skill_names_exists also fails on any dangling reference that a later move leaves behind.
Optional:
- The rule to resolve
<this skill's dir>from where SKILL.md was loaded, and never from the default skills root, now lives only in references/accept-eval-fallback.md. Every pointer needs that rule first. Consider keeping one line of it in SKILL.md before the first pointer, near line 83. - references/manual-dispatch.md:25-31 brings back the bind-before-seed rationale that the shared prompt rule already holds. accept-eval-fallback.md:48-49 repeats the "Evaluate every done item in ONE call" sentence that SKILL.md keeps. You could delete both to keep one copy of each rule.
- The new existence test checks only one direction. Nothing pins the pointers to dashboard-contract.md, ledger-fields.md or acceptance-kinds.md, so a deleted pointer would leave its reference unreachable while every test stays green.
Problem / Motivation
Goal: The goal-conductor skill loads only what every turn needs; each rare path is read from its own file at the step where it starts.
Every conductor reads all of
goal-conductor/SKILL.mdon every goal, including paths most goals never take: dispatching by hand, the shell fallback for the evaluator, an overduependingbar, settling ahuman_approvalitem, board-page field schemas and per-kind acceptance details (auditskill-audit.mdsection 1c, PR5 in section 7).Why it matters
Text a turn does not use still costs tokens on every load and pushes the per-turn rules further apart. The skill is read by both kinds of conductor (conductor mode's
kirocrew-conductorand a Bot'skirocrew-mate-conductor), so both pay it.Not a goal
_LEDGER_CONDUCTOR_RULES(feat(conductor): share the long-task and team rules with the Bot and root the parity test at conductor mode's agent #37725, refactor(goal-conductor): one copy of each rule, pointers to the shared conductor rules #37778) and stay there.references/remote-dispatch.mdsince refactor(goal-conductor): show remote dispatch only while its preview is on #37612).What changed (motivation → approach → change)
Rare path in the always-loaded file → one file per path under
references/, the same mechanismworker-debate.mdandremote-dispatch.mdalready use → the skill keeps one pointer line at the step where the path starts, saying when to read it.SKILL.md: 903 → 808 lines. The audit's ~230 included the 88 remote-dispatch lines #37612 already moved and the copies #37778 removed.
references/dashboard-contract.mdkirocrew-conductorpage fields,goal-boardasksneeds_you/asksor callingpanel_publishreferences/acceptance-kinds.mdreporeason, draftrefusedreferences/manual-dispatch.mdmessage_needs_send_approval, why bind before seedwork_dispatch, or re-binding a sessionreferences/accept-eval-fallback.mdaccept_batch, quoted-heredoc shell call, skill-dir resolutionreferences/rare-cases.mdpending_overduebudget,human_approvalasking, withdrawn cardpending_overdueorhuman_approvalitemreferences/ledger-fields.mdorphaned/stale/report_undelivered,accept_evalanswer fieldsreferences/worker-debate.md(new section)Safety rules (
skill-audit.mdsection 6)S1-S41 checked by anchor phrase across SKILL.md,
references/and the shared rules: none lost. Moved this PR (old → new), each with a line left in SKILL.md:manual-dispatch.mdmessage_needs_send_approvalmanual-dispatch.mdmanual-dispatch.mdwork_dispatchdoes itaccept_batchaccept-eval-fallback.mdaccept_batch"accept-eval-fallback.mdprintforecho", read the file firstaccept-eval-fallback.mdhuman_approvalanswer; withdrawn cardrare-cases.mdStay in SKILL.md unchanged: S4 (no "run this command" kind), S5 (always set
repo), S10 (seed is the whole contract), S23, S27, S29-S39.Both conductors read references the same way: their specs map the
goal-conductorskill and mountfs_read.Backwards compatibility
Compatible: text moves only; no config key, schema, API or tool change.
Removes nothing: every moved paragraph is copied verbatim into a shipped file the skill names at the step where it applies.
Tests
test_every_reference_the_goal_conductor_skill_names_exists(test/test_mate_conductor_parity.py): fails when the skill or a reference names a file underreferences/that does not ship.test_conductor_agent.py(batch filter, heredoc, no-folder, wake never blocks on a card, draft verdict ratchet),test_seed_after_create_rule.py,test_work_ledger_pending_budget.py,test_worker_grill_preview.py.references/(285 files) before the pin fixes: 8 failed (the pins above), 12492 passed. After the fixes and the rebase ontobffb0b6eda, the 11 affected files: 248 passed.Proof: not provable -- other: text moved between skill files; the new existence test and the updated pins guard the move.
Manual verification
N/A — every pointer's target is checked to exist by the new test.
Related Issues
agent.crew_mode_agentto it.Checklist
Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.