Skip to content

refactor(prose): skill-handoff convergence — one grammar, bridge plan integrity#511

Merged
leeovery merged 7 commits into
mainfrom
feat/handoff-convergence
Jul 23, 2026
Merged

refactor(prose): skill-handoff convergence — one grammar, bridge plan integrity#511
leeovery merged 7 commits into
mainfrom
feat/handoff-convergence

Conversation

@leeovery

Copy link
Copy Markdown
Owner

Standalone PR off main (independent of the batching stack). Fixes the Portal stall (conclude-discovery printing its bridge payload and stopping) as one instance of a family, per the plan agreed with Lee.

The mechanisms, made explicit (CONVENTIONS: "Loading, Invoking, and the Bridge")

  • Loading a reference reads into context; variables resolve because prose stated them first.
  • Invoking a skill is a Skill tool call at a boundary, enriching the running context — nothing is cleared. Canonical form: imperative before the payload fence ("Invoke the workflow-x skill (Skill tool) with the next fenced block as its arguments…"), fence as pure payload, terminal after — no STOP, no after-fence instruction (too late), no in-fence instruction (gets printed, not executed).
  • The bridge owns the only context-clear, phase→phase via plan mode.

The sweep (34 sites, 24 files)

  • In-fence Invoke the workflow-X skill. payload tails removed everywhere (conclude-* ×9 incl. review-actions ×5, entry invoke-skill ×8 skills, spec-entry handoffs ×6).
  • conclude-discovery gains the missing imperative and loses the terminal STOP that licensed the stall.
  • Entry files' imperatives move from after the fence to before it; payload-construction notes move above too (command-prelude).

Bridge plan integrity (the ~10% contamination)

All 8 plan-template sites: "verbatim — this is the complete plan", plan mode's investigate/verify/design job explicitly disclaimed, nothing learned this session added (the next context is designed to start empty), ## User instructions as the sole sanctioned addition — and ## How to proceed now addresses the human plainly: approve with "Clear context and continue" (the option migration 034 keeps enabled).

Test plan

  • Lint check 14 (buried invocation imperative) + fixtures; corpus clean.
  • npm test 1560/1560 · conventions lint 29/29 · typecheck clean.

🤖 Generated with Claude Code

leeovery and others added 7 commits July 22, 2026 22:20
… integrity

The Portal stall class, fixed as a family (34 sites, 24 files):

- CONVENTIONS gains "Loading, Invoking, and the Bridge": reference
  loads read into context (variables resolve from prose already
  stated); skill invocations are Skill tool calls at boundaries that
  enrich the running context — nothing is cleared; only the bridge
  clears, phase→phase, via plan mode. Canonical invocation form:
  imperative BEFORE the payload fence naming skill + mechanism, fence
  as pure arguments, terminal after (no STOP).
- Every handoff site converged: the in-fence "Invoke the workflow-X
  skill." payload tails removed everywhere; conclude-discovery gains
  the missing imperative and loses the STOP that licensed the Portal
  stall; entry invoke-skill files move their imperative from after the
  fence to before it (command-prelude); payload-construction notes
  move above the fence; spec-entry handoff files aligned.
- Bridge plan integrity: "write the following content" is now
  "verbatim — this is the complete plan" with the anti-enrichment
  contract (plan mode's investigate/design job explicitly does not
  apply; the next context is designed to start empty) and the one
  sanctioned addition (## User instructions, after the template). The
  How-to-proceed line now addresses the human explicitly: approve
  with "Clear context and continue" (kept enabled by migration 034).
- Lint check 14: a line inside any fence starting "Invoke the
  workflow-" fails — the buried-imperative class is extinct.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
… placeholders resolve first

Review catch (Lee): the templates carry @if/@endif directives and
placeholders; a literal "verbatim" would write the syntax into the
plan. The instruction now says resolve, then output the result
verbatim.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…s contract

Review catch (Lee): the imperative said "the next fenced block is its
arguments" but the payload was a prose-shaped context block the bridge
read by inference. The shape is uniform across all twelve call sites —
work_unit, completed_phase, optional next_phase — so the contract is
now literal: the bridge SKILL declares its Skill-tool args, and every
call site passes exactly that line. (The Portal transcript shows the
model already improvising this exact form when left to infer.)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The bridge declares $0/$1/$2 (work_unit, completed_phase, optional
next_phase) exactly as the entry skills and discovery do — 0-indexed
per code.claude.com/docs/en/skills — and every call site invokes with
inline positional arguments instead of a key=value fence no receiver
parses. Dangling imperative and a stray terminal STOP tidied in
conclude-discussion.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…ngs aligned

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…args get whole-command branches

Review feedback (Lee): show the actual command — /workflow-bridge
{work_unit} {phase} — like everywhere else, and when an argument is
conditional, write the complete command per branch. Conventions
updated: positional-arg skills use the slash literal; context-block
handoffs keep the pre-fence imperative.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…literal command

Review catch (Lee): the branch-pair form invented an "If not"
conditional and split the command. The in-repo precedent
(route-to-discovery) resolves optional values in prose — absence as
the literal none — then shows one literal invocation. The bridge $2
now declares the none convention; conclude-discovery and the
conventions passage follow it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@leeovery
leeovery merged commit ccda8e7 into main Jul 23, 2026
@leeovery
leeovery deleted the feat/handoff-convergence branch July 23, 2026 11:00
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
…515)

* feat(scoping): promotion routes through first-phase choice + bridge

The promote paths predate discovery (2026-03-28 vs 05-31) and were
never revisited: a promoted feature was forced straight into
discussion — no research option — and both promotions started their
first phase inside the still-loaded scoping session. Promotion now
mirrors discovery's endpoint: feature promotions get the
research-vs-discussion choice, and both types hand off through the
bridge's supplied-destination arm for a clean context.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* refactor(scoping): promotion bridge handoff joins the #511 grammar

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
leeovery added a commit that referenced this pull request Jul 23, 2026
* docs(design): batching programme — census, contract, staged plan

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(design): stage 1 log entry; C1 wording matches the shipped grammar

* docs(design): stage 2 log entry + census corrections

* docs(design): stage 3 log entry, census rows ticked

* docs(design): stage 4 log entry + contract C6 (uniform batch grammar)

* docs(design): stage 5 log entry, census rows ticked

* docs(design): stage 6 log entry, shell-cluster row ticked

* docs(design): end-of-stack review round recorded

* docs(design): deep-dive round 2 recorded

* docs(design): system-wide round 3 recorded

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(design): round-3 ambiguity resolutions recorded

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(design): #511 landed, #515 restyled, brief lifecycle hole closed

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* docs(design): round 4 — simulation gate, drift-free contract, tail fixes

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
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.

1 participant