feat(planning): route by size and fog, with a mid-interview check and a ship-it exit

[kyle-sexton]

Requested by Kyle · project thread

Closes #6729

Summary

Before: the interview already skipped a quick-to-review, cheap-to-retry diff and had a soft "ballooning frontier" cue toward /planning:wayfind. It had no explicit check partway through, no way to say "this is small, ship it", and no statement of what the wayfind handoff carries.

After: the interview has a "Routing by size and fog" section that points at a new context/routing.md. At every round boundary it checks whether the work is bigger than it looked: the context-guard zone worsened, or two rounds running opened more questions than they closed. On a trigger it recommends /planning:wayfind chart, carrying over the ledger, constraints, intake disclosure and shorthand glossary. At any boundary the operator can say "this is small, ship it", and the model can propose it.

Fix

• interview/context/routing.md (new): the entry gate and its reason, the bigger-than-thought check and its two triggers, the handoff contents, and the ship-it exit. The zone trigger reads context-guard's report and writes no threshold, since the zones belong to context-guard. interview/SKILL.md keeps a ## Routing by size and fog section with a one-paragraph pointer, outside every digest-pinned section.
• Handoff persistence: the ledger template (interview/templates/checklist.md) gains a ## Starting point section. The handoff writes the intake disclosure there before handing off, so a /clear between the two skills does not lose it. Wayfind chart step 1 seeds its Notes from the ledger's constraint ledger, ## Starting point line and shorthand glossary.
• Ship-it states which gates it keeps. A model-proposed ship-it waits for the operator's yes. On that yes:
  • open rows move to deferred, with the reply as resolution;
  • the assumption sweep is skipped;
  • the Step 3 confirmation gate still runs, because the yes drops questions, not the restatement;
  • deferred rows go to the Brief's ### Deferred questions tagged arbiter: USER-RESERVED;
  • the Step 4 --brief cross-check must exit 0;
  • the work hands off to /implementation:implement.
• Fragment for planning (minor).

Already in place, so unchanged: the "tiny, reviewable, cheap-to-retry diff skips the interview" gate and "What this skill does NOT do" text; wayfind's new-effort gate (a cold start is told to interview first); wayfind seeding from the ledger.

Defaults picked:

• The routing text lives in a context/ spoke. interview/SKILL.md was at the 500-line hard cap, and interview-defenses.test.sh pins the digests of the Action Router, Stance and "does NOT do" sections; recomputing a digest is attended-only. To fit the pointer, the session-config paragraph was unwrapped onto one line, with its wording unchanged.
• The "two rounds running" bar for the branch trigger is my choice; the issue says only "more branches opening than closing".
• Ship-it skips the assumption sweep, because the sweep exists to find more questions and the operator just declined them. Deferred rows take USER-RESERVED because the handoff skips /planning:plan, so a /planning:plan arbiter would never run.

Left for Kyle (needs an attended digest change): the Stance section (interview/SKILL.md "Question budget", about line 111) still says a single round that opens more branches than it closes is the wayfind signal. Its "Interview outgrew one session" bullet in the loop section says the same. context/routing.md treats one such round as noise and two running as the trigger. Aligning the pinned Stance text means recomputing its digest in interview-defenses.test.sh, which an unattended run must not do.

Ready-flip review (fresh-context, on the merged head): fixed in a010901 — ship-it now hands off by session kind (implement, /planning:design for design-significant work, general summary, scope return); the zone trigger needs a zone worse than at entry and is not re-raised after a decline until it escalates; the ledger's ## Starting point line is a placeholder so no example reaches wayfind; deferred USER-RESERVED rows are stated as dropped by the user; "operator" made "user". Left open for Kyle:

• Decided by Kyle (option a), fixed in 4c550bb: a worsened context zone with no fog recommends /session-flow:handoff; /planning:wayfind chart is recommended only on the fog trigger (two rounds running with more branches opened than closed), keeping wayfind's too-big AND foggy stop rule intact.
• interview/SKILL.md "Sweep for assumptions" skip list does not name the ship-it exit (routing.md and the ledger checklist do); the file sits at 499 of 500 lines.
• No eval cases yet for ship-it or the bigger-than-you-thought trigger: test(planning): eval cases for the interview's ship-it exit and bigger-than-you-thought trigger #7365.

Bot review round fixed in 2548d6d: the branch trigger counts branches the answers exposed (register rows appear only when asked); the ship-it handoff lists the deferred rows; the ledger checklist records the ship-it sweep skip.

Verification

At the ready-flip head (main merged): check-affected.sh --tests 7 passed, 2 skipped; interview-defenses.test.sh 172 pass; check-skill.sh plugins/planning/skills 12 passed; cross-plugin drift and shared-copies checks clean.

