DOCS-1629 - Add /stage-deploy and /review-deploy commands for two staging environments

[mafsumo]

Purpose of this pull request

Adds four Claude Code commands that deploy PR branches to Pantheon for external review, split across two dedicated environments:

• /stage-deploy and /stage-teardown — the existing helpdocs environment (staging/** branches), now scoped to UX/UI and site-wide feature previews.
• /review-deploy and /review-teardown — the docs-review environment (review/** branches) added in add workflow for second staging environment #7014, scoped to quick, temporary article-level review.

Both pairs reuse existing infrastructure. This PR adds no new workflow files; /review-deploy and /review-teardown depend on the docs-review workflow from #7014, which has already merged.

How it works

Staging (UX/UI, feature work):

1. /stage-deploy {pr-number} pushes a staging/pr-{number} branch.
2. workflow_deploy-to-pantheon-staging.yml triggers automatically.
3. Deploys to https://helpdocs-sumo-logic.pantheonsite.io/help/.
4. /stage-teardown {pr-number} deletes the staging branch.

Review (article-level, ad hoc):

1. /review-deploy {pr-number} pushes a review/pr-{number} branch.
2. workflow_deploy-to-pantheon-review.yml triggers automatically.
3. Deploys to https://docs-review-sumo-logic.pantheonsite.io/help/.
4. /review-teardown {pr-number} deletes the review branch.

What's included

• .claude/commands/stage-deploy.md, .claude/commands/stage-teardown.md
• .claude/commands/review-deploy.md, .claude/commands/review-teardown.md
• CLAUDE.md updates registering all four commands and clarifying which environment each is for

Key features

• Two separate slots, so a long-running UX/UI staging deploy doesn't block a quick article review, or the reverse.
• Conflict detection: warns before overwriting another PR's deployment in the same environment.
• Article URL detection: converts changed docs/*.md paths into a direct preview link.
• PR comment on deploy and teardown, confirming the URL and noting the environment is shared.

Conflict detection

Checks for existing staging/pr-* or review/pr-* branches and shows:

• Who created the conflicting deployment
• What article they're previewing
• Option to continue and overwrite, or cancel and coordinate

Article URL detection

• Analyzes PR files to find docs being changed
• Converts docs/path/to/article.md → /docs/path/to/article/
• Includes the direct preview link in the PR comment

Out of scope

Slack notifications were dropped from this PR. Claude Code running locally has no way to read WEBOPS_SLACK_URL, or any Slack bot token, out of GitHub Actions secrets — they're write-only once set, with no CLI or API path to retrieve them. The PR comment step covers coordination instead. A workflow-level redesign (posting from within GitHub Actions, which does have secret access) is a possible follow-up, not part of this PR.

Limitations

• Two shared slots, not per-PR: one deploy at a time per environment.
• Manual cleanup: branches persist until torn down with /stage-teardown or /review-teardown.
• Shared URL: reviewers on the same environment see whatever was deployed last.

Select the type of change

• Minor Changes - Typos, formatting, slight revisions
• Update Content - Revisions, updating sections
• New Content - New features, sections, pages, tutorials
• Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-1629

Testing

After merge, test staging:

/stage-deploy {test-pr-number}

Verify:

• Staging branch created (git ls-remote --heads origin 'refs/heads/staging/pr-*')
• Workflow triggered: https://github.com/SumoLogic/sumologic-documentation/actions/workflows/workflow_deploy-to-pantheon-staging.yml
• Site deployed to https://helpdocs-sumo-logic.pantheonsite.io/help/
• PR comment posted with instructions

Then run /stage-teardown {test-pr-number} and confirm the branch is deleted and the PR comment reflects it.

Repeat with /review-deploy {test-pr-number} and /review-teardown {test-pr-number} against https://docs-review-sumo-logic.pantheonsite.io/help/.

[mafsumo]

@kimsauce FYI this is a proposal for adding a claude code skill to sumologic-documentation to allow writers to easily generate preview/staging sites for docs reviews and tear them down when review cycles have been completed.

[mafsumo]

Coordination Features Added ✅

Added automatic coordination to prevent conflicts and keep team informed:

🔔 Slack Notifications

Posts to #web-ops (same channel as existing Pantheon workflows):

On deploy:

🚀 Staging deployment started for PR #6701
• PR: #6701 - Update Jira skill fields
• Author: @mafsumo
• Staging: https://helpdocs-sumo-logic.pantheonsite.io/help/
• Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/docs/integrations/jira/
• Monitor: [GitHub Actions]

On teardown:

🗑️ Staging environment torn down
• Branch: staging/pr-6701
• Previous deployment remains live until next deploy

⚠️ Conflict Detection

Before deploying, checks for existing staging/pr-* branches:

⚠️ Staging environment conflict detected!

Currently staged PR(s):
• PR #6701 - "Update Jira skill fields"
  - Author: @mafsumo
  - Branch: staging/pr-6701
  - Preview: https://helpdocs-sumo-logic.pantheonsite.io/help/docs/integrations/jira/

Do you want to:
1. Continue and overwrite (will notify team in Slack)
2. Cancel and coordinate with @mafsumo first

📄 Article Preview URL

Automatically detects the article being previewed from PR files:

• Inspects changed files in PR
• Converts docs/path/to/article.md → /docs/path/to/article/
• Includes direct preview link in Slack
• If multiple docs changed, links to primary file

This ensures everyone knows:

• What is being previewed (article URL)
• Who deployed it (author)
• When to avoid conflicts (Slack alerts)

No more accidentally overwriting someone's staging deployment! 🎉

[kimsauce]

This is a great idea, Mark! Had some feedback -

• I think this should be a command, not a skill. Skills in .claude/skills/ are passive reference guides (sumo-style, docusaurus, pr-template-guide) that get applied automatically. An explicitly invoked /stage-deploy command belongs at .claude/commands/stage-deploy.md.
• /stage-teardown has no corresponding file. Whether this moves to .claude/commands/ or stays as a skill, teardown needs its own file. There's no .claude/commands/stage-teardown.md or .claude/skills/stage-teardown/SKILL.md — so /stage-teardown as a slash command won't route anywhere.
• Update CLAUDE.md./stage-deploy and /stage-teardown aren't listed in the slash commands section of CLAUDE.md. New commands need to be registered there.

[mafsumo]

This is a great idea, Mark! Had some feedback -

* I think this should be a command, not a skill. Skills in `.claude/skills/` are passive reference guides (sumo-style, docusaurus, pr-template-guide) that get applied automatically. An explicitly invoked `/stage-deploy` command belongs at `.claude/commands/stage-deploy.md`.

* `/stage-teardown` has no corresponding file. Whether this moves to `.claude/commands/` or stays as a skill, teardown needs its own file. There's no `.claude/commands/stage-teardown.md` or `.claude/skills/stage-teardown/SKILL.md` — so `/stage-teardown` as a slash command won't route anywhere.

* Update CLAUDE.md.`/stage-deploy` and `/stage-teardown` aren't listed in the slash commands section of CLAUDE.md. New commands need to be registered there.

Good catches, all three fixed:

• Moved to .claude/commands/stage-deploy.md and deleted the old .claude/skills/stage-deploy/ directory — you're right that the skills subdirectory pattern is for passive reference guides; explicitly invoked commands belong in .claude/commands/.

• Created .claude/commands/stage-teardown.md as a standalone command.

• Added a Staging section to the slash commands table in CLAUDE.md registering both /stage-deploy and /stage-teardown.

[mafsumo]

Added /review-deploy and /review-teardown alongside /stage-deploy and /stage-teardown. They target the docs-review environment and review/** branches from #7014, giving quick article-level reviews their own slot so helpdocs stays free for UX/UI and feature-level staging. Also added a cross-reference note in stage-deploy.md pointing to /review-deploy, and registered both new commands in CLAUDE.md.

Merge note: /review-deploy and /review-teardown need workflow_deploy-to-pantheon-review.yml from #7014 to work. That workflow should merge before or shortly after this PR, or the new commands won't have anything to deploy to.

[kimsauce]

This is a great follow-up, @mafsumo ! The command/environment split is clean and the file structure matches the pattern we settled on for /stage-deploy. A few things before I approve:

• /review-deploy has no guard for the missing add workflow for second staging environment #7014 dependency. Right now if someone runs it before workflow_deploy-to-pantheon-review.yml exists, the push to review/pr-{number} will succeed and just silently do nothing since there's no workflow listening on that branch pattern yet. Can you add a line to the Limitations section (or a note near the top) saying this command has no effect until add workflow for second staging environment #7014 merges? Better to fail loud than have someone think it's broken.
• stage-deploy.md's own purpose section wasn't updated for the new split. CLAUDE.md and review-deploy.md's cross-reference both describe helpdocs as scoped to "UX/UI and feature previews" now, but stage-deploy.md itself still opens with the old framing: "Deploy a PR branch to the shared Pantheon staging environment for external review (legal, compliance, product)." The "When to use this command" bullets underneath don't mention UX/UI or features either. That's the exact ambiguity the cross-references are supposed to prevent, so I'd update the Purpose and When to use sections there to match the narrower scope.
• Can you confirm docs-review actually has HTTP basic auth set up? review-deploy.md states it the same way as the existing helpdocs line, want to make sure that's confirmed from add workflow for second staging environment #7014 and not just copied from the template.

Everything else (conflict detection, article URL detection, the optional Slack pattern) is consistent with what's already approved on /stage-deploy and /stage-teardown. Once the above are addressed I'm good to re-approve.

[mafsumo]

Thanks for the follow-up review, Kim. Addressing each point:

1. add workflow for second staging environment #7014 dependency guard for /review-deploy: moot now. add workflow for second staging environment #7014 merged before this reply, so the docs-review workflow exists and the command works end to end. No code change needed.

2. stage-deploy.md purpose/when-to-use: fixed. It now opens with "previewing UX/UI changes or other site-wide feature work," and the bullets talk about UX/UI, Docusaurus features, and layout/navigation review instead of the old "external review (legal, compliance, product)" framing. Matches CLAUDE.md and review-deploy.md's cross-reference.

3. HTTP basic auth on docs-review: confirmed. job_pantheon.yml (lines 89-91) runs terminus lock:enable whenever the multidev doesn't already exist, using the same PANTHEON_AUTH_USER/PANTHEON_AUTH_PASSWORD secrets. add workflow for second staging environment #7014 didn't touch that job, it only changed PANTHEON_STAGING_ENV_NAME and SITE_PATH in its own call to job_pantheon.yml. So docs-review gets the same lock and the same credentials as helpdocs, guaranteed by the shared job, not copied from a template.

Also dropped the Slack notification step from all four commands (/stage-deploy, /stage-teardown, /review-deploy, /review-teardown). Claude Code running locally has no way to read WEBOPS_SLACK_URL, or any Slack bot token, out of GitHub Actions secrets. They're write-only once set, with no CLI or API path to retrieve them, so I'm scoping that out. The PR comment step already in each command covers coordination instead, and the workflows' own build success/failure Slack ping is untouched.

[kimsauce]

Review

Verified workflow_deploy-to-pantheon-review.yml from #7014 is merged to main and its review/** trigger matches what these commands push to — that part is solid.

Found two real defects (present in both the staging and review pair, since the files are near-duplicates):

1. Missing --force on the deploy push (review-deploy.md:74, stage-deploy.md:73) — git push origin origin/{pr-branch}:refs/heads/review/pr-{number} has no force flag. Redeploying the same PR after the author amends/rebases/force-pushes (routine when addressing review feedback) will get rejected as non-fast-forward, with no documented fallback.

2. Overwrite comment promised but never implemented (review-deploy.md:53, stage-deploy.md:53) — the conflict prompt says "Continue and overwrite" "posts a heads-up comment on PR #{n}" (the PR being displaced), but Steps 3–6 only ever comment on the PR currently being deployed. The displaced PR's author never actually gets notified.

One lower-confidence gap:

3. Conflict template doesn't handle multiple stale branches (review-deploy.md:41) — since there's no automatic cleanup, git ls-remote can return several leftover review/pr-* branches over time, but the conflict message template only has a slot for one.

[mafsumo]

Thanks for catching these, Kim. Good review. Fixed both defects and the lower-confidence gap in stage-deploy.md and review-deploy.md:

1. Missing --force: added. git push --force origin origin/{pr-branch}:refs/heads/staging/pr-{number} (and the review/ equivalent), with a note on why: the target ref already exists from the previous deploy, and the PR branch may have been amended, rebased, or force-pushed since, so a plain push isn't guaranteed to be a fast-forward.

2. Overwrite comment never implemented: fixed. The conflict-handling step now posts a heads-up comment on the displaced PR when the user chooses to overwrite, separate from the Step 6 comment on the PR being deployed. The prompt promised this before, but nothing in the workflow ever executed it.

3. Multiple stale branches: addressed. The conflict template now lists every matching staging/pr-* or review/pr-* branch instead of assuming there's only one, notes that only the most recently pushed one is actually live on the shared URL, and suggests tearing down the stale ones. When overwriting, the heads-up comment goes to every displaced PR listed, not just one.

Pushed as 4a316ee.

[mafsumo]

@kimsauce , addressing your three new findings from the latest review. Fixed all three in both stage-deploy.md and review-deploy.md, pushed as 6398a72.

1. Fork PRs: fixed. Step 4 now fetches refs/pull/{number}/head instead of {pr-branch} and pushes FETCH_HEAD. GitHub maintains that ref on origin for every PR, whether the branch lives on origin or a fork's remote, so this works for fork-based contributions too. Step 1 no longer needs the branch name at all, just the PR number.

2. Self-conflict: fixed. Step 2 now excludes the branch belonging to the PR currently being deployed before evaluating conflicts, so redeploying the same PR after new commits doesn't treat its own prior deployment as a conflict and post an overwrite comment onto itself.

3. Deleted docs: fixed. Step 3 now filters gh pr view --json files on changeType != "REMOVED" before converting paths to preview links, so a deleted doc doesn't get a link that 404s.

Also merged main into this branch to pick up #6872, the AGENTS.md refactor. CLAUDE.md is now the one-line @AGENTS.md pointer, and I ported the Staging quick-reference bullet, key distinctions, and command table into AGENTS.md's Claude Code specifics section, matching the existing pattern for the other command categories there.

This should cover everything from your last two rounds of review. Can you take a final look before merging?

[mafsumo]

Merged in three more AGENTS.md changes from main (#7056, #7049, #7046) and resolved the conflicts, pushed as 15568a5.

Those commits removed the "Key distinctions" bullet block, dropped the stale /review reference, added a Bulk Changes section, and introduced /docs-pr-reviewer with its own quick-reference line and table. I kept that new structure as-is and folded the Staging entries in alongside it: the **Staging:** quick-reference line sits after /docs-pr-reviewer's **Workflow:** line, a new proactive-suggest bullet covers when to reach for /stage-deploy vs /review-deploy, and the Staging table follows the new PR review table. Didn't try to resurrect the removed Key distinctions block.

No changes needed to the command files themselves, this was all AGENTS.md structure.