Skip to content
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions .claude/skills/audit-code-quality/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,29 @@ finding, a completeness pass — same findings shape.

---

## Phase 2.5 — React Doctor pass (ui / frontend / both scope)

For any scope that includes the frontend, also run the deterministic **React-correctness
scanner** — it catches state/effects, hydration, perf, and a11y bugs the rubric's LLM finders
miss, and it is a **required CI check** (`.github/workflows/react-doctor.yml`):

```bash
npx -y react-doctor@0.7.6 --project apps/web,apps/mobile,packages/shared \
--json --json-out "$TMPDIR/rd-audit.json" \
--no-supply-chain --no-score --no-dead-code --yes --max-duration 360 --no-color
```

Scope to the three workspaces via `--project` — this **excludes `design/handoff/**`**, whose
vendored `*.jsx` design mockups emit ~1054 false `jsx-no-undef` errors that are not app code.
The flags match the CI gate's hermetic/no-knip stance; the CI gate is `--scope changed`, so it
never sees the standing backlog this full scan surfaces. Fold every diagnostic into the report
(the JSON's paths are workspace-relative — prefix with the project): react-doctor **errors** →
**High** (real React bugs), **warnings** → **Low/Info**, each tagged `[react-doctor · {rule}]`
with file:line + the rule's fix; group warnings by rule with a count. `api` scope skips this
(React-only). Report-only — surface findings, do not fix here.

---

## Phase 3 — Apply the rubric (what a repo-wide audit recalibrates)

The rubric was written for a diff; the workflow's finders already recalibrate two rules —
Expand Down
33 changes: 25 additions & 8 deletions .claude/skills/prod-readiness/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: prod-readiness
description: Pre-launch orchestrator — runs the four repo-wide audits (security, tests, performance, code-quality) in parallel via the audit workflow and adds an ops-layer audit (observability, multi-instance readiness, background durability, backups, staging), then consolidates everything into ONE tier-tagged, verification-protocol-backed report with an honest launch verdict. Use before a release to know what's safe to ship. Orchestrates + consolidates; it does not re-derive the child audits' findings.
description: Pre-launch orchestrator — runs the four repo-wide audits (security, tests, performance, code-quality) in parallel via the audit workflow, adds an ops-layer audit (observability, multi-instance readiness, background durability, backups, staging) AND a full-repo React-correctness scan (React Doctor) over orbit-ui-mobile, then consolidates everything into ONE tier-tagged, verification-protocol-backed report with an honest launch verdict. Use before a release to know what's safe to ship. Orchestrates + consolidates; it does not re-derive the child audits' findings.
argument-hint: <both (default) | ui | api | path>
---

Expand Down Expand Up @@ -44,7 +44,7 @@ The workflow runs its own coverage contract over the ops inventory + the §2 cha
its ops findings, and **inherits** each child audit's verify and loop; you merge every child
ledger into the consolidated report.

**The binding inventory (§1) — nine items:**
**The binding inventory (§1) — ten items:**

| # | Inventory item | Kind | Owner of the analysis |
|---|---|---|---|
Expand All @@ -57,6 +57,7 @@ ledger into the consolidated report.
| 7 | Background durability | ops check | the workflow (own §2 challenge) |
| 8 | Backups | ops check | the workflow (returns as Deferred — un-verifiable from a repo read) |
| 9 | Staging | ops check | the workflow (own §2 challenge) |
| 10 | React correctness (React Doctor) | scanner | the workflow (full-repo react-doctor scan of apps/web + apps/mobile + packages/shared; ui/both scope only) |

This list is **binding**: by the end every item is either **(a) covered with a verdict** or
**(b) in the Deferred ledger with a one-line reason**. There is no silently-skipped bucket.
Expand Down Expand Up @@ -100,13 +101,22 @@ durability · staging — as Haiku finders, runs a Haiku skeptic per Blocker/Hig
{ scope,
audits: [ { kind, findings, counts, coverage, deferred, rounds }, … ×4 ],
opsFindings: [ { severity, check, title, location, risk, evidence, fix } ],
reactDoctor: { ran, errorCount, warningCount, findings: [ { severity, rule, category, location, message, fix } ], note },
opsChecksRun, opsDeferred, failedAudits }
```

`opsDeferred` always includes **backups** ("verify in the DB console — PITR + a tested
restore path"). `failedAudits` names any audit workflow that errored — each forces **≤
CONDITIONAL** and is named as a blocker.

**React Doctor (item 10)** runs only for `ui`/`both` scope (it is React-only — `api` scope
returns `ran:false`, a legitimate skip, not a gap). It is the deterministic React-correctness
gate that also runs in CI as a **required** check (`.github/workflows/react-doctor.yml`, but
there `--scope changed` — only NEW issues). Here it scans the **full** app backlog across the
three workspaces (design/handoff mockups excluded — their vendored `*.jsx` throw ~1054 false
`jsx-no-undef`). A `reactDoctor.ran:false` for a ui/both scope is a **Deferred coverage gap**
(react-doctor couldn't run), not "clean".

---

## Phase 3 — Consolidate & write reports (Opus)
Expand All @@ -129,11 +139,14 @@ audit + native label** so nothing is silently relabeled:
| Consolidated tier | Maps from |
|---|---|
| **Blocker** | security Tier 1 · tests Critical · performance Critical · code-quality Critical · ops Blocker |
| **High** | security Tier 2 · tests High · performance High · code-quality High · ops High |
| **High** | security Tier 2 · tests High · performance High · code-quality High · ops High · **react-doctor error** (real React bug: effect cleanup, hydration/browser-global in render, impure updater, prop-callback-in-render, server-auth-actions) |
| **Medium** | tests Medium · performance Medium · code-quality Medium · ops Medium |
| **Low / Info** | performance Low/Info · code-quality Low/Info |
| **Low / Info** | performance Low/Info · code-quality Low/Info · **react-doctor warning** (perf/a11y/maintainability nits) |
| **Out-of-scope / acknowledged** | security Tier 3 · enterprise-only ops |

Tag each react-doctor finding `[react-doctor · {rule} · {error/warning}]` with its `location`
and `fix`. Group the (typically many) warnings by rule with a count rather than listing each.

### Report skeleton

```markdown
Expand Down Expand Up @@ -173,6 +186,7 @@ audit + native label** so nothing is silently relabeled:
| 7 | Background durability | … | … |
| 8 | Backups | deferred | verify in the DB console |
| 9 | Staging | … | … |
| 10 | React correctness (React Doctor) | yes/skipped(api)/deferred | {errorCount errors / warningCount warnings, or "skipped — api scope" / "did not run — deferred"} |

## Deferred ledger (verification-protocol §4)

Expand All @@ -188,10 +202,13 @@ above — silence reads as coverage.}

