Skip to content

release skill: Phase 2 step 1 is a single 1,700-word unbroken paragraph #623

Description

@SUaDtL

Finding

core/surface/skills/release/SKILL.md Phase 2 step 1 (line 240 on fix/579-578-576-findings-triage, will drift as the file grows) is a single unbroken paragraph, 10,256 characters / roughly 1,700 words, with no sub-bullets or line breaks. It composes the annotated tag message, asserts dates-match, and covers several distinct sub-steps in prose form.

Originally raised in #579 (blind exercise runs 14/15, deferred from #576) as "Phase-2 step 1 is one unreadable paragraph."

Why this is real but out of scope for a triage PR

The paragraph is dense specifically because it has accreted HIGH/MEDIUM fix rationale from several adversarial review rounds (each sentence traces to a specific finding). .github/scripts/test_release_lib.py carries a _GOVERNANCE_RULES-style dict of pinned literal phrases from this file's prose (mutation-style checks against specific wording). Restructuring the paragraph into sub-bullets risks:

  • silently dropping or rewording a pinned phrase and breaking a governance-rule test in a way that looks like a doc nit but is actually a silent contract regression, and
  • losing the "this sentence is the fix for finding X" traceability that a bullet-per-topic split would need to preserve deliberately, not accidentally.

This needs a dedicated pass that (a) maps every pinned phrase to its new location before restructuring, and (b) re-derives the governance-rule test assertions against the new structure — not a drive-by paragraph split bundled into a findings-triage PR touching a dozen other files.

Suggested approach

  1. Inventory every _GOVERNANCE_RULES-pinned phrase currently living in this paragraph (.github/scripts/test_release_lib.py).
  2. Split the paragraph into a numbered sub-list (6a/6b/6c-style, matching Phase 1's own step-6 sub-lettering conventions used elsewhere in this file), preserving every pinned phrase verbatim.
  3. Update the governance-rule tests' location assumptions if any are line/context-sensitive.
  4. Re-run test_release_lib.py and the full skill-authoring test suite.

Evidence

$ awk '/^## Phase 2/{f=1} f{print length($0), NR} /^## Phase 3/{exit}' core/surface/skills/release/SKILL.md | sort -rn | head -1
10256 240

Cross-ref: #579, #576.

Activity

  1. SUaDtL commented on Oct 5, 2026

    @SUaDtL
    CollaboratorAuthor

    Closing as fixed by #845. Phase 2 now has twelve ordered, named substeps (2.0–2.11). The invariant map preserves obligation-to-instruction/test traceability, with structural regression coverage.

    The same restructuring is in the published 0.15.1 release routine. This closure is based on source and existing evidence; no fresh independent exercise was run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    sev:lowTribunal/triage: low severity

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions