-
[OPIK-6296] [DOCS] feat: auto-refresh PR description on git push to prevent drift (#6546)
frostbyte_neo 发布于
2026-05-05 09:13:12 +00:00 - [OPIK-6296] [INFRA] feat: add shared PR description sync sub-skill
Introduce .agents/commands/comet/_pr-description-sync.md as a single
source of truth for refreshing a PR description after every git push,
so descriptions don't drift from what actually shipped (concrete drift
case: PR #6391 — endpoint paths, method names, and emitted events the
review cycle reshaped after the description was written).The sub-skill regenerates from the canonical pull_request_template.md,
preserves images/videos/Loom embeds and hand-edits, validates against
pr-lint rules, and confirms with the user via AskUserQuestion. Per-repo
"always" / "never" choices persist to user memory keyed by the
normalized remote URL, so the prompt only fires where the user wants it.Idempotent and a no-op when no PR exists for the branch.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- feat(skills): wire post-push PR description sync into the three skills
Three integration points for the new _pr-description-sync sub-skill:
- create-pr.md Step 3 — call the sub-skill after the post-rebase
force-with-lease push. Step 4's "PR exists" branch no longer
duplicates description-refresh logic; the sub-skill already ran. - work-on-jira-ticket.md Step 10 — add an explicit post-push contract
so any push that happens during the implementation phase triggers
the refresh. - address-github-pr-comments.md Step 6 deferred replies — sync the
description after the fix push and before posting the "Fixed in
" replies. Highest-drift moment in the PR lifecycle.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(skills): validate pr_number and disambiguate PR lookup; soften create-pr Step 4 wording
Address review feedback on PR #6546:
- _pr-description-sync.md Step 1: when pr_number is passed, always
fetch headRefName/state and verify they match branch before any
read or write; on mismatch, fall back to the branch lookup instead
of editing the wrong PR. - _pr-description-sync.md Step 1 branch lookup: replace the implicit
'.[0]' selector with explicit headRefOid==local HEAD disambiguation.
0 matches -> no-op; 1 match -> use it; >1 matches -> log and skip
rather than guess. Closes the High-severity case where multiple
forks/remotes can share a head-branch name. - create-pr.md Step 4: soften wording so it doesn't claim the
description "was already refreshed" when _pr-description-sync may
have no-op'd (user opted out, gh unavailable, or already in sync).
Item 4 (dedup with create-pr Step 6/7) addressed via PR reply — the
sub-skill already points at Step 6/7 as canonical; the bullets that
follow are sync-specific qualifiers.Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(skills): tighten _pr-description-sync spec — section-hash marker, semantic idempotence, concrete memory path
Address audit findings from PR #6546 self-review:
- H1: Replace the underspecified "preserve hand-edits that don't
conflict" rule with a concrete merge algorithm. Each refresh writes a
hidden HTML comment at the
body bottom. On next run, recompute each section's sha1 and compare
to the stored hash: equal -> overwrite with regenerated content;
differs -> user touched it, keep verbatim. No fuzzy matching. - H2: Redefine idempotence as sha1(body without marker). Resolves the
prior failure mode where Testing's commit list changed every push so
byte-equality never held — meaningful drift now triggers the prompt,
noise doesn't. - H4: Replace the {user-memory-dir} placeholder with concrete path
resolution: walk up from cwd looking for the project's MEMORY.md
index; fall back to ~/.claude/memory/ if absent. - M2: Step 1a now fails closed on pr_number/branch mismatch instead of
silently switching to the branch lookup. A caller passing a
mismatching hint is a bug; surfacing it is safer than guessing. - M3: Tighten the pr-lint placeholder check so bodies that legitimately
quote "<!-- REPLACE ME" while documenting this skill itself pass.
The check now matches the literal template comment block as the only
content of a section, not arbitrary substring occurrences. - Step 2 now uses mktemp and references the resolved PR number from
Step 1, not the (potentially unset) input hint. - Step 4 split into two parts: the marker-based section merge (4) and
always-on media preservation (4b). Step 4b's "extra ## sections"
rule clarified to anchor above the marker. - Marker-absent first run: regenerate everything, let user review the
full diff in Step 7. Their confirmation is the act of opting into
managed mode; the marker installs on first apply.
Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(skills): scope Step 4b media extraction to template-managed sections only
Address Baz review on PR #6546 (comment 3168840537):
Step 4b's "scan the current body for media" rule could lift media out
of a user-added custom ## section AND keep that section intact at the
bottom — resulting in duplicate writes or reorders when a custom
section contains image syntax.Tighten the scope: media scan + reinsertion now apply only to
template-managed ## sections (those defined in pull_request_template.md).
Media inside custom sections travels verbatim with the section's
intact appended block; it is never independently scanned or moved.Also clarify that sections preserved verbatim under the Step 4 marker
check carry their media along automatically — no separate lift needed.Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(skills): flip _pr-description-sync default to auto-apply
Address andrescrz review feedback on PR #6546:
Minor: let's remove friction by having more automation. I'd rather
not request confirmation. It's quite clear that we want up to date
PR descriptions.As mentioned, no need for user confirmation here.
I suggest reducing friction. LGTM, you can always change that in a
follow-up PR.Refresh is a routine bookkeeping action, not a decision. By the time
Step 7 runs, the body has already passed pr-lint, preservation rules
have already protected user edits, and idempotence has already
filtered out no-op cases. The four-option AskUserQuestion was friction
on every push for marginal value.New behavior:
- Default: silent auto-apply via gh pr edit. No prompt.
- Opt-out: per-repo
neverlist in the memory file. Sub-skill reads
it; users edit it (or ask the agent to) when they want to disable
auto-refresh for a specific repo. TheAlwayslist is gone — auto-
apply IS the always mode. - Media-stale reminder demoted from a pre-apply prompt preface to a
post-apply log line. Apply still happens; user is just informed.
Updated:
- Overview bullet 14: "Auto-applies by default" instead of "Confirms
via AskUserQuestion". - Step 4 marker-absent paragraph: drops references to user reviewing
diff in Step 7; first-run is implicit adoption of managed mode. - Step 7: rewritten as "Apply (auto, no prompt)". Single gh pr edit
call, no decision tree. - Step 8 (was Step 9): memory file now has only the Never list.
Sub-skill is read-only against the file; users opt out manually.
Caller files (create-pr, work-on-jira-ticket, address-github-pr-comments)
already say "the user opted out for this repo" / similar — those still
read correctly under the new spec, so no caller edits needed.Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
- fix(skills): drop the Never opt-out clause from _pr-description-sync
Per discussion on PR #6546: the per-repo opt-out was vestigial after we
flipped the default to auto-apply. Adds spec surface and a memory file
the sub-skill must read on every invocation, for a path that's likely
never used. The natural recovery for an unwanted refresh isgh pr edit
or the GitHub UI — and the marker check (Step 4) then treats those
edits as user-owned on subsequent runs and leaves them alone, so no
permanent opt-out is required.Removed:
- Step 1b (mute memory check) — gone; Step 1 is now flat with no
sub-step labels. - Step 7's Opt-out paragraph — replaced with a Recovery paragraph
pointing at gh pr edit / GitHub UI. - Step 8 (Memory entry — feedback_pr_description_auto_refresh.md) —
deleted entirely. No memory file, no path resolution, no normalization
rule for repo URLs. - Failure mode "Memory file read fails" — gone (no file to read).
Updated:
- Overview bullet 14 — "There is no opt-out flag; if a refresh ever
produces unwanted content, the user edits the body in the GitHub UI
or via gh pr edit, and the marker check leaves those edits alone on
subsequent runs." - Step 4 marker-absent paragraph — drops "opt the repo out" reference;
recovery guidance points at GitHub UI editing.
Net: spec drops from 8 sections to 7, ~50 lines lighter, simpler
surface for reviewers and implementers.Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com
Co-authored-by: Claude Opus 4.7 (1M context) noreply@anthropic.com
下载附件