### Launch verdict (§5 honesty) — computed, never hardcoded

- **GO** only if **zero Blockers** AND all **9** inventory items produced a verdict (every
audit ran; every ops check resolved or is a legitimately Deferred un-verifiable like backups).
- **GO** only if **zero Blockers** AND all **10** inventory items produced a verdict (every
audit ran; every ops check resolved or is a legitimately Deferred un-verifiable like backups)
AND **react-doctor reports zero errors** (a react-doctor error is a real React bug and the
required CI gate's currency — GO requires the app-code error backlog at zero).
- **CONDITIONAL** if no Blockers but some items are Deferred in a way that gates launch (e.g.
backups unverified, staging gate absent) — name the conditions.
backups unverified, staging gate absent, react-doctor errors outstanding, or react-doctor
did not run for a ui/both scope) — name the conditions.
- **NO-GO** if any Blocker stands.
- **A `failedAudit` forces at most CONDITIONAL and names itself as the blocker** — a partial
sweep can never read green. The coverage table makes any non-running audit visible.
Expand All @@ -213,7 +230,7 @@ above — silence reads as coverage.}
| Medium | {N} |
| Low / Info | {N} |

**Inventory (9)**: security {ran/deferred} · tests {…} · performance {…} · code-quality {…} · observability {…} · multi-instance {…} · background durability {…} · backups {deferred} · staging {…}
**Inventory (10)**: security {ran/deferred} · tests {…} · performance {…} · code-quality {…} · observability {…} · multi-instance {…} · background durability {…} · backups {deferred} · staging {…} · react-doctor {N errors / M warnings, or skipped-api}
**Report**: `.claude/audits/prod-readiness-{scope}.md`
**Top blocker**: {the single highest-priority thing standing between here and launch, or "none"}
```
Expand Down
57 changes: 57 additions & 0 deletions .claude/workflows/prod-readiness.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ export const meta = {
phases: [
{ title: 'Audits', detail: 'the four /audit workflows in parallel' },
{ title: 'Ops', detail: 'observability · multi-instance · background durability · staging' },
{ title: 'React', detail: 'react-doctor full-repo scan of orbit-ui-mobile (ui/both scope)' },
{ title: 'Verify', detail: 'skeptic per Blocker/High ops finding — default refuted' },
],
}
Expand Down Expand Up @@ -49,6 +50,48 @@ const OPS_VERDICT = {

const OPS_LADDER = 'Blocker (a whole runtime is dark, or it corrupts user data on scale-out) / High (a single observability gap, a scheduler that double-fires, work lost on restart) / Medium (calibrated — e.g. a missing pre-prod gate)'

// React Doctor — the deterministic React-correctness gate (also a REQUIRED CI check,
// .github/workflows/react-doctor.yml). The CI gate is --scope changed (only NEW issues);
// prod-readiness runs the FULL-repo scan so the whole backlog is surfaced and fixed.
const REACT_DOCTOR_SCHEMA = {
type: 'object',
additionalProperties: false,
properties: {
ran: { type: 'boolean' },
errorCount: { type: 'number' },
warningCount: { type: 'number' },
findings: {
type: 'array',
items: {
type: 'object',
additionalProperties: false,
properties: {
severity: { type: 'string' },
rule: { type: 'string' },
category: { type: 'string' },
location: { type: 'string' },
message: { type: 'string' },
fix: { type: 'string' },
},
required: ['severity', 'rule', 'location', 'message'],
},
},
note: { type: 'string' },
},
required: ['ran', 'findings'],
}

function reactDoctorPrompt() {
return [
`Run React Doctor over the WHOLE orbit-ui-mobile repo (apps/web + apps/mobile + packages/shared) and report EVERY diagnostic — this is the full backlog, NOT the PR-scoped CI gate.`,
`Steps: cd to ${UI}. Ensure deps are present (node_modules exists; if not, run \`npm ci\`). Then run EXACTLY:`,
` npx -y react-doctor@0.7.6 --project apps/web,apps/mobile,packages/shared --json --json-out "%TEMP%/rd-prodreadiness.json" --no-supply-chain --no-score --no-dead-code --yes --max-duration 360 --no-color`,
`(SCOPE the scan to the three real app workspaces via --project — this EXCLUDES design/handoff/**, whose vendored *.jsx design mockups emit ~1054 false jsx-no-undef "errors" that are NOT app code. --no-dead-code + --no-supply-chain + --no-score match the CI gate's hermetic/no-knip stance; do NOT drop them. Default scope is "full" and --warnings is on, so BOTH error- and warning-severity diagnostics are reported. Paths in the JSON are workspace-relative — prefix each with its project when reporting location.)`,
`Read the JSON report file. For EVERY diagnostic emit a finding: severity ("error" or "warning"), rule (the rule id), category (e.g. Correctness/Performance/Accessibility/Security), location ("apps/…/file.tsx:line"), message (what's wrong), fix (the concrete change — from the rule's guidance; run \`npx react-doctor@0.7.6 why <file:line>\` if you need the rationale).`,
`Return ran=true with errorCount + warningCount + the full findings array. This is READ-ONLY analysis — do NOT modify any source file. If react-doctor genuinely cannot run (offline, deps unresolved after npm ci), return ran=false, findings=[], and a one-line note.`,
].join('\n')
}

