Skip to content

skill: renumber steps to monotonic Stage.N (numbers stop lying about order) - #25

Merged
Gandy2025 merged 1 commit into
mainfrom
refactor/skill-stage-numbering
Jul 7, 2026
Merged

skill: renumber steps to monotonic Stage.N (numbers stop lying about order)#25
Gandy2025 merged 1 commit into
mainfrom
refactor/skill-stage-numbering

Conversation

@Gandy2025

Copy link
Copy Markdown
Contributor

Why

Across successive rewrites the Step N labels drifted out of execution order: Step 1.5 runs after Step 2, Step 9.5 before Step 9, Step 10 before Step 9, and "Step 8" (the Voice register) sits at the top of the file. The numbers actively mislead a reader — and the executing agent — about what runs when. Pure renumbering, zero behavior change.

What

  • Stages stay the ordered spineSTAGE 0–6, unchanged.
  • Every sub-step heading → N.M — Name (number for navigation + descriptive name), monotonic within its stage: 0.1/0.2 · 1.1 (+ 1.1a/b/c) /1.2/1.3/1.4/1.5 · 2.1 · 3.1 · 4.1 · 5.1 · 6.1/6.2.
  • Every inline Step N cross-reference → the matching N.M — a reference can no longer point at a step that executes in a different order. Verified: zero Step N left in the live skill.
  • The Voice register is a load-before-you-write preamble, not a step — its Step 8 label is dropped; referenced by name now, like Operating rules / Shared constants.
  • reference modules: the few SKILL.md Step 2.4/4/7 citations become the content-name style the modules already use (closed id-prefix table / ownership matrix / schema), immune to future renumbering.

Scope

The live skillSKILL.md + references/. Deliberately untouched: docs/REVIEWS.md (historical review log) and docs/example-report*.md (stale sample already tracked for a separate refresh).

Verification

  • grep -roE 'Step [0-9]' over SKILL.md + references/0.
  • 7 STAGE headings intact; 16 N.M sub-headings.
  • Render smoke test still green (touches only prose/headings). Diff +125/−125 (a rename).

🤖 Generated with Claude Code

…about order

The step labels had drifted out of execution order across successive rewrites:
Step 1.5 ran after Step 2, Step 9.5 before Step 9, Step 10 before Step 9, and
"Step 8" (the Voice register) sat at the top of the file — the numbers actively
misled a reader about what runs when. Pure renumbering, no behavior change.

- Stages stay the ordered spine (STAGE 0–6, unchanged).
- Every sub-step heading becomes `N.M — Name` (number + descriptive name),
  monotonic within its stage: 0.1/0.2, 1.1(+1.1a/b/c)/1.2/1.3/1.4/1.5, 2.1,
  3.1, 4.1, 5.1, 6.1/6.2. Navigation by number, self-description by name.
- Every inline "Step N" cross-reference is renumbered to the matching N.M, so
  a reference can no longer point at a step that runs in a different order.
- The Voice register is a load-before-you-write preamble, not a step — its
  "Step 8" label is dropped (it's referenced by name now, like the other
  preambles).
- reference modules: the few "SKILL.md Step 2.4/4/7" citations become the
  content-name style the modules already use (closed id-prefix table /
  ownership matrix / schema), immune to future renumbering.

Scope: the live skill (SKILL.md + references/ — what the agent executes).
docs/REVIEWS.md (historical review log) and docs/example-report*.md (a stale
sample already tracked for a separate refresh) are intentionally left as-is.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@Gandy2025
Gandy2025 merged commit cf1a16e into main Jul 7, 2026
1 check passed
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