Skip to content

Prose composed outside the commit path is hard-wrapped in GitHub bodies #1267

Description

@williamthorsen

Problem

Agents hard-wrap prose at roughly 100 columns in PR and issue bodies. GitHub renders a newline inside a paragraph as a literal line break, so the text reads ragged. Eight documents are affected: PRs #1213 and #1223, and issues #1256 and #1260 through #1264.

Context

The rule already exists and works where it reaches. commit/SKILL.md § Body mechanics states it, and prose arriving through the commit path is unwrapped every time.

PR #1223 shows the boundary inside a single document. Its ## What, inherited from a 336-character single-line commit body, is unwrapped; its ## Why, composed directly by summarize-change, wraps at 103. Step 4 of summarize-change marks that split explicitly: ## Why and ## Details are composed in place, while ## What comes from a separate dispatch.

The transmission path is not implicated. Every PR and issue body has gone out through --body-file since the pattern was adopted in April, including the unwrapped ones, and PR #1223 holds both a wrapped and an unwrapped section in one file written by one call.

Two files carry the rule in their own words today, and the second has drifted from the first: commit/SKILL.md and subagents/orchestrated-coder.md.

The rate is low. Two of 45 PR bodies and six of 77 issue bodies in August, none before. A fix cannot be confirmed by watching the rate fall.

Proposed solution

One partial under content/_partials/, carried by the two skills that compose the affected prose and the two files that already hold a copy. The rule states the line-break contract together with its precedence: a file in a repository is governed by the project's formatter, then by the convention already in the file; everything else takes one line per paragraph.

No ambient statement in shared guidance, and no sweep of the other artifact-writing skills. The evidence locates the gap at two composition sites, and guidance/shared/AGENTS.md loads in every session and every subagent.

A deterministic alternative was considered and deferred: normalizing the body file to join soft-wrapped lines before gh reads it. It would cost no ongoing context and could not be forgotten, but it reaches only the GitHub path, and it would put every body through a transformation to correct a lapse affecting eight. Revisit it if wrapping recurs after this change lands.

Acceptance criteria

Must have

  • One partial states the rule: each paragraph and each list item is a single line, with no newlines inserted to wrap at a column width.
  • It states the precedence governing a file in a repository: the project's formatter, then the convention already in the file.
  • commit, create-ticket, summarize-change, and orchestrated-coder each carry it.
  • The hand-written copies in commit and orchestrated-coder are gone, replaced by the partial.
  • A test asserts that each carrier holds the rule exactly once, and that no other content file carries its text.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions