---
name: sdp-release-process-run
description: Execute the SDP Release Process (doc/ReleaseProcessOverview.md) step by step, pausing for explicit human confirmation after each numbered step. Use whenever asked to run/execute/start/resume the SDP release process, cut a release or patch, or "turn the crank."
---

# SDP Release Process Runner

Operational layer for executing `doc/ReleaseProcessOverview.md`'s numbered Procedure steps
for real. This skill does NOT duplicate that document's step content -- it's the source of
truth and can change over time (it did, the same day this skill was written: a Friday/holiday
scheduling note and a preview-first merge/copy practice were both added mid-release). Always
read the *live* copy from whichever workspace you're currently in before executing a step,
rather than trusting anything cached from earlier in the conversation.

## The core practice: one step, then stop

**Do the real work for exactly one numbered step, then stop and report before touching the
next one.** This is a deliberate human-in-the-loop accountability pattern, not just a
one-off pace-setting request -- treat it as the default for this skill even if not
re-stated for a given run. Concretely, for each step:

1. Read that step's current text from `doc/ReleaseProcessOverview.md` in the relevant
   workspace (see "Which workspace" below).
2. Do the actual work -- run the commands, check the state, make the edits -- don't just
   describe what the step says to do.
3. Report what you found/did, including anything that needed a judgment call (e.g. an open
   JIRA issue that looks like it should be deferred, per Step 1/16's own guidance).
4. Explicitly stop and wait for the user to say to proceed. Never chain multiple steps
   together in one turn, even if a step turns out to be a no-op ("already satisfied, nothing
   to do") -- report that finding and still wait, since the user may want to redirect, ask a
   question, or handle something out of band before the next step.

Do not delegate this whole flow to a subagent/fork that would run multiple steps
autonomously -- the per-step pause is the point, and a background agent can't surface a
mid-flight question to the user the way inline execution can.

## AI-specific shell environment know-how

- **Shell state does not persist between your own tool calls.** Sourcing `tools/env.sh`
  (Step 8) in one Bash call does not carry forward to the next -- there is no persistent
  interactive shell behind you the way there is for a human following this doc. Re-source
  `env.sh` (or just invoke scripts by relative/full path, and reference `$WSRoot`-equivalent
  paths explicitly) in whichever call actually needs one of its aliases/functions/PATH
  entries.
- **Steps alternate between different P4 clients/streams** (`dev`, `main`, the release
  stream once cut) -- a P4 client can only be switched to one stream at a time. Per the
  doc's own "Preparation" section, use one workspace directory per stream. Before running a
  step's commands, confirm you're in the *right* one (`p4 info`'s "Client stream" line, or
  just check the directory) -- don't assume the last workspace you touched is still the
  right one for the current step.
- **Set `P4CONFIG` explicitly per command** rather than relying on an exported env var
  persisting -- this project's convention is `.p4config.bot_Claude_Anthropic` for
  AI-attributed work, sitting alongside the human operator's own `.p4config` in each
  workspace root.
- **Regenerate HTML freely; never regenerate PDF except in Step 14** (the actual release
  process's own doc-generation step) or when specifically asked to check PDF rendering. See
  the "Documentation Builds" section of `SDP_DeveloperGuide.adoc` for the full policy --
  PDFs are large, low-incremental-value files not worth regenerating during ordinary steps.
- **Check `p4 files <path>` before assuming a generated doc needs Copy Up treatment.**
  Some generated artifacts (`doc/*.html`, `doc/*.pdf`, `doc/gen/*.man.txt`) are `isolate`d
  and tracked in `main` only, not `dev` -- editing/regenerating them in `dev` may find
  nothing to open at all, which is expected, not an error.
- **Always preview before merging or copying** (`p4 merge -n` / `p4 copy -S <stream> -n`),
  per the practice now documented alongside the "Merge Down, Copy Up" mantra in this same
  doc -- check the preview against your own workspace's opened-file state before proceeding.
- **After Step 10 (Copy Up), `dev` and `main` are *expected* to diverge again** -- Copy Up
  is a one-time event for the release, not something to repeat after every subsequent `main`
  -only edit (Steps 11+ intentionally happen in `main` alone, per the doc). If you make a
  small process-doc fix in `dev` after Step 10 and try to Copy Up just that file, expect
  `Stream //p4-sdp/dev cannot 'copy' over outstanding 'merge' changes` -- this is the flow
  guard correctly detecting that `main` now has independent content `dev` doesn't (e.g. the
  Step 11 revnumber/date bumps), and it wants a Merge Down first, which isn't the right move
  mid-packaging. Just apply the same small fix directly in `main` too (two independent
  identical edits), rather than fighting the guard or forcing a Merge Down you don't want.

## Which workspace for which step

Steps explicitly say which client to use (`dev`, `main`, or "whichever client you're
currently in"). Track this per-step rather than assuming; several steps in a row often use
the same client, but Step 9 (Merge Down, `dev` client) is immediately followed by Step 10
(Copy Up, `main` client), and everything from Step 10 onward through packaging happens in
`main` until the release stream is cut (Step 17), after which most remaining steps move to
that fresh release-stream client instead.

## Judgment calls worth surfacing, not silently resolving

- **Step 1 (Plan)**: query JIRA for open issues tagged with the release's Fix Version.
  Anything that looks unaddressed and not already known-deferred (check the issue's own
  description for a stated fallback plan) is worth surfacing to the user with a specific
  recommendation (usually: retarget `Fix versions` to the next release), not just noted in
  passing.
- **Step 4 (Verify Regression Tests)**: if one of the three suites can't be made to pass
  (e.g. infrastructure flakiness unrelated to code), that's a real decision point for the
  user, not something to route around quietly. Supplementing missing coverage with targeted
  manual testing (as done for a Jenkins/podman host issue during the 2026.1 release) is a
  legitimate mitigation, but say so explicitly rather than treating the suite as if it
  passed.
- **Step 16 (Update Release Notes)**: this is the authoritative point for reconciling JIRA
  issue status against what's actually in the release notes -- don't skip or shortcut this
  audit even if Step 1's lighter check looked clean, since new issues get closed throughout
  the cycle.
- **Whenever closing a JIRA issue during this process (Steps 1, 16, 21), explicitly set the
  `resolution` field, not just the `status`.** This project's "Close" transition moves
  `status` to `Closed` (statusCategory Done) but does *not* set `resolution` -- confirmed the
  hard way during the 2026.1 release, when JIRA's "Release version" dialog reported "10
  unresolved work items" for a Fix Version where every single issue was already visibly
  `Closed`. JIRA's release-blocking "unresolved" check is driven by `resolution` being empty,
  independent of `status`/statusCategory. After transitioning an issue to Closed, also run
  `editJiraIssue` with `{"resolution": {"name": "Done"}}` (or whatever resolution value fits)
  -- don't assume the transition handled it, and don't assume this is new/changed JIRA admin
  behavior if it surprises the user; it's more likely existing issues have always had empty
  resolutions and this is simply the first time something actually checked.
- **Step 21 (Release in JIRA)**: when the human operator brings up the "Release" dialog,
  remind them to **uncheck "Create release notes"** before confirming. JIRA's own
  auto-generated release notes feature is not used for SDP -- the real release notes live in
  `doc/ReleaseNotes.adoc` (Step 16) -- so leaving that box checked just creates unwanted,
  redundant JIRA-side content.