--- name: bworlds-audit description: "Full technical audit of one Build you can operate: health check, codebase read, business context, targeted deep dive, then Findings the Builder can act on. Run it when a Build is new to you, before a milestone, or when someone asks what could break. Use when the user says 'audit this Build', 'what should we fix', 'is this ready to sell', 'review this app before launch', or 'onboard me onto this Build'. For a recurring two-minute check, use bworlds-check instead." --- # Build audit Read one Build end to end and leave behind what the next person needs: a prioritized report, Findings on the Build's Findings screen, and a Dossier that says how this app works and what must not break. 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. Reading is free. The only step that spends Workspace tokens is the Audit run inside the health check; each command below says so where it applies. The audit never pushes to the Build's repository and never writes a file inside the clone. What it learns persists in the Build Dossier and in Findings. ## Before you start ```bash bworlds build info ``` This one call reports the Build's authorized areas, its Workspace's token balance and whether GitHub is connected. If the balance is low, say so and get agreement before running anything paid. **Area gating.** `autoFixAuthorizedAreas` scopes what you analyze and report: go deep only on areas the Build enabled, and name the gated-out areas in the report. This field governs the in-app autofix agent's scope. It is not consent to push to the repository. The audit is read-only on the clone whatever it contains. ## Phase 1: Read the Build before asking anything ### 1.1 Run a health check Run `bworlds-check` through its report step, then stop. It clones the repository, pulls the Dossier, reads telemetry, scans recent commits and runs the First Look Audit. Read its output before going further. Stop it at its report. This skill writes the Findings for both, so letting the check reach its own step 8 files them twice. ### 1.2 Explore the codebase Go deeper than the check: - **Toolchain and Builder profile**: the slug encodes the tool (`-lovable`, `-bolt`, `-replit`). Cross-reference the git commit authors. All-agent commits mean a non-technical Builder; mixed commits mean a hands-on one. This sets the report's tone. - **App shape**: pages, components, hooks. A small CRUD app or a complex workflow tool? - **Schema**: tables, foreign keys, RLS policies per table. - **File health**: the largest files, cross-referenced with the hot files from the check. - **Auth model**: roles, permissions, the multi-tenancy pattern. - **Hot tables**: which tables the code queries most, cross-referenced with index coverage. - **Data-access shape**: how client code queries the database. Flag nested PostgREST embeds three levels deep or more, `select=*` on hot tables, unbounded `.in()` lists, statuses computed on read across joins, and RLS policies whose subqueries traverse other RLS-protected tables. These shapes work at demo scale and collapse as data grows. Report them as capacity risks even when nothing is failing yet. ### 1.3 Form hypotheses Synthesize into: - **3-5 risks** ranked by severity, each with its evidence. - **Struggle areas** from fix-on-fix patterns. - **Questions** that confirm or dismiss each risk. Present the summary before moving on. ## Phase 2: Establish the business context Code never says which flow cannot break, who is about to depend on it, or what the next three months look like. Without that, severity is a guess. Read `context.md` from the Dossier first (`bworlds dossier pull ` prints the workspace path; the health check already ran it). Ask only for what it does not answer. Lead with the struggle areas from 1.3 and with what you already inferred. ### What you need to know - **Users and growth**: how many users today, expected growth over three months, paying clients, any SLA. - **Critical workflow**: the one flow that cannot break, and what an hour of downtime on it costs. - **Pain points**: user complaints, past incidents, what is most frustrating right now. - **Technical decisions**: who changes the code, whether changes get reviewed, how migrations are handled. - **Growth plans**: next features, expected traffic spikes, new roles or pricing. ### Read the signals - "It works but sometimes it's slow" → performance. - "My clients sometimes can't see their data" → RLS gaps. - "I fixed that but it came back" → migration issues. - "I'm not sure what the AI tool changed" → no code review. - "I'm about to onboard a big client" → production pressure. ### Write `context.md` to the Dossier Write it now. Update `context.md` in the operator workspace, never inside the clone, then publish: ```bash bworlds dossier push --confirm ``` Under 30 lines: what the app is, its roles, its critical workflow, its key tables. The Dossier is latest-only with attribution, so push as soon as you edit it and nobody starts from a stale baseline. ## Phase 3: Targeted deep dive Pick 2-4 areas from Phase 1 and Phase 2 and the Build's authorized areas. Do not audit everything; go deep where this Build's business is exposed. ### Areas | Area | What to investigate | `--area` | |------|--------------------|----------| | **Security** | Authentication, authorization, data isolation, input handling, secrets | `security` | | **Data integrity** | Schema design, constraints, migrations, state consistency | `operations` | | **Performance and scalability** | Query efficiency, rendering, resource limits, capacity at 10x | `operations` | | **Reliability** | Error handling, monitoring, backup, deployment safety, external dependencies, platform posture | `operations` | | **Cost governance** | Uncapped API and LLM calls, storage growth, platform tier exposure | `operations` | | **Compliance and privacy** | Personal data handling, retention, GDPR and CCPA, cookie consent | `legal-compliance` | | **Code health** | Architecture coherence, dependency hygiene, test coverage, safe AI-assisted evolution | `code-quality` | Investigate only the areas the Build authorized, and report the gated-out ones. **Platform posture.** When hosting or the backend runs on a platform with no contractual availability or support commitment, treat it as a reliability risk scaled by stage: not worth reporting for a prototype or first users; medium (`improve`) once paying clients depend on the app; high (`launch`) with enterprise clients or customer-facing SLAs, and heavier when data and publishing live outside accounts the Builder owns. State only the platform's written commitments at the Build's tier: no uptime figures the vendor does not publish, and no "no SLA" claim where conditional Enterprise terms exist. Present the options, which are to accept and document, to buy a support tier where one exists, or to move the backend into accounts the Builder owns. Do not prescribe a migration. ### Deep dive protocol For an area that warrants real investigation, run 2-3 parallel agents in the background. Give each one the clone path and a single focused concern. Each must read the actual source and assume nothing about the framework or the stack. Security nearly always warrants one. Performance and scalability warrant one whenever Phase 1 surfaced traffic growth, performance-distress commits, or fragile data-access shapes. Data integrity and compliance sometimes do. **Quality bar for every finding:** - Above 80% confidence of real impact. Skip theoretical issues. - Every finding connects to this Build's context: what breaks, who is affected, which milestone is at risk. - File references are evidence inside the finding, never the finding itself. - Report what you checked and found clean alongside what you found broken. Wait for every agent. Deduplicate overlapping findings. Sort by severity. ### Write `guardrails.md` to the Dossier Turn the critical and high findings into guardrails. Update `guardrails.md` in the operator workspace, under 30 lines, never inside the clone, then publish: ```bash bworlds dossier push --confirm ``` Present both Dossier documents. ## The report For each finding: ``` ### [CRITICAL/HIGH/MEDIUM] Title **What we found**: one sentence with a file:line reference. **Why it matters**: one sentence tied to this Build's context, its upcoming milestone, its critical workflow, or its growth plans. If there is a milestone, say what happens if this hits during it. ``` Sort by priority. End with "What's working well." ## Record the outcome as Findings Every audit outcome becomes a Build-scoped Finding. Follow the six steps in `bworlds-cli` ("Writing Findings") after presenting the report. Four things an audit decides for itself: - **Source ref**: `bworlds-audit:{YYYY-MM-DD}:{risk-slug}`. - **Area**: from the area table above. - **Service line**: audits skew `launch`-heavy. Capacity and data-access Findings are `improve` unless they are already causing incidents, and then `run`. - **The bar for an `improve` Finding** is a judgment call: would you spend this Builder's attention on it today? Weigh the severity of the pattern against the evidence that it will bite. Usually that means citing both the pattern in the code and trajectory evidence inline, such as a latency trend, an error-class shift, performance-distress commits, or the growth plans from Phase 2. An egregious pattern clears the bar on its own. A textbook antipattern on a quiet Build with no growth in sight does not. Seeing a flaw and knowing it does not matter for this business yet is a reason to stay quiet. Three per audit is an overflow bound, not a target; it trims an unusually signal-rich run. Frame every description against what Phase 2 established: their milestone, their critical workflow, their growth plans. ## Tone Calibrate from the Builder profile inferred in Phase 1. - **Non-technical** (all-agent commits): business-impact language. - **Technical** (hand-written commits, custom code): precise technical language. Default to business impact. Never condescend. Frame everything as what can be improved.