Skip to content

Scribe splices inbox H2 headings under H3 entries, breaking hierarchy #1760

Closed

Description

@bradygaster

Scribe merges decision-inbox files into .squad/decisions.md verbatim. But inbox files carry their own ## Context, ## Decision, ## Consequences, ## Rationale sections, and those H2s splice in beneath H3 entries.

Result: an H2 child under an H3 parent, which breaks document hierarchy and any TOC generated from it.

### 2026-08-19: Squad's responsibility matrix stops at this repo
## Context          ← should be ####
## Decision         ← should be ####
## Consequences     ← should be ####

Scale — cumulative, not new

H1 H2 H3
dev before #1754 3 stray 14 stray 30
after #1754 3 ~60 44

Pre-existing and growing with every Scribe run. PR #1754 added ~46 more and deliberately did not fix them, to keep that rescue reviewable.

The fix

In Scribe's inbox-merge logic: when merging an inbox file body beneath an ### entry, demote every heading in that body by two levels (## → ####, ### → #####).

Fix the merge logic first. A one-time cleanup of existing strays should follow, but only afterward — otherwise the next Scribe run reintroduces them.

⚠️ Gotcha for any cleanup script

Some apparent H1s are false positives: they're # comments inside fenced code blocks. For example decisions.md contains lines like:

# Just add to the Modes table:
# In workflows/squad.md:

Any cleanup pass must be fence-aware or it will corrupt code samples. A naive ^## regex is not safe here.

Origin

Surfaced while reviewing PR #1754 (the Scribe decision-inbox merge rescue).

Activity

  1. bradygaster commented on Aug 20, 2026

    @bradygaster
    CollaboratorAuthor

    Flight sequencing note — revised 2026-08-20.

    Wave: 1.

    Depends on: nothing in this gh-aw findings stream.

    Blocks: no numbered issue in this stream. A one-time cleanup of existing decisions.md heading damage should wait until this logic fix lands.

    Safe to run in parallel with: all other included issues. It is Scribe/state-document hygiene, not workflows/squad.md or worker dispatch work.

    Why / evidence: Scribe's charter owns the merge at .squad/agents/scribe/charter.md lines 23-31. The current broken shape is visible in .squad/decisions.md: an entry starts at line 8 as ### 2026-08-19..., then child sections appear as H2s at lines 13 and 25. That is independent of #1772, #1756-#1759/#1757, and #1748/#1762, which touch workflow/docs surfaces.

  2. added
    type:bugSomething broken
    triagedIssue has been triaged
    wave:2-soonWave 2 — next 2-4 weeks
    and removed
    bugSomething isn't working
    on Aug 20, 2026
  3. added
    squadSquad triage inbox — Lead will assign to a member
    on Aug 20, 2026
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

    priority:p2Next sprintsquadSquad triage inbox — Lead will assign to a membertriagedIssue has been triagedtype:bugSomething brokenwave:2-soonWave 2 — next 2-4 weeks

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions