Park

Park — freeze a PR that's waiting on the world

Some docs are done as far as they *can* be, but can't merge yet: they're written against an

upstream PR that hasn't merged, a feature that hasn't GA'd, an API still in review. Left as a

bare open PR, the context rots — six weeks later nobody remembers what it tracked or what was

known to be shaky. This skill freezes that context into the PR so it can be picked up

cleanly when the source settles.

Park is the pipeline's pause button between /reflect and /finalize — it preserves the

episodic layer and adds a forward-looking re-check contract, instead of distilling and

merging.

The manifest format is defined once in

../_shared/park-manifest.md — read it first, and

../_shared/commit-trailers.md for the trailer vocabulary

you'll harvest. This file is *how to build and land the manifest*.

Where this sits

/reflect          →  WIP commit messages          [episodic, provisional]
        ↓  THIS SKILL — when the work can't merge yet
/park             →  parked PR + manifest           [frozen; /finalize DEFERRED]
        ↓  (wait for the upstream trigger)
/unpark           →  reconcile docs vs source        [thaw + delta]
        ↓
/reflect+/finalize → durable squash commit           [resume the normal pipeline]

The one principle: snapshot the source, not just a pointer

A note that says "watch upstream PR X" is nearly useless on unpark — it tells you where to

look but not *what changed*. The manifest must capture the source's state at park time

(merge status, head SHA, milestone, the observed API shape) so unpark is a diff, not a

fresh read. Recording the snapshot is the whole value of parking; everything else is

plumbing.

Step 1 — Confirm it should be parked (not merged, not abandoned)

Park only when the docs are as complete as the source allows and the sole blocker is an

external event. If the work is merely unfinished, keep working. If the source may never ship,

don't park — say so. There must be a concrete, testable trigger condition.

Step 2 — Harvest the loose ends already on the branch

The branch's own commits hold the re-check items, from /reflect:

git log --reverse main..HEAD --format='%(trailers:only,unfold)'

Pull the Recheck:, Gaps:, and Directive: trailers — these seed the checklist. Read the

commit bodies too, for the *why*. Don't restate them as trailers on a new commit; they belong

in the manifest checklist now (see ../_shared/park-manifest.md,

"Relationship to commit trailers").

Step 3 — Snapshot each pinned source

Identify the external sources the docs depend on (URLs in the ticket, commit bodies, the page's

bannerText). For each, capture its live state with the endpoint that matches the source type.

For a GitHub pull request:

gh api repos/<owner>/<repo>/pulls/<n> \
  --jq '{state, merged, head_sha: .head.sha, base: .base.ref, milestone: .milestone.title, updated_at}'

For a GitHub issue — a feature-request or GA-tracking issue, say — the pulls endpoint and

its merged / head / base fields don't exist, so use issues/<n>:

gh api repos/<owner>/<repo>/issues/<n> \
  --jq '{state, state_reason, milestone: .milestone.title, updated_at, closed_at}'

Record URL + snapshot in the sources table, and the re-fetch command for unpark. Add a

confidence-tagged summary of the API/behaviour the page assumes (LOW for docs written

against an unmerged diff — and say *why* it's low, e.g. "signatures differed between two reads

of the diff").

Step 4 — Compose the manifest & PR body

Build the PR body: a short human summary, a prominent do-not-merge warning linking the

source, then the <!-- park-manifest -->…<!-- /park-manifest --> block with all five

required sections (per the shared spec). The page itself should already carry a bannerText

"not yet released / subject to change" note — if it doesn't, add one before parking.

Step 5 — Land it

• Commit any working-tree edits first — including a bannerText you added in Step 4 — and

confirm a clean tree before pushing. The parked PR must not get its manifest and labels while a

required edit lingers only in the local working tree.

• Push the branch.
• Open the PR, or update an existing one in place. For a new PR:

  gh pr create --title "DOC-XXXX <summary> [PARKED]" --body-file <body> \
    --label parked --label "do not merge yet" --base main

When the branch already has a PR (re-parking — gh pr create would fail), replace the body

and ensure the labels instead:

  gh pr edit <n> --body-file <body> --add-label parked --add-label "do not merge yet"

• Verify the labels stuck (gh pr view <n> --json labels).
• Do not run /finalize. State explicitly that it's deferred until unpark — the manifest

records this, but say it in your handoff too.

Present the PR URL, the trigger condition, and the checklist, then stop. Opening a PR is

outward-facing — if the branch isn't pushed or the user hasn't asked, confirm first.

Limits (read honestly)

• A stale snapshot is worse than none — if you record a head SHA or API shape you didn't

actually verify, unpark diffs against fiction. Snapshot only what you checked; leave the

rest out and flag it in the checklist.

• Park cannot judge whether the source will ship. It records a trigger; it doesn't predict

the future. A parked PR that never triggers is dead weight — /unpark's scan mode is how you

find and close those.

• It defers, never distills. If you're tempted to "just finalize while it's fresh," don't:

you'll squash away the very notes unpark needs. Freshness is preserved *in the manifest*, not

in a premature durable commit.

• The manifest is only as good as the checklist. If Step 2's harvest is skipped, the loose ends

live only in scattered trailers and the unparking starts blind.