Automate the job, not the typing

---
name: review-production-change
description: Independently audit a production release for hidden correctness, data, dependency, environment, and rollout risks. Use after implementation and staging verification, especially when the change includes ETL output, caches, background workflows, or deployment ordering.
---

# Review Production Change

Act as an independent release reviewer. Treat the implementation summary, tests, and green staging result as evidence, not proof.

## Establish the release boundary

1. Identify the production base, proposed head, acceptance criteria, rollout plan, and rollback path.
2. Inspect the complete diff.
3. List application, schema, data, workflow, cache, configuration, deployment, test, and monitoring changes.
4. Separate experimental changes from the production change.
5. Stop and report if unrelated work cannot safely ride with the release.

## Build the risk model

Ask:

- What must exist before this code runs?
- What happens between two workflows?
- Can a later commit bypass a pending prerequisite?
- Does green evidence name the target environment?
- Can a cache preserve an empty result?
- Are totals computed at the grain claimed by the product?
- Can missing or censored data look like zero?

Prioritize temporal and lineage risks.

## Verify independently

1. Trace one visible value from source through parser, storage, query, cache, API, and UI.
2. Exercise the negative path for each new gate.
3. Confirm workflow ancestry when one deployment depends on another.
4. Run relevant tests and the production build.
5. Open staging and test the changed path.
6. Derive at least one oracle from source evidence or an external observation.

## Report findings

Use this format:

```text
[severity] Short finding title

Evidence:
- file, workflow, query, or visible behavior

Failure mode:
- concrete sequence that produces harm

Required correction:
- smallest change that closes the gap
```

Choose one decision: `blocked`, `ready for staging`, or `ready for production PR`.

Never merge or deploy because the review is green. Preserve the human approval boundary.

#!/usr/bin/env bash
set -euo pipefail

workflow_name="${1:-}"
required_sha="${2:-}"
release_sha="${3:-}"
branch_filter="${BRANCH_FILTER:-main}"
max_attempts="${MAX_ATTEMPTS:-120}"
poll_seconds="${POLL_SECONDS:-30}"

if [[ -z "$workflow_name" || -z "$required_sha" || -z "$release_sha" ]]; then
  echo "usage: release-ancestry-gate.sh <workflow> <required-sha> <release-sha>" >&2
  exit 2
fi

git cat-file -e "${required_sha}^{commit}"
git cat-file -e "${release_sha}^{commit}"

for ((attempt = 1; attempt <= max_attempts; attempt += 1)); do
  if ! successful_shas="$(gh run list \
    --workflow "$workflow_name" \
    --branch "$branch_filter" \
    --status success \
    --limit 100 \
    --json headSha \
    --jq '.[].headSha')"; then
    echo "Could not read workflow runs." >&2
    exit 1
  fi

  while IFS= read -r run_sha; do
    [[ -n "$run_sha" ]] || continue
    git cat-file -e "${run_sha}^{commit}" 2>/dev/null || continue

    if git merge-base --is-ancestor "$required_sha" "$run_sha" \
      && git merge-base --is-ancestor "$run_sha" "$release_sha"; then
      echo "$workflow_name succeeded at $run_sha and covers $required_sha."
      exit 0
    fi
  done <<< "$successful_shas"

  if [[ "$attempt" -lt "$max_attempts" ]]; then
    sleep "$poll_seconds"
  fi
done

echo "Timed out waiting for $workflow_name to cover $required_sha." >&2
exit 1

#!/usr/bin/env bash
set -euo pipefail

script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
subject="$script_dir/release-ancestry-gate.sh"
fixture_dir="$(mktemp -d)"
trap 'rm -rf -- "$fixture_dir"' EXIT

git -C "$fixture_dir" init -q
git -C "$fixture_dir" config user.email "test@example.com"
git -C "$fixture_dir" config user.name "Release Gate Test"

printf 'zero\n' > "$fixture_dir/value.txt"
git -C "$fixture_dir" add value.txt
git -C "$fixture_dir" commit -qm "before requirement"
before_sha="$(git -C "$fixture_dir" rev-parse HEAD)"

printf 'one\n' > "$fixture_dir/value.txt"
git -C "$fixture_dir" commit -qam "required"
required_sha="$(git -C "$fixture_dir" rev-parse HEAD)"

printf 'two\n' >> "$fixture_dir/value.txt"
git -C "$fixture_dir" commit -qam "pipeline"
pipeline_sha="$(git -C "$fixture_dir" rev-parse HEAD)"

printf 'three\n' >> "$fixture_dir/value.txt"
git -C "$fixture_dir" commit -qam "release"
release_sha="$(git -C "$fixture_dir" rev-parse HEAD)"

