Skip to content

Say in every prompt that a completion summary is a PR description - #175

Merged
MJohnson459 merged 1 commit into
mainfrom
summary-is-pr-description
Aug 14, 2026
Merged

MJohnson459 merged 1 commit into
mainfrom
summary-is-pr-description

Conversation

@MJohnson459

Copy link
Copy Markdown
Contributor

docs/DESIGN.md §8 already settles that a done summary "is written to read as
a PR description" — voro pr opens the pull request with that text as the body —
but the agent-facing prompts only gestured at it ("a PR-ready --summary"), and
the voro-cli skill did not mention --summary at all. Agents consequently
returned one-liners like "Implemented X, tests pass", which is the whole PR body
the operator then reviews against. This is a wording change: no schema, state
machine, or scoring moves, and nothing about when a summary is recorded moves.

Every place an agent is told what a summary is now says the shape, in a phrase or
a sentence:

  • crates/voro/src/dispatch.rs — the closing paragraph of
    RETURN_PATH_PREAMBLE_TEMPLATE now says the summary is the pull request's
    description and to write it as one ("a short account of what changed and why
    followed by how you verified it, not a status line").
    REWORK_SUMMARY_SENTENCE says the same and keeps its point-by-point demand
    ("a PR body that answers that feedback point by point, one item per point"). It
    stays a single shared constant, so the redispatch preamble's {rework} block
    and rework_message cannot drift. No new brace-wrapped text was introduced, so
    the single-pass renderer is unaffected.
  • crates/voro/src/cli.rs — the done usage block and the set --summary
    line in HELP (which is what voro done --help and voro set --help print)
    describe --summary as the PR description; the done warning appends "the
    summary is the PR description pr opens the pull request from" only when the
    summary is the missing half, and the show [incomplete report] nudge says
    the same.
  • plugins/voro/skills/voro-cli/SKILL.md--summary added to the done
    line in the transitions block, plus a sentence on the shape it takes. Edited
    the plugin copy, per CLAUDE.md.
  • docs/agent-integration.md — the copy-paste preamble's example, which was
    modelling the bad shape (--summary "Implemented X, tests pass"), now carries
    placeholder text that reads as a PR description, and the done bullet matches
    the wording landed in the prompts.

Summaries stay optional — the new wording describes the shape of one that is
written, never that one must be. docs/DESIGN.md needed no edit: §8 already
licenses all of this and nothing landed contradicts it.

Verification

  • New dispatch.rs unit test preamble_says_the_summary_is_the_pr_description
    asserts the plain rendered preamble against render_preamble; the existing
    preamble_tells_a_redispatched_rework_to_answer_the_feedback and
    the_rework_message_carries_the_feedback_and_the_instruction were extended so
    both spellings — render_preamble(…, rework = true) and rework_message(…)
    assert the PR-description wording alongside the surviving "point by point".
    Prose assertions match on whitespace-normalised text so a rewrap of the
    hand-wrapped constants does not break them.
  • New cli.rs test help_describes_a_summary_as_the_pr_description;
    done_warns_only_about_the_missing_half now also asserts the shape note
    appears for the missing summary and not for a missing branch, and
    a_partial_report_is_flagged_incomplete_in_list_and_show asserts the nudge
    names the PR description.
  • cargo test --workspace (470 + 1 + 389 passing, 0 failed),
    cargo clippy --workspace --all-targets -- -D warnings, and cargo fmt --all
    are clean.

DESIGN.md §8 already settles that a `done` summary "is written to read as a
PR description" — `voro pr` opens the pull request with that text as the body
— but the agent-facing prompts only gestured at it ("a PR-ready `--summary`"),
and the skill did not mention `--summary` at all. Agents returned one-liners
like "Implemented X, tests pass", which is the whole PR body the operator then
reviews against.

Every place an agent is told what a summary is now says the shape in a phrase:
the dispatch preamble's closing paragraph, the shared `REWORK_SUMMARY_SENTENCE`
(still demanding the point-by-point answer, still one constant so the message
and the preamble cannot drift), the `done` and `set --summary` help blocks, the
`done` warning and the `[incomplete report]` nudge when they name the missing
summary, the `voro-cli` skill's transitions block, and the copy-paste preamble
in docs/agent-integration.md, whose example was modelling the bad shape.

Nothing about when a summary is recorded moves, and summaries stay optional —
the wording describes the shape of one that is written.
@MJohnson459
MJohnson459 merged commit 3056219 into main Aug 14, 2026
7 checks passed
@MJohnson459
MJohnson459 deleted the summary-is-pr-description branch August 14, 2026 21:05
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.

1 participant