Skip to content

Bring the Handoff Skills' Sentences to 25 Words or Fewer - #3570

Merged
ptr727 merged 6 commits into
developfrom
feature/3531-handoff-skills-sentence-length
Oct 28, 2026
Merged

ptr727 merged 6 commits into
developfrom
feature/3531-handoff-skills-sentence-length

Conversation

@ptr727

@ptr727 ptr727 commented Oct 28, 2026

Copy link
Copy Markdown
Owner

Summary

Next slice of the sentence-length cleanup. Every sentence over the cap in the three handoff-family skills, outside their generated include regions, is split or restructured to 25 words or fewer. Its meaning stays the same.

  • python3 scripts/prose_lint.py --check sentence-length per file:
    • .agents/skills/backlog-burndown/SKILL.md: 88 hits to 0.
    • .agents/skills/session-handoff/SKILL.md: 65 hits to 0.
    • .agents/skills/unattended-handoff/SKILL.md: 34 hits to 0.
  • The include regions are untouched. backlog-burndown and unattended-handoff carry AGENTS.md "Model Tiers", and session-handoff carries GOVERNANCE.md "Communicating with the User". No hit fell inside any of them.
  • A script compared develop with this branch for each file. It checked the frontmatter, headings, fenced code blocks, include regions, quoted strings, and link targets, and all of them match. Every inline code span is still present. The only additions are a second git branch -d in backlog-burndown and a second new in session-handoff, each repeating a name the sentence already used.
  • Some quoted section names were wrapped across a line break, so the gate counted their words. Those are rewrapped onto one line, and their text is unchanged.
  • No sentence was left long, and none needed a meaning change to fit the cap.
  • The regenerated copies under .github/skills/ and .claude-plugin/fleet-skills/ come from scripts/build_dist.py, and --check is clean.

There is one commit per skill and one for the regenerated distributions. The review fixes follow them.

Verification

  • prose_lint.py default rules on each of the three files: clean. Run with --diff origin/develop: clean.
  • uv run --no-project --script scripts/build_dist.py --check: current.
  • repo_gate.py and canonical_review.py status: clean.
  • docker_lint.py with markdownlint, editorconfig-checker, and cspell: 0 issues.

Local Review

Three local-strict-review passes were recorded, each over the whole branch diff, and they raised 10, 2, and 0 findings. Every finding acted on was introduced, where a split had loosened what the old sentence said:

  • a condition stopped reaching the next sentence ("Missing the label", "when the budget is reached", "Where the round is not narrowed", "Where the interface has a prompt mechanism")
  • a pronoun moved to a new antecedent
  • an "only" stopped covering both parking grounds, behind a new "one other ground" count
  • "whose fix changes" became "can change", and "can owe" became "owes"
  • a restrictive "where" clause became a separate assertion
  • a "means" turned an elaboration into a closed definition
  • a step moved after the hand-off it has to precede

The two follow-up commits fix all of them. The last pass raised none, so no introduced finding is open.

Refs #3531

🤖 Generated with Claude Code

ptr727 and others added 6 commits October 28, 2026 07:32
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings October 28, 2026 14:57
@coderabbitai

coderabbitai Bot commented Oct 28, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@ptr727

ptr727 commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

A recorded local strict-review pass covers head afee83f54726067fdfd04d246586cfb75174f616, the content this pull request carries at that commit against develop, and it recorded 0 findings.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

@codecov

codecov Bot commented Oct 28, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.50%. Comparing base (a70a543) to head (afee83f).

Additional details and impacted files
@@           Coverage Diff            @@
##           develop    #3570   +/-   ##
========================================
  Coverage    81.50%   81.50%           
========================================
  Files           26       26           
  Lines         9066     9066           
========================================
  Hits          7389     7389           
  Misses        1677     1677           
Flag Coverage Δ
python-3.13 81.50% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@ptr727

ptr727 commented Oct 28, 2026

Copy link
Copy Markdown
Owner Author

Merge Gate item 2: Copilot posted an error refusal on this head, read as possible quota, so no Copilot round covers it. The maintainer authorized this develop merge on 2026-10-28 under item 5. The coverage relied on is the attested local strict review pass on this head, which raised 0 findings, with 13 of 13 checks green.

