business-review

# Business Review (Relaticle v3): panel-of-QAs, environment-discovering, regression-aware

A panel of senior manual QAs for Relaticle. The engine is the proven v2/universal one
(preflight → tier → journey fleet → adversarial verify → substance-gated verdict), with
three organs no earlier generation had: an **environment-discovery stage** (nothing about
URLs, credentials, or infra is assumed. It is derived from the running app each run, so
the skill keeps working when app code, routes, or domains change), a **regression ledger**
(`~/.claude/business-review/relaticle/regressions.json`, machine-local and NOT in the repo:
the repo is public and the ledger records production incident history. Past confirmed
findings become standing checks the planner MUST schedule when the diff matches their
trigger; `$BR_LEDGER` overrides the path), and a **fix mode** (find → fix → cold
re-verify against the original repro → re-gate, on request).

Every claim is **browser-truth**: observed through the live UI, never `tinker`/DB; an
error is a *finding*, never something to engineer around. Coverage is a required,
attested output: journey map, per-journey value verdict, sad-path attestation, regression
sweep, and an explicit frontier with `how_to_close`.

## Invocation: natural language first, flags as internals

```
business-review                          # local: current branch vs main, committed only
business-review --working-tree           # local incl. uncommitted changes
business-review --pr <N>                 # review a GitHub PR on relaticle/relaticle
business-review --describe "<text>"      # AC from free text, no diff
business-review --fix                    # after the verdict, enter fix mode automatically
business-review --publish                # post to the PR when done (healthy runs only)
business-review --no-prompt              # suppress the end-of-run prompt
business-review --reverify REG-NNN       # replay one ledger entry's repro verbatim, report pass/fail
```

**Parse the user's words, not just flags.** Real invocations are natural language; map them:

| User says (any phrasing like…) | Effect |
|---|---|
| a bare number, `#332`, or a PR URL | `--pr <N>` |
| a PR URL + "inside this branch" / the PR is already MERGED into the current branch | `--pr <N>` reviewed against the LOCAL live app: diff = `git diff <merge>^1 <merge>` (or `gh pr diff`), walks run on this checkout, comment posts to the merged PR with both the merge and head SHA in the br-sha footer (verified: 2026-06-12, PR 336) |
| "deploy to prod for 100,000 customers", "stress testing", "every single detail/angle", "deeply", "end-2-end" | **Tier 3 override** (production-gate depth, §Tiers). Never tier below the user's stated stakes |
| "20+ scenarios", "as many scenarios as possible" | depth override: plan at least that breadth on the touched arcs |
| "quick check", "smoke", "just sanity" | cap at Tier 1 |
| "post review into PR (with screenshots)" | `--publish` (screenshots are always inline; see §Publish) |
| "fix all issues", "fix and reverify", "fix inside this PR" | `--fix` (fix mode, §Stage 6) |
| "is <bug> still fixed?", "re-check <finding>" | `--reverify` against the matching ledger/review finding |

There is **no `--tier` flag**. Tier is auto-computed (`scripts/compute_tier.py`) and only
ever raised (never lowered) by user emphasis. When the user's words and the computed tier
disagree, take the higher and say so in the plan.

## Autonomy contract

Ask **0–N clarifying questions, batched at the END of Stage 1**, each justified in
REVIEW.md `## Context gaps`. Stage 0 feeds that batch (unreachable URL after discovery,
no working credential for a role in scope). **No mid-run questions.** The only permitted
mid-run halt is the degraded-channel escalation (`references/preflight.md`). Under
`--no-prompt`, unresolved fields become Context gaps and preflight fails loudly instead
of asking.

## Stage flow

```
0 ENVIRONMENT  re-derive volatile facts from the RUNNING app (URLs, creds, queue, Redis,
               Reverb, credits) + 5-step browser-capability smoke  -- incapacity --> BLOCKED
1 UNDERSTAND   diff · sanitize untrusted text · AC curation · code-context subagent ·
               changed-surface map · regression-ledger match (check_regressions.py)
2 TIER + PLAN  classify_diff --profile -> compute_tier (0-3) ∪ user emphasis;
               journey synthesis (diff + CRM priors); personas; plan.md;
               GATES: validate_plan.py + check_regressions.py --plan
3 RUN          persona walks (lenses always; parallel subagents only Tier 3 + capacity-checked,
               inline sequential fallback is legitimate and recorded); browser-truth;
               health gate; artifact per claim
4 VERIFY       adversarial cold-repro of every bug in a FRESH context (mandatory subagent
               when the diff was authored in this session); coverage-critic -> frontier
5 REPORT       aggregate_verdicts.py -> substance gates 6b/6c (never vacuous) +
               regression-sweep section + decision_needed/frontier gates -> REVIEW.md
6 FIX MODE     (on request / --fix) fix -> cold re-verify EACH fix against its original
               repro -> re-run gates -> updated verdict -> ledger update
7 PUBLISH      opt-in; inline images (evidence branch / gh attach); ai-* label;
               br-sha marker; HARD-DISABLED when blocked
```

Stage detail lives in `references/`: `environment.md` (0), `preflight.md` (0),
`understand.md` (1), `tiering.md` + `journeys.md` + `personas.md` (2), `fleet.md` +
`browser-truth.md` + `ux-lens.md` + `checks-matrix.md` (3), `verification.md` (4),
`report.md` (5), `fix-mode.md` (6), `regression-ledger.md` (cross-cutting),
`screenshot-rules.md` + `gotchas.md` (cross-cutting).

## Setup

```bash
PRIOR_BRANCH=$(git branch --show-current)
MODE=local|pr|describe            # from invocation parsing
REVIEW_DIR=".context/reviews/${PR_NUM:-local}"     # same roots gen-1 used; LATEST.txt still maintained
mkdir -p "