Skip to content

refactor(goal-conductor): move rare paths to references/, one pointer each - #37832

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
refactor/goal-conductor-rare-paths
Nov 16, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
refactor/goal-conductor-rare-paths

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

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.md on every goal, including paths most goals never take: dispatching by hand, the shell fallback for the evaluator, an overdue pending bar, settling a human_approval item, board-page field schemas and per-kind acceptance details (audit skill-audit.md section 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-conductor and a Bot's kirocrew-mate-conductor), so both pay it.

Not a goal

What changed (motivation → approach → change)

Rare path in the always-loaded file → one file per path under references/, the same mechanism worker-debate.md and remote-dispatch.md already 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.

moved to content pointer in SKILL.md (when to read)
references/dashboard-contract.md kirocrew-conductor page fields, goal-board asks before writing needs_you/asks or calling panel_publish
references/acceptance-kinds.md each kind's object and verdicts, repo reason, draft refused before writing a kind not used yet in this goal
references/manual-dispatch.md four-step dispatch, message_needs_send_approval, why bind before seed without work_dispatch, or re-binding a session
references/accept-eval-fallback.md hand-filtered accept_batch, quoted-heredoc shell call, skill-dir resolution before handing the evaluator a document, or any shell call to it
references/rare-cases.md pending_overdue budget, human_approval asking, withdrawn card before acting on a pending_overdue or human_approval item
references/ledger-fields.md compact/full read fields, orphaned/stale/report_undelivered, accept_eval answer fields a flag or field you do not know how to act on
references/worker-debate.md (new section) "When to offer a debate" before offering one

Safety rules (skill-audit.md section 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:

rule old place (SKILL.md) new place line kept in SKILL.md
S12 bind before seed (reason) Dispatch a round manual-dispatch.md "Bind BEFORE you seed … neither visible nor recoverable"
S13 message_needs_send_approval Dispatch a round manual-dispatch.md pointer (manual path only)
S14 acceptance stored verbatim Dispatch step 1 manual-dispatch.md work_dispatch does it
S24 never an unfiltered accept_batch Patrol step 3 accept-eval-fallback.md "Never hand the evaluator an unfiltered accept_batch"
S25 quoted heredoc only Patrol step 3 accept-eval-fallback.md "a quoted heredoc only, never printf or echo", read the file first
S26 resolve skill dir from where it loaded Patrol step 3 accept-eval-fallback.md read before the shell call
S28 never invent a human_approval answer; withdrawn card Patrol step 3 rare-cases.md pointer at the kind's definition and in step 3: "Neither is ever settled by an answer you invent"

Stay 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-conductor skill and mount fs_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

  • New 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 under references/ that does not ship.
  • Pins on moved text now read the file it lives in, and each also asserts the pointer left in SKILL.md: 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.
  • Local, under the test lock: every test file that reads the skill or references/ (285 files) before the pin fixes: 8 failed (the pins above), 12492 passed. After the fixes and the rebase onto bffb0b6eda, 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

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

… 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.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 16, 2026 05:26
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 16, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 3c277ce6620580e8f12f0db2409f86e886805f38 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns. The refactor uses the same references/ mechanism the skill already uses for remote-dispatch.md and worker-debate.md, and a new test checks that every file the skill points to ships.

Notes

  • The shortened acceptance-kinds paragraph in SKILL.md is reworded rather than copied, despite the description's "Moved text is copied verbatim". The full text is in acceptance-kinds.md. Either check that the summary still says what the old text said, or change the description's claim.
  • kirocrew-team-lead also maps goal-conductor (service_agents.py:829). The description's "Both conductors read references" leaves out this third reader; confirm it can read fs_read references too.

[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 .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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 3c277ce6620580e8f12f0db2409f86e886805f38 — 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

Text moves only; no default, tool or schema changes. One moved sentence now exists twice.

Notes

  • Item 4 — oversized: accept-eval-fallback.md ends with "Evaluate every done item in ONE call: a shell fallback call costs one approval prompt.", but SKILL.md:489 still says the same thing ("Evaluate every done item in ONE call — a shell fallback call costs one"). Grepping Evaluate (\*\*)?every \done` item in ONE callgives 2 copies. That works against the "one copy of each rule" goal this PR builds on (#37778). Subtraction: delete the last paragraph ofreferences/accept-eval-fallback.md`.

What this change ships

Inventory (8 items) — 7 justified

Intent: 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).

  1. Board-page field schemas are read from references/dashboard-contract.md only before a board write — justified
  2. Details of each acceptance kind move to references/acceptance-kinds.md, leaving a short list in SKILL.md — justified
  3. The four-step manual dispatch moves to references/manual-dispatch.md — justified
  4. Handing the evaluator a document and the heredoc shell fallback move to references/accept-eval-fallback.md — oversized: one rule now has two copies
  5. The pending_overdue budget and human_approval asking move to references/rare-cases.md — justified
  6. Meanings of ledger flags and fields move to references/ledger-fields.md — justified
  7. The full "when to offer a debate" rules move into worker-debate.md, with a one-line summary kept — justified
  8. A new test fails when the skill names a references/ file that does not ship — justified

[FIRST-PRINCIPLES-REVIEWED] 3c277ce

Description read

[DESCRIPTION-READ] 7fdcecf6a633c52a27d2104242a304fbc5da652fe78b0d6e6783e03c6f5f73ec

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 3c277ce

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

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

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 3c277ce

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

@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 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 3c277ce662 · 436 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 16, 2026 07:26

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@KiroCrewCaptain
KiroCrewCaptain merged commit de2c5da into main Nov 16, 2026
96 of 97 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the refactor/goal-conductor-rare-paths branch November 16, 2026 07:26
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
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.

2 participants