@ptr727
ptr727 merged commit 8d390ac into develop Oct 28, 2026
13 of 14 checks passed
@ptr727
ptr727 deleted the feature/3531-handoff-skills-sentence-length branch October 28, 2026 18:08
ptr727 added a commit that referenced this pull request Oct 28, 2026
…ence Splits (#3573)

Refs #3531

This is a promotion fix for review thread `PRRT_kwDOQ5caqM6xQ88w` on
#3572. That thread is the P1 on `unattended-handoff` picker step 1,
where the full-page check no longer said which reads it applies to.

The #3570 sentence-length sweep split sentences in `unattended-handoff`,
`backlog-burndown`, and `session-handoff`. I compared each split in `git
show 8d390ac` with its original. This change repairs each one that was
ungrammatical or had lost its subject, an antecedent, or the scope of a
qualifier or reason. Each repaired sentence keeps the original meaning
and is 25 words or fewer. Text #3570 did not change is left alone, apart
from line rewrapping.

## Splits repaired

`unattended-handoff`:

- **Picker step 1, the full-page check (the P1).** Picker step 3 and the
worker's `decision` read are the subject again. The bold term is kept,
so step 1's other references still resolve. The check is defined, and
the re-read applies only where a read returns a full page.
- **Auto-resolvable, "Nothing on it waits on the maintainer".** "And no
comment asks..." had come loose after the `canonical-sweep` aside. It is
joined back to the label clause, and the aside now names
`canonical-sweep` rather than "the last".
- **Auto-resolvable, "Nothing has worked it".** The open-handoff and
claim-comment clauses are one sentence again, so "That is because each
marks work that has no pull request yet" covers both of them.
- **Worker step 1.** "Follow it" is back inside the "Where a parking
comment names a decision issue" condition.
- **Worker step 3, narrowed round.** "so each closes" had lost its
antecedent. It now reads "so each issue closes".
- **Worker step 3, unnarrowed round.** The hand-off to
`merge-and-release` is back under "where the round is not narrowed".
- **Parking step 2.** "and the handoff it belongs to" no longer reads as
an object of "would do to". "Comment onto it" is back under the
existing-issue condition ("In that case").

`backlog-burndown`:

- **Dispatching a Worker, "No worker inherits another's worktree".** The
"That is why" reason covers both dispositions again. The third clause
carries it as "for the same reason".
- **Assembling the Promotion Body.** "amend the body when it lands" had
"it" binding to the body. It now reads "when the fix lands".

`session-handoff`:

- **The Attended Session step 6.** Handing the lane back is back under
"Where work remains" ("In that case").
- **Closing a Session step 4.** The elliptical "Never the round's
state..." had come to follow the example sentence. "What goes there is
saved as the session's final act" now comes before it.
- **Running the Chain, unlisted forks.** The example sentence had moved
directly in front of "Missing the label there". That made "there" mean
only upstream-contribution forks, and the `new` clause had lost the
condition. The scope is unlisted forks again, and the read clause and
the `new` clause are one sentence again, as in the original.

## Local review

`local-strict-review` ran three recorded passes at the `frontier` tier.
The first raised 4 findings and the second raised 1, all fixed in the
two edit rounds. The third raised 1, recorded below.

### Open `introduced` findings

- `.agents/skills/unattended-handoff/SKILL.md` worker step 1, class
`introduced`. The rejoined sentence reads "since it unblocked the lane"
where the original read "since it is what unblocked the lane". The
meaning is identical, and the reviewer confirmed that. #3570 split this
sentence, so its second half is #3570's text. Rejoining it at the
original wording runs to 27 words. The reviewer's alternative, "Follow
that answer, since...", would restore the split and leave "Follow"
outside the condition, which is the scope gap this repair closes.
Disposition: declined on that evidence.

### Dropped findings

- `.agents/skills/session-handoff/SKILL.md` "Running the Chain",
unlisted-fork paragraph, class `style`. Copilot's round on `0b58dfed`
raised no thread, but its overview mentions "a minor non-blocking
grammar nit ... regarding the missing-label condition". The nearest
candidate is the participle "Missing the label there, a read prints...".
That phrase is identical in `git show
8d390ac^:.agents/skills/session-handoff/SKILL.md` line 359. Neither
#3570 nor this change altered it beyond rewrapping, so it is out of this
change's scope.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
ptr727 added a commit that referenced this pull request Oct 28, 2026
…tence Length, Handoff Skills, and Blog host-secrets (#3572)

## Summary

Promotes `develop` to `main`, carrying round 4 of the resync-issue
burndown:

- #3569: the registry declares no `python` profile. The schema and
`spec/validate.py` refuse one, since each declared directory's
`pyproject.toml` shape states its profile.
- #3567: the `CODESTYLE.md` Python summary names the undeclared-root
default. `CODESTYLE.md`, python-codestyle, and shell-codestyle reach 25
words or fewer per sentence.
- #3568: the `pr_review.py` `refusal=` usage text names the `sent` and
`spent` readings. pr-review-conduct, drive-pr,
`docs/pr-reviewer-reference.md`, and the last Copilot-instructions
sentence reach the cap.
- #3570: backlog-burndown, session-handoff, and unattended-handoff reach
the cap.
- #3534: Blog declares the `host-secrets` overlay, and the conformance
matrix names it the first adopter. The hub session took this over from
the Blog session.
- #3573: promotion fix for Copilot's finding on this pull request. It
restores the full-page check sentence and repairs 11 more #3570 splits
that lost a subject, antecedent, or condition scope.
- #3574: promotion fix auditing the #3567 and #3568 splits the same way.
It repairs 16 that lost an antecedent, a reason, or a condition's reach.

#3567, #3568, and #3570 merged into `develop` on attested local passes,
after Copilot refusals read as possible quota. The maintainer authorized
each, as recorded on those pull requests. The sweep slices continue
#3531 and do not close it.

Fixes #3556
Fixes #3563
Fixes #3560

🤖 Generated with [Claude Code](https://claude.com/claude-code)
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