From 6e26b03f0c5abcac2bf4cb82f5ac1808cded4b13 Mon Sep 17 00:00:00 2001 From: Lee Overy Date: Sun, 26 Jul 2026 22:27:20 +0100 Subject: [PATCH] docs(conventions): a step whose reference routes every exit still signposts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Discovery's Step 5 loads confirm-trigger and ends there. Every other step in that skill says where it goes next, so a reader arriving at the blank line has one signal left — the next heading — and takes it. A walk did exactly that: read confirm-trigger's route to Step 7, talked itself into Step 6 because the file numbers it earlier, then caught itself. The convention already anticipates most of this. A reference whose paths need different backbone steps overrides its caller, because "the caller's single Proceed to line can only go one place". That wording assumes a line exists to be overridden, and for final-review.md it does — three of its eight exits return bare and the caller's footer is what serves them. confirm-trigger has no such exit. Every path routes, so any footer would name a step that never runs, and the step was left with nothing at all. That is the shape with no documented form, and it now has one: the footer defers rather than naming a step. The rule also states what a footer governs — the bare returns only, never the branches the reference routed itself — which was true already and unwritten, and is what lets a reader over-apply a footer to all eight of final-review's exits when it serves three. A step is never left with no footer. Silence reads as the end of the step, and the heading below becomes the fall-through by default. Behaviour is unchanged: the routing was always complete for anyone who read the reference. This makes it complete for someone who has just finished reading it. Co-Authored-By: Claude Opus 5 --- CONVENTIONS.md | 1 + skills/workflow-discovery/SKILL.md | 2 ++ 2 files changed, 3 insertions(+) diff --git a/CONVENTIONS.md b/CONVENTIONS.md index 74b29957e..ae27176c6 100644 --- a/CONVENTIONS.md +++ b/CONVENTIONS.md @@ -692,6 +692,7 @@ Rules: - `→ On return, proceed to` is the footer after a Load directive, separated by a blank line — the loaded reference runs to completion (its STOP gates and loops included) before the proceed applies. A bare `→ Proceed to` here reads as the immediate next action and overshoots the reference - When a `**STOP.**` gate or a bold conditional sits between the Load directive and the routing line, the routing is keyed to the user's response or the branch, not the return — those use the bare `→ Proceed to` - The final step has no routing footer (it's terminal) +- A footer governs only the reference's bare `→ Return to caller.` exits — never the branches the reference routes itself (see Navigation & Return Patterns → backbone escape). Where every exit routes to a named step, no branch is left for a footer to serve and naming one would name a step that never runs: the footer instead defers, `→ On return, proceed as the reference directed.` A step is never left with no footer at all — silence reads as the end of the step, and the next heading gets treated as the fall-through - Within reference files routing to other reference files, use `→` before Load (it IS a routing instruction in that context) **Parameter passing**: When a shared reference needs context from the caller, append `with` followed by named assignments. String literals and variable values are both backtick-wrapped; variables use curly brace placeholders: diff --git a/skills/workflow-discovery/SKILL.md b/skills/workflow-discovery/SKILL.md index dbf61361a..7325fb5e4 100644 --- a/skills/workflow-discovery/SKILL.md +++ b/skills/workflow-discovery/SKILL.md @@ -150,6 +150,8 @@ Load **[shape-and-confirm.md](references/shape-and-confirm.md)** and follow its Load **[confirm-trigger.md](references/confirm-trigger.md)** and follow its instructions as written. +→ On return, proceed as the reference directed. + --- ## Step 6: Resume Detection