DOC-6830 Add /park and /pickup skills for parked-PR lifecycle#3612
Merged
Conversation
Two skills that bracket the existing /reflect -> /finalize pipeline for docs written against an unreleased or still-changing external source. /park freezes a branch as a PR carrying a machine-diffable manifest and defers the durable squash; /pickup thaws it once the source ships, diffing current source state against the park-time snapshot. Format lives in _shared/park-manifest.md, mirroring how _shared/commit-trailers.md is shared between reflect and finalize. Built against a real artifact first: the manifest in PR #3611 (DOC-6829) was hand-authored, then the shared spec was written to match it, so the format and a real instance are in sync. The load-bearing design choice is that the manifest snapshots the source's state (merge status, head SHA, milestone, observed API shape) rather than just pointing at it — that snapshot is what makes /pickup a diff instead of a blind re-read. Learned: park/pickup bracket reflect->finalize; the manifest snapshot is what makes pickup a diff, not a re-read Constraint: never run /finalize while a PR is parked — it squashes the Recheck/Gaps trailers that /pickup depends on Rejected: in-repo .claude/parked/ manifest file | chose a PR-body block so gh can read and list it with no merge-time cleanup Gaps: only the authoring side has been exercised; the /pickup path is unrun until an upstream trigger fires (SDR#3390 is the shakedown) Ticket: DOC-6830 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Address three Cursor Bugbot findings on the skill spec: reorder the manifest's "On pickup, then" so labels drop only after /reflect and /finalize (matching pickup Step 5), correct scan mode to apply Step 2's trigger-met check rather than citing Step 1, and document the `gh pr edit` re-park path alongside `gh pr create`. The fourth finding (a High claiming the REST `merged` field does not exist) was a false positive — the single-PR endpoint returns it — and is left unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…re reflect Address Cursor Bugbot High 3558314964: pickup Step 4 reconciled and rebased but never committed, while Step 5 ran /reflect and /finalize, which see committed history only — so an uncommitted reconcile would be silently dropped from the squash merge. Rather than bolt on a lone commit step (this is the second finding on the pickup closing sequence — subsystem churn), specify the whole sequence once as an explicit ordered list in Step 5 (commit -> /reflect -> /finalize -> drop labels) and make the manifest summary defer to it as authoritative. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Widen the fix for the recurring pickup closing-sequence churn instead of adding another step. Step 5 now leads with the invariant it enforces — before the `gh pr merge` hand-off the pushed remote PR head must contain everything that must land (reconciliation commit, Step 4's rebased/merged-main history, and any `/reflect` amend), because the squash sees only what is pushed — then orders the steps commit -> /reflect -> push -> /finalize -> drop labels, with a remote-matches-local check before hand-off. This addresses Bugbot High 3558614316 (missing push before merge), the third finding on this sequence. Also realign the manifest's "On pickup, then" summary to that exact order (commit -> /reflect -> push -> /finalize), per Codex review: the summary is copied verbatim into every parked PR body, and its previous "commit and push ... then /reflect" wording would push before the /reflect amend and re-open the gap. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Record the park/pickup review rounds on #3612: a new bugbot FP flavour (nonexistent 'merged' field, refuted empirically), an internal doc-vs-doc contradiction, and the 3-round pickup closing-sequence churn with the 'consolidation scoped too narrowly' recurrence; calibration 5 valid / 1 FP. Also correct two pre-existing off-by-one encounter counts (GraphQL, fix-quality) caught by Codex review. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Claude Code per-machine memory store belongs in ~/.claude and must never be committed; ignore any repo-root .claude/projects/ so it can't be added by mistake. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fifth review finding on the pickup closing sequence (bugbot 3558867168, 'manifest omits rebase step') — the third on manifest-summary-vs-pickup drift. Root cause: the manifest kept a hand-maintained copy of pickup's sequence, and a copy drifts from its source every round. Rather than patch in the missing rebase (inviting a sixth finding), remove the duplication: manifest section 5 now defers entirely to /pickup Steps 4-5 as the single authoritative sequence and restates no steps, so there is nothing left to drift. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture the decisive round of the #3612 pickup closing-sequence churn: the fifth finding forced the structural fix (eliminate the duplicated manifest summary), generalising the earlier 'widen the boundary' rule to 'when a duplicate of a procedure keeps drawing drift findings, stop duplicating and point at the single source'. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…shots Two review-driven skill fixes. Pickup: merge Steps 4-5 into one ordered git sequence (commit -> rebase/merge main + link-checks -> /reflect -> push -> /finalize -> drop labels), fixing bugbot 3558994646 — the old order ran 'git rebase' on a dirty tree before the reconciliation commit. Park: split Step 3's source snapshot into PR (pulls/<n>) and issue (issues/<n>) variants per Codex review, since the PR-only merged/head/base fields don't exist for issue-driven parks. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture the #3612 review cycle's decisive rounds: de-duplication validated (manifest copy-drift class closed) and a distinct pickup git-op ordering thread surfaced and fixed; correct the #3612 calibration header to 6 valid / 1 FP to match its enumerated findings (Codex P3). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit 91d0c20. Configure here.
Contributor
Author
|
Thanks @dwdougherty ! |
Two Codex review residuals. Park Step 5: commit working-tree edits (notably a bannerText added in Step 4) and confirm a clean tree before pushing, so a parked PR can't get its manifest and labels while a required edit lingers local. Manifest section 5: strip the residual 'reconcile, rebase, commit, push' step list (which also implied the stale rebase-before-commit order) so it is a pure pointer to /pickup Steps 4-5 — finishing the de-duplication. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture the r7 finding: the pickup git sequence hit its 4th churn round (force-with-lease), and the endgame shifted from consolidation to de-prescription — assert the invariant + intent checklist, delegate git mechanics; an invariant can't be incomplete the way a command list can. Calibration 8 valid / 1 FP. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… trigger check Address the 4th pickup git-sequence churn round (force-with-lease, bugbot 3559171169) not by patching another command but by de-prescribing: Step 5 is now the invariant + an ordered intent checklist (committed & synced -> /reflect -> remote==local -> /finalize -> labels last), delegating the exact git commands (rebase clean-tree, force-with-lease on rewritten history) to normal git — an invariant can't be incomplete the way a command list can. Also decouple Mode A's trigger check from Step 2's stop-and-report rule (bugbot 3559171157) so a scan records fired?=no and continues instead of aborting on the first not-ready PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds two Claude Code skills that extend the existing
/reflect→/finalizeexperience-notes pipeline to cover docs written against an unreleased or still-changing external source (an upstream PR, a preview feature)./park— freeze a release-ready-pending-upstream branch as a PR carrying a machine-diffable pickup manifest, apply theparked/do not merge yetlabels, and deliberately defer/finalizeso the episodic re-check notes survive./pickup— thaw a parked PR: re-fetch each pinned source, diff its current state against the park-time snapshot, report what changed vs what was predicted, reconcile the docs, then resume/reflect→/finalize. Includes a no-argument scan mode ("which parked triggers have fired?").Files
.claude/skills/_shared/park-manifest.md— the manifest format, defined once and shared by both skills (mirrors how_shared/commit-trailers.mdis shared by/reflect+/finalize, so the format can't drift)..claude/skills/park/SKILL.md.claude/skills/pickup/SKILL.mdDesign notes
/pickupa diff rather than a blind re-read.<!-- park-manifest -->markers), not an in-repo file —ghcan read/list it by label with nothing to clean up at merge./finalizeis deferred while parked — running it would squash away theRecheck:/Gaps:trailers/pickupdepends on.Proven against a real artifact
The manifest was hand-authored on a real parked PR first (#3611, the DOC-6829 Spring Data Redis JSON docs), then the shared spec was written to match it — so the format and a live instance are in sync. Honest limitation: only the authoring side is exercised so far; the
/pickuppath is unrun until an upstream trigger fires (spring-data-redis#3390 will be the shakedown).🤖 Generated with Claude Code
Note
Low Risk
Changes are agent workflow docs and tooling metadata only; no product docs, build, or runtime behavior.
Overview
Introduces a parked PR workflow for docs that are ready except for an unreleased upstream:
/parkopens or updates a PR with a PR-body pickup manifest (source snapshots, confidence-tagged assumptions, trailer-harvested checklist), appliesparked/do not merge yet, and defers/finalizesoRecheck:/Gaps:trailers survive;/pickupre-fetches pinned sources, diffs against the snapshot, reconciles docs, and resumes/reflect→/finalize, with a no-arg scan mode for triggers that have fired.The manifest contract lives once in
_shared/park-manifest.md(manifest §5 points only atpickupSteps 4–5 to avoid copy drift). Review iterations on this PR also expanded.claude/state/assess-comments.coverage.mdwith #3612 evidence and ignores/.claude/projects/in.gitignore.Reviewed by Cursor Bugbot for commit d9263a6. Bugbot is set up for automated code reviews on this repo. Configure here.