At head c5c4bf3:

• plugins/skill-quality/scripts/check-skill.sh plugins/planning/skills: 12 passed, 0 failed. Interview passes with 0 errors; its SKILL.md is 497 lines, and 499 when merged with current main.
• scripts/affected-tests.sh --base origin/main --run: all 5 selected suites pass, including interview-defenses.test.sh (172 pass, 0 fail) and check-open-questions.test.sh.
• node_modules/.bin/markdownlint-cli2 on the changed files and the new spoke: 0 issues.
• scripts/check-changelog-fragments.sh --check and --check-required origin/main: valid. scripts/check-changelog-parity.sh --check, --check-bump origin/main and --check-preserved origin/main: pass.
• git merge-tree against current main, which now includes fix(planning): word interview questions so yes accepts the recommendation #7036: clean.
• Not run: interview/wayfind evals.

Related

• feat(planning): every /planning:interview recommendation shows its evidence, not bare judgment #6728 (every interview recommendation shows its evidence), listed in the issue.
• fix(planning): word interview questions so yes accepts the recommendation #7036 (merged) also edited the interview skill.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L8KdG7fWg2YrErVYWtohmR

---

Generated by Claude Code

---

Generated by Claude Code

[kyle-sexton]

ci-status is red because this PR is a draft, not because of the change. On a draft every lint and test lane skips (lint-repo, test-bash, test-node, test-python, check-skills, check-plugins), and the aggregate counts a skip as not passing. See .github/workflows/pr-require-checks.yml:507-513.

The lanes run once the PR is marked ready. That flip waits for Kyle, because it also starts the review lanes. Until then, the local runs listed under Verification in the PR body are the signal.

---

Generated by Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-13T03:33:50.120093Z	9dca661	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 1m 19s —— View job

---

Security review complete

• Gather context (PR diff, changed files)
• Check skip gate (security-relevant surface, instruction-surface deletions)
• Review diff for logic/trust-boundary/injection issues
• Check instruction-surface deletions against protected classes
• Report findings or no-issues result

No security issues found.

This PR only touches planning-skill prose (interview/SKILL.md, the new interview/context/routing.md, interview/templates/checklist.md, wayfind/SKILL.md) and a changelog fragment — no executable code, no secret handling, no auth/access-control logic, and no injection surface.

Checked specifically for instruction-surface deletions (the instruction exception register classes: irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority):

• interview/SKILL.md: the session-config paragraph is only re-wrapped onto one line (unchanged wording), and a new ## Routing by size and fog pointer section is added. Nothing removed or softened.
• wayfind/SKILL.md: purely additive — extends what rides into Notes; the existing no-fog bail-out gate is untouched.
• The new ship-it exit in context/routing.md adds a path that still keeps the Step 3 confirmation gate and the Step 4 --brief cross-check (per the PR body); it doesn't remove any existing control, so it's an addition, not a deletion/narrowing of a standing instruction.

No findings to post inline.

claude-lane-summary: lane=claude-security-review sha=9dca6612e8adc53ec5cf8c1f71eeaa9467aca5d6 run=38341966346

[claude]

Claude finished @kyle-sexton's task in 6m 37s —— View job

---

Review complete

• Gather context (PR diff, changed files, CLAUDE.md/REVIEW.md)
• Review interview/context/routing.md (new)
• Review interview/SKILL.md changes
• Review templates/checklist.md changes
• Review wayfind/SKILL.md changes
• Check changelog fragment
• Post findings

Scope note: This PR's body already discloses several known gaps (the Stance-section "one round vs. two rounds" mismatch, wayfind's no-fog bail-out vs. the zone-only trigger, the assumption-sweep skip list not naming ship-it). I didn't re-report those — they're not new information. I focused on what the author's own analysis hadn't covered.

Finding (1 inline comment)

plugins/planning/skills/interview/context/routing.md:68-71 — Ship-it tags every deferred row arbiter: USER-RESERVED with the stated reason that the handoff skips /planning:plan. But USER-RESERVED's only documented resolution mechanism anywhere else in this plugin is /planning:plan's approval gate (context/loop.md:421,429; enforced by audit-answers/SKILL.md:60,95, which explicitly refuses to touch a USER-RESERVED row because it "re-confirms at the /planning:plan approval gate"). Ship-it's handoff (step 4) skips /planning:plan for every destination — implementation, design, general summary, or scope return — so the one place that would ever re-surface these rows to the user never runs. /implementation:implement has no reference to ### Deferred questions or USER-RESERVED at all; its nearest hook is a generic "put to the user every decision that is still theirs" closing step, not the explicit contract this tag relies on elsewhere. Net effect: a user's declined questions get a tag whose entire meaning, everywhere else in the codebase, is "will be asked again" — and then usually aren't. Full repro and fix directions in the inline comment.