fake_bin="$fixture_dir/bin"
mkdir -p "$fake_bin"
# The generated fake reads FAKE_SUCCESS_SHA when it runs, not while this fixture is created.
# shellcheck disable=SC2016
printf '#!/usr/bin/env bash\nprintf "%%s\\n" "$FAKE_SUCCESS_SHA"\n' > "$fake_bin/gh"
chmod +x "$fake_bin/gh"

run_gate() {
  (
    cd "$fixture_dir"
    PATH="$fake_bin:$PATH" \
      FAKE_SUCCESS_SHA="$1" \
      MAX_ATTEMPTS=1 \
      POLL_SECONDS=0 \
      bash "$subject" "Example Data Pipeline" "$required_sha" "$release_sha"
  )
}

run_gate "$required_sha"
run_gate "$pipeline_sha"

if run_gate "$before_sha" 2>/dev/null; then
  echo "expected a run before the requirement to fail" >&2
  exit 1
fi

echo "workflow ancestry tests passed"

export function parsePublishedCount(raw) {
  const token = String(raw ?? '').trim()

  if (/^<\d+$/.test(token)) {
    const upperExclusive = Number(token.slice(1))
    return {
      kind: 'censored',
      exact: null,
      lower: 0,
      upper: upperExclusive - 1,
      source: token,
    }
  }

  const exact = Number(token.replaceAll(',', ''))
  if (!Number.isSafeInteger(exact) || exact < 0) {
    throw new Error(`Invalid published count: ${JSON.stringify(token)}`)
  }

  return { kind: 'exact', exact, lower: exact, upper: exact, source: token }
}

export function assertCoarseTotalCoversDetail(coarse, detailedFloor) {
  if (coarse.kind === 'exact' && coarse.exact < detailedFloor) {
    throw new Error(
      `Coarse exact total ${coarse.exact} is below detailed exact-only floor ${detailedFloor}`
    )
  }
}

export function displayCount(count) {
  return count.kind === 'exact' ? count.exact.toLocaleString('en-AU') : count.source
}

import assert from 'node:assert/strict'
import test from 'node:test'

import {
  assertCoarseTotalCoversDetail,
  displayCount,
  parsePublishedCount,
} from './dashboard-data-contract.mjs'

test('keeps a censored value as an interval', () => {
  assert.deepEqual(parsePublishedCount('<20'), {
    kind: 'censored',
    exact: null,
    lower: 0,
    upper: 19,
    source: '<20',
  })
})

test('rejects a coarse total below the detailed floor', () => {
  assert.throws(
    () => assertCoarseTotalCoversDetail(parsePublishedCount('99'), 100),
    /below detailed exact-only floor/
  )
})

test('renders the published semantics', () => {
  assert.equal(displayCount(parsePublishedCount('1,095')), '1,095')
  assert.equal(displayCount(parsePublishedCount('<20')), '<20')
})

# Builder and reviewer role prompts

## Builder

Implement the scoped change and prove it on staging.

1. Restate the visible acceptance criteria.
2. Identify code, schema, data, workflow, cache, and environment dependencies.
3. Keep experiments outside the production diff.
4. Add focused tests before broad regression tests.
5. Run the production build.
6. Deploy to staging and test the path in a browser.
7. Record commands, URLs, workflow runs, and uncertainty.
8. Stop before production authority.

Leave evidence another reviewer can reproduce.

## Reviewer

Review this release independently from the builder.

1. Inspect the complete diff and acceptance criteria.
2. Reconstruct dependencies without relying on the builder's explanation.
3. Find a temporal sequence that tests may not cover.
4. Check whether an unrelated later commit can bypass a prerequisite.
5. Trace one visible value from source to UI.
6. Test the failure path of each new gate.
7. Verify the named staging environment in a browser.
8. Report findings by severity before the release decision.

Do not implement findings or approve a merge unless explicitly authorized.

# Production promotion state machine

Move work through observable states. Do not mark a state complete from an agent summary alone.

## Scoped

- The issue names the visible problem and acceptance criteria.
- Experimental work is explicitly excluded.
- The production diff is known.

## Built

- Implementation and focused tests are complete.
- Data operations are idempotent.
- Rollback behavior is documented.

## Staged

- Required data and schema state exists in staging.
- Relevant tests and the production build pass.
- A browser walk verifies the deployed path.

## Independently reviewed

- A reviewer with fresh context inspects the complete diff.
- Negative paths and workflow ordering are tested.
- Findings are fixed and rechecked.

## Ready for production PR

- The release contains only approved changes.
- Dependency gates bind workflow success to release ancestry.
- CI is green. No merge has occurred.

## Approved

- A human owner explicitly authorizes rollout.
- The final diff and CI state have not changed since approval.

## Released

- The approved merge path is used.
- Read-only checks confirm the production target.

## Learned

- Each failure mode becomes a test, gate, skill, playbook, or monitor.