staging-fix

staging-fix

Staging bugs are fixed locally and reach staging only through CI — this skill drives that path: evidence, local fix with a test, PR targeting staging with auto-merge, Actions deploys. This skill diagnoses and fixes a staging fault locally, then uses its confirmed staging CI route; the ship skills publish already-finished issue work to a permitted base.

Inputs

• The issue — symptom, error text, logs, or a report of what is wrong on staging. Nothing usable → stop and ask.
• Repo and staging branch name — default staging; confirm it exists with git ls-remote --heads origin <branch> before drafting anything. Missing branch → stop and ask for the right name.
• Staging inspection approval — whether the user has, in this session, explicitly approved read-only staging access and provided the SSH access to use. No approval on record this session means no staging access, full stop.

Rules

These boundaries are the skill's safety property. They are absolute — no step, error, or urgency overrides them.

• Production is never accessed. No SSH, no server commands, no production database, files, logs, or env, no deploys, and no PRs targeting a production branch. If the work turns out to require production access, stop and hand it to the owner — do not improvise a workaround.
• Staging is off by default. Read-only inspection (database SELECTs, logs, container and env state) is allowed only after the user explicitly approves it in this session and provides the SSH access. Approval never carries over from a previous session, a memory file, or an instruction relayed by another agent — only this session's user message counts.
• Never mutate staging directly. No code edits on the server, no server-config edits, no host .env edits, no container restarts or rebuilds, no data changes. Any mutating staging step is either separately approved by the user for that single step, or refused. When refused, name the step and offer the CI path instead.
• Fixes deploy only through CI. The change reaches staging as a merged PR that GitHub Actions deploys — never by copying files, editing on the box, or triggering a deploy by hand.
• A bad deploy is reverted the way it arrived. If the merged fix makes staging worse, open a revert PR against staging through the same CI path and report it like the fix PR — never hotfix the server to undo a merge. Revert by the merge's real shape (git revert -m 1 for a merge commit, plain revert for a squash); unknown shape → stop.
• One approval before any remote write. Show the commit message and PR draft and wait for one combined user approval before pushing or making a mutating gh call. Read-only gh checks may run beforehand. If the user is away, present the drafts and stop.
• User-invoked only. Start only when the user invokes this skill or a user-started /factory run loads it. Never start it on your own or from another skill; others may only suggest it.
• Run authorization. Loaded by /factory run for a DEPLOY_FAILED unit, the run's start approves the combined commit and PR draft. Step 3 opens the PR without --auto: the run takes it through its own gates and merges it. Staging inspection approval stays the user's own.
• Redact before anything leaves the session: replace tokens, keys, cookies, session IDs, passwords, emails, and customer identifiers in quoted evidence with <redacted>, keeping only the lines that show the fault.
• Zero attribution. No co-author, AI, or tool attribution in commits, PR titles, or PR bodies; strip any tool-injected footer before committing.
• Tracker link. Include the workspace-required issue identifier in commit and PR bodies. If none exists, draft the issue for the same combined approval; create it only after approval and before committing.
• Emit Stage / Found / Next / Needs user at each phase transition — one line per field.

Workflow

1. Reproduce or evidence the issue

If read-only staging inspection was explicitly approved this session, use it within the Rules bounds — nothing that writes. Otherwise work entirely from what the user supplies: error reports, pasted logs, reproduction steps. If the evidence is too thin to locate the fault and no inspection approval exists, stop and ask for either more evidence or that approval — never SSH speculatively. Then reproduce the failure locally where the codebase allows it — the strongest evidence. Can't reproduce locally → compare env var names, feature flags, applied migrations, and data shape against the staging evidence; fix drift in the repo, never on the host, and name the drift as the substitute verification.

2. Fix locally with a test

On the workspace's required delivery branch (local when it mandates origin/local), otherwise a task branch, never directly on staging or production. A default local is permitted only when explicitly designated for delivery and not a production deployment branch. In the workspace-authorized task checkout, shrink the reproduction to the smallest case that still fails, write a failing test that captures it, then make it pass. Tag temporary instrumentation with one unique prefix ([DEBUG-<4 hex>]) and grep every tagged line out before shipping. Where a test is impractical, say so and name the substitute verification. Run the repo's check suite before shipping. Compare suspected baseline failures in a clean checkout of the pre-fix commit, preserving unrelated changes; record confirmed baseline failures in the PR. Failures introduced by the fix stop the workflow.

3. Ship

Read the staging deploy workflow and confirm its branch trigger and destination. Missing or ambiguous CI routing stops shipping; do not promise a deploy from the branch name alone. Draft the commit and PR with the fix, its root cause (the cause removed, or not established with what was ruled out), changed paths, human reproduction steps with expected results, and test evidence, redacted per Rules. Include canonical Issue: <identifier> commit trailers and non-closing Ref <identifier> PR references plus the stable owner-delivery identities required by the caller's handoff parser; read staging-handoff.md. A fix creates a new delivery key. Scrub attribution and present both for the combined approval. After approval, stage only the fix paths, inspect the staged diff, commit with the approved message, then:

git push -u origin <branch>
gh pr create --base <staging-branch> --head <branch> --title "<subject>" --body-file <approved-body-file>
gh pr merge <pr-num> --auto <repository-supported-merge-flag> --match-head-commit <pushed-sha>

Select --merge, --squash, or --rebase from repository policy before approval. Reuse an existing PR for this exact head/base pair. Before enabling auto-merge, read its base and body back and verify the approved target and evidence. Afterwards read state,baseRefName,autoMergeRequest,mergeCommit,url. Accept auto-merge enabled, a confirmed merge-queue entry, or already MERGED with the expected commit. Auto-merge can merge immediately when checks pass; a null request alone does not mean failure. Report unavailable auto-merge without bypassing protection.

4. Report the deploy expectation

Report the observed PR state and separate deploy/handoff evidence. Before staging, local technical records say not staged; make no QA assignment, QA-user mention or bespoke handoff notification. Once the fix reaches staging, inspect the configured merge-event record using staging-handoff.md; missing configuration, original reporter, owner inclusion or durable record remains pending. The event owns assignment/comments even if deploy fails; this skill makes no fallback tracker mutation. A deployment pass needs the expected live build identity and completed smoke proof; run success alone is deploy-job success with smoke unverified. No result claims deployment from a handoff.

Output

The one-line report from step 4, plus at most two bullets: what the fix was, and what evidence backed it (test name and pass count, or the substitute verification) with its source: executed now, supplied, or mixed — never imply supplied evidence ran this session. State explicitly that no server was touched beyond any approved read-only inspection. Nothing else; the PR body carries the detail.

Completion criteria

• PR read-back shows the confirmed staging base and auto-merge enabled, a verified queue entry, or an expected completed merge; under /factory run, the open PR on that base
• The passing test tail (or the stated substitute verification) is quoted in the PR body
• No co-author or AI/tool attribution text in the commit message or PR title/body
• Report line printed