Everything else checked out: the register-gate interaction (deferred rows pass check-open-questions.sh cleanly), the digest-pinned sections in interview-defenses.test.sh (confirmed the new ## Routing by size and fog section and the unwrapped session-config paragraph both sit outside every pin_section/pin_frontmatter boundary), the ## Starting point placeholder mechanics, and the scope/general/design handoff variants in the ship-it list.

Not independently verified: I was not able to execute the shell test suites (interview-defenses.test.sh, check-skill.sh) in this sandbox — those runs blocked on tool approval. The PR body's reported local-run results (172 pass, markdownlint clean, changelog checks pass) are author-claimed and unverified by me; I relied on static reading of the scripts and pinned-section boundaries instead.

claude-lane-summary: lane=claude-review sha=9dca6612e8adc53ec5cf8c1f71eeaa9467aca5d6 run=38341966342

[github-actions]

claude-security-review has reviewed this pull request through 4c550bb; a later push is reviewed from there.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9dca6612e8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

claude-review has reviewed this pull request through 4c550bb; a later push is reviewed from there.

[claude]

Claude finished @kyle-sexton's task in 52s —— View job

---

Security review complete

• Gather context (incremental diff since 9dca6612e8)
• Run /review:security-review procedure on the incremental diff
• Report findings

No security issues found.

Scope: incremental — only the diff since 9dca6612e8adc53ec5cf8c1f71eeaa9467aca5d6 (full history at this lane already covered in that earlier review). Two files changed, both prose-only planning-skill content, no executable code, no secret handling, no auth/access-control logic, no injection surface:

• interview/context/routing.md — tightens the "more branches opened than closed" trigger to count the recomputed frontier instead of register rows alone, and (L78-L83) adds that the handoff message lists each deferred Q<N> row since /planning:plan's approval gate doesn't run on that path. Both are additions that tighten existing checks, not removals.
• interview/templates/checklist.md — adds a new skip-criteria line documenting the ship-it exception for the assumption sweep; purely additive.

Instruction-surface deletion check: neither hunk deletes, narrows, or softens a standing instruction — both add new constraints/specificity on top of existing gates (the Step 3 confirmation gate and Step 4 --brief cross-check are unchanged by this diff). Checked against docs/conventions/instruction-exception-register/README.md, which is present in this checkout; no protected-class match.

No findings to post inline.

claude-lane-summary: lane=claude-security-review sha=2548d6dbcdf77c567e282b013d8ef20cb8d96014 run=38342698080
· branch feat/6729-route-by-diff-size-and-fog

[claude]

Claude finished @kyle-sexton's task in 2m 43s —— View job

---

Review complete

• Gather context (incremental diff, PR body, prior review threads)
• Review interview/context/routing.md changes (branch-counting fix, ship-it handoff deferred-row listing)
• Review interview/templates/checklist.md changes (ship-it sweep-skip addition)
• Post findings

Scope: incremental, last reviewed at 9dca661. I read .claude-lane/incremental.diff and reviewed only the two changed files it names.

This diff is a targeted set of fixes responding to three earlier review comments:

1. routing.md:26-30 — the "more branches opened than closed" trigger now counts branches this round's answers expose (the next round's candidate questions) against rows moved to terminal status, instead of counting only existing register rows. This matches Codex's point that a new branch has no register row until it's asked, so counting register rows alone missed a round that answered everything but opened a wide new frontier.
2. routing.md:78-83 — the handoff step now explicitly lists each deferred row (Q<N> id + question) in the handoff message itself, since /planning:plan's approval gate (the only place USER-RESERVED is documented to resurface elsewhere in this plugin) never runs on this path. This directly addresses the earlier finding that ship-it's deferred rows had no resurfacing mechanism — it doesn't invent new downstream machinery, but it does make sure the user is told explicitly, by id and question, at the moment of handoff, not just buried in a register recap.
3. checklist.md:12 and checklist.md:80 — the assumption-sweep's "once frontier is empty" trigger is now explicitly exempted for a ship-it exit, in both the step description and the skip-criteria list, with a pointer back to routing.md. Without this, a ship-it that moves every open row to deferred would leave the frontier looking empty and (per the pre-existing rule) trigger a sweep that reopens exactly the questions the user just declined — the bug Codex flagged.

