--- name: bworlds-check description: "Two-minute health check on one Build: pull telemetry, scan recent commits for struggle patterns, compare against the Dossier guardrails, run the First Look Audit. No interview, no deep dive. Use when the user says 'check this Build', 'how is [slug] doing', 'anything on fire', 'what changed since last time', or 'weekly check'. For a full audit with business context and a deep dive, use bworlds-audit instead." --- # Build health check Is anything on fire, and what changed? Everything here runs with your own credential through the `bworlds` CLI. Load `bworlds-cli` for the command contract, the exit codes, the safety rules and the Findings protocol step 8 follows. Every step is free except the Audit run in step 4, which debits the Workspace. The check never pushes to the Build's repository and never writes a file inside the clone. Its baseline lives in the Build Dossier, server-side per Build. ## Posture: assume you lack the full picture A check sees a clone and telemetry. It does not see intent, roadmap or environment. When something looks unfixed, incomplete or wrong, whether that is a fix that misses cases, an unauthenticated route, or a committed migration that may never have been applied, treat it as an observation to confirm and never as a verdict. There may be context the code does not carry: a route public on purpose, a policy applied out of band, a deferral someone chose deliberately. Give the Builder the benefit of the doubt. Write summaries and Findings as "here is what we see from the outside, did we miss something, or is there a reason?" rather than "you failed to do X". When a detection depends on context the code cannot show, such as whether that SQL ran in production or whether that route is public by design, set the Finding to `needs_user` with a `--decision-summary` asking for that context instead of asserting it as fact. ## Before you start ```bash bworlds build info ``` One call reports the Build's authorized areas, used in step 5, its Workspace's token balance, and whether GitHub is connected. If the balance is low, say so before running anything paid. ## 1. Load context ```bash bworlds repo clone bworlds dossier pull ``` `dossier pull` prints the operator workspace path and downloads the Dossier: the baseline from the last audit or check, retrieved from the server on any machine. Read `context.md` and `guardrails.md` from that path. You now know the app, its roles and its known risks. If the pull reports no Dossier, this is the first check on this Build. Report "no baseline yet" and continue. The check still works; it has nothing to compare against. ## 2. Pull telemetry ```bash bworlds telemetry errors bworlds telemetry sessions bworlds telemetry uptime ``` Report: - **Errors**: anything new? Recurring patterns? Filter out localhost noise. - **Sessions**: active usage or dormant? Rage clicks? Error-heavy sessions? - **Uptime**: any downtime or degraded periods? ## 3. Scan recent commits ```bash cd && git log --oneline -20 ``` Look for: - **Struggle patterns**: fix-on-fix cycles (`grep -iE "fix|bug|revert"`). - **Performance distress**: commits mentioning `timeout|slow|optimis|perf`. One hit means someone is already fighting a scaling problem. Inspect the queries those commits touched and raise it as a performance concern; never file it as routine feature work. - **Hot files**: files touched more than once in the last 20 commits. - **New migrations**: any schema change since the last check? - **Guardrail violations**: did a commit touch something a guardrail protects? If a guardrail says "never drop a foreign key", did a new migration drop one? ## 4. Run the First Look Audit ```bash bworlds audit run --confirm --json --wait-timeout 10m ``` This debits the Workspace. Say so and get agreement before running it; the rates are in `https://docs.bworlds.co/docs/reference/pricing`. Compare the new Control results against the previous AuditRun. The command must wait for the server-owned AuditRun, so `--no-wait` is unsuitable here: this step needs the settled result. ## 5. Read the authorized areas Take them from the `build info` output above: the `Authorized areas:` line, or `autoFixAuthorizedAreas` in `--json`. If the list is empty, recommend enabling areas. If step 3 found security-related commits, meaning migrations touching RLS, storage policies, auth or edge functions, make that recommendation more strongly. `autoFixAuthorizedAreas` scopes what you analyze and report: cover only the enabled areas and mention the gated-out ones. This field governs the in-app autofix agent's scope. It is not consent to push. The check is read-only on the repository whatever it contains. ## 6. Report A short summary, not an audit report: ``` ## [Slug] Health Check — [Date] **Status**: [healthy / attention needed / issues found] **Activity**: [N sessions in the last 7 days / dormant since DATE] **Errors**: [none / N new errors — summary] **Commits**: [N new commits, touching AREAS] **Audit**: [covered / attention / pending, changes: LIST — every count from the Audit output] **Areas**: [enabled: LIST / none enabled — recommend enabling] ### Attention needed (if any) - [One line per issue that needs a decision] ### Guardrail status - [Which guardrails still hold, which recent changes violated one] ``` A healthy Build is five lines. Only expand on what needs attention. ## 7. Update the guardrails If the check found new risks, add them to `guardrails.md` in the operator workspace, present them, then publish: ```bash bworlds dossier push --confirm ``` ## 8. Record what the check found as Findings Follow the six steps in `bworlds-cli` ("Writing Findings"). Three things a check decides for itself: - **Source ref**: `bworlds-check:{YYYY-MM-DD}:{risk-slug}`. - **Service line**: checks skew `run`-heavy, where audits skew `launch`-heavy. - **One `improve` Finding per check**, an overflow bound rather than a target. When the signal is real but the mechanism is not diagnosed, recommend a performance-focused `bworlds-audit` deep dive in the report instead of writing a speculative Finding. A confident diagnosis ships even without a local reproduction: a failed reproduction lowers certainty about the trigger, not about the prescription. Resolve a Finding this check verified fixed with `bworlds findings update-status resolved --reason "..." --confirm`.