const OPS_CHECKS = [
{
check: 'observability',
Expand Down Expand Up @@ -114,6 +157,19 @@ const opsRaw = (
)
).filter(Boolean).flatMap((r) => r.findings || [])

phase('React')
let reactDoctor = { ran: false, findings: [], note: 'skipped — react-doctor is orbit-ui-mobile-only (scope=api)' }
if (scope !== 'api') {
reactDoctor =
(await agent(reactDoctorPrompt(), {
label: 'react-doctor',
phase: 'React',
agentType: 'general-purpose',
effort: 'low',
schema: REACT_DOCTOR_SCHEMA,
})) || { ran: false, findings: [], note: 'react-doctor agent returned null (died/skipped) — treat as a Deferred coverage gap' }
}

phase('Verify')
const seriousOps = opsRaw.filter(isSeriousOps).sort((a, b) => rank(a.severity) - rank(b.severity))
const opsVerdicts = (
Expand Down Expand Up @@ -145,6 +201,7 @@ return {
scope,
audits: auditResults,
opsFindings,
reactDoctor,
opsChecksRun: OPS_CHECKS.map((c) => c.check),
opsDeferred: [
{ check: 'backups', reason: 'un-verifiable from a repo read — verify in the DB console: automated backups / PITR enabled AND a tested restore path' },
Expand Down
Loading