I checked each fix against the surrounding unchanged text it interacts with (the Step 2/3 register-recap restatement, the scope/general/Brief deferred-row listing in the untouched lines 70-77, the skip-criteria list's other bullets) and didn't find a new inconsistency or logic gap introduced by this diff.

No findings to report.

claude-lane-summary: lane=claude-review sha=2548d6dbcdf77c567e282b013d8ef20cb8d96014 run=38342698064

[claude]

Claude finished @kyle-sexton's task in 53s —— View job

---

Security review complete

• Gather context (incremental diff since 2548d6dbcd, scoped to interview/SKILL.md, interview/context/routing.md, interview/templates/checklist.md)
• Run /review:security-review procedure on the incremental diff
• Check instruction-surface deletions against protected classes
• Report findings

No security issues found.

Scope: incremental, three files, all prose-only planning-skill content — no executable code, no secret handling, no auth/access-control logic, no injection surface:

• interview/SKILL.md:450 — the routing pointer now names two destinations (/planning:wayfind chart on fog, /session-flow:handoff on context size alone) instead of one.
• interview/context/routing.md:18-40 — splits the single "either trigger → wayfind" rule into two: the fog trigger (branches opening faster than closing) keeps recommending wayfind and is now stated as the fog evidence wayfind's own too-big-AND-foggy stop rule requires; the zone-only trigger now recommends the interview's own /session-flow:handoff instead. This resolves the product-choice thread left open in the PR body/review comments (option a).
• interview/templates/checklist.md:15 — adds a checklist line mirroring the same split; purely additive.

Instruction-surface deletion check: this redirects a routing recommendation between two downstream skills; it doesn't delete, narrow, or soften any standing instruction. The "never switch on your own" rule (model only recommends, user decides) is preserved verbatim in both the old and new text, so there's no agent-authority widening, and nothing here touches irreversible-action, secret-handling, data-integrity, external-publication, or legal-compliance either. Checked against docs/conventions/instruction-exception-register/README.md, present in this checkout; no protected-class match.

No findings to post inline.
· branch feat/6729-route-by-diff-size-and-fog

claude-lane-summary: lane=claude-security-review sha=4c550bbda42c1c39f6aecc8d916fee0960074f1c run=38346331131

[claude]

Claude finished @kyle-sexton's task in 5m 4s —— View job

---

Review complete

• Gather context (incremental diff, CLAUDE.md/AGENTS.md, custom review instructions)
• Invoke /review:code-review procedure on the incremental diff
• Review interview/SKILL.md changes
• Review interview/context/routing.md changes
• Review interview/templates/checklist.md changes
• Post findings

Scope: incremental, last reviewed at 2548d6dbcd. Read .claude-lane/incremental.diff; reviewed only the three files it names, cross-checked against the full (unchanged) text of wayfind/SKILL.md's chart-step fog test and interview/SKILL.md Step 5/line 420 for consistency.

This diff implements the owner's resolution (option a, per the 04:24:58 review-comment thread) to the zone-vs-fog conflict Codex and kyle-sexton raised earlier: a context-zone-only trigger now recommends the interview's own /session-flow:handoff instead of /planning:wayfind chart, and wayfind is recommended only when the fog trigger (two rounds running with more branches opened than closed) holds — alone or together with a worsened zone.

I checked this against the pieces it has to stay consistent with:

• wayfind/SKILL.md's no-fog bail-out (chart step 1, unchanged in this increment): requires too-big AND foggy both; a zone-only recommendation reaching wayfind would have bounced straight back out. With this fix, wayfind is only ever recommended once the fog trigger is live, so the bail-out condition it depends on no longer fires on this path.
• interview/SKILL.md line 420 / Step 5 (line 438, unchanged): "never on your own estimate of remaining context" governs self-polling, not consuming context-guard's surfaced zone report; the new zone-alone route still only reads that external report, so no conflict there. Step 5's own wording ("too big AND still foggy → wayfind") already matches the same dual-condition rule this diff encodes in routing.md.
• checklist.md's new line 15 restates the same two-route split (wayfind on fog, /session-flow:handoff on zone-alone, never wayfind on zone-alone) consistently with routing.md's wording.
• Digest pins: the edited text in SKILL.md stays inside the already-unpinned ## Routing by size and fog section (confirmed against interview-defenses.test.sh's pin_section/pin_frontmatter call list), so this diff doesn't touch pinned content.

I didn't find a defect in this increment — it's a narrowly-targeted, internally consistent fix for exactly the conflict it says it fixes, and I couldn't construct a scenario where the new routing produces a wrong or contradictory recommendation.

Not independently verified: sandbox tool-approval blocked running interview-defenses.test.sh / check-skill.sh here; relied on static reading of the pin boundaries and script logic instead of executing them.

No findings to report.
· branch feat/6729-route-by-diff-size-and-fog

claude-lane-summary: lane=claude-review sha=4c550bbda42c1c39f6aecc8d916fee0960074f1c run=38346331130