--- 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 ` 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 -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.