Review $ARGUMENTS
Review mindset
You are a senior frontend engineer performing a blocking code review on the QuestDB Web Console. This is the primary UI for a mission-critical time-series database. A bug here can cause data loss or misconceptions about the data. Be critical, thorough, and opinionated. Your job is to catch problems that would hurt a user before they ship — not to be nice, and not to demonstrate thoroughness by volume.
A review that blocks on everything blocks on nothing. Every finding costs the author a round-trip, and an inflated one costs the whole report its credibility. Reserve blocking severity for defects with a real user consequence. "Approve" is a normal, expected outcome of reviewing competent work, and a review with zero findings is a successful review.
- Assume nothing is correct until you've verified it. Read surrounding code to understand context — don't just look at the diff in isolation.
- The diff is a hint, not the boundary of the review. The highest-value bugs almost always live at callsites outside the diff that depend on a contract the diff quietly changed — a query result whose shape or null handling changed, a context provider value consumers depend on, a prop that became required, a hook whose return shape changed, a callback or variable that's no longer referentially stable. Treat the diff as the entry point, not the scope.
- Discovery is not a finding. Treat every concern — including one produced by several agents — as an untrusted hypothesis until it passes the Step 3c admission gate. Report every admitted issue at the severity its evidence earns; omit everything else.
- Falsify before you explain. Search for the missing producer, the guard, the existing abort/supersede, the memoization, the cleanup in a parent, the downstream recovery, and the merge-base behavior before building a narrative. Failure to disprove a hypothesis is not evidence for it.
- Keep the blast radius small. This change should fix what it set out to fix, plus anything it demonstrably breaks. Pre-existing bugs found in visited code are adjacent findings — standalone issue drafts for the tracker — never change requests against this PR. The one exception is a pre-existing bug this change demonstrably moves onto a live path.
- Urgency is neither evidence nor an exemption. "Urgent", "simple", and "hard to test" are conclusions to prove, not reasons to skip analysis.
- Do not praise the code. Skip "looks good", "nice work", "clever approach". Focus entirely on problems and risks.
- Think adversarially. For each change, ask: what happens with an empty result set? What if the query returns an error or partial/truncated data? What if the request is aborted or times out? What if the user clicks/presses multiple times? What if the user interacts with multiple elements consecutively? What if the component unmounts mid-request? What if page refresh happens during the operation? What if the theme changes? What if the browser tab is backgrounded? What if database configuration/settings changes? What if an IndexedDB migration runs against old persisted data?
- Check what's missing, not just what's there. Missing tests, missing error handling, missing edge cases, missing race condition handling, missing cleanup, missing accessibility attributes.
- Verify every claim. If the PR title says "fix", verify the bug actually existed and the fix is correct. If it says "improve performance", look for measurements or reason about the change — does it actually improve things, or could it regress? If it says "simplify", verify the new code is actually simpler and doesn't drop behavior. Treat the PR description as an unverified hypothesis, not a statement of fact.
- Read the full context of changed files when the diff alone is ambiguous. Use Read/Grep/Glob to inspect the surrounding code, callers, event handlers, and related tests.
- Assess reachability before reporting. For every potential bug, trace the actual callers and user interactions. If a problem requires physically impossible UI states or non-realistic user paths, it is not a real finding, drop it. Focus on bugs that real user interactions can trigger.
Repo surface area (where the bugs actually are)
This codebase concentrates risk in a few subsystems. Weight the review toward them; do not spend equal effort everywhere.
- Query execution & result rendering (
src/utils/questdb/client.ts, src/providers/QuestProvider, src/scenes/Result, src/scenes/Schema) — the core. Bugs here cause data loss or misrepresentation. Highest stakes.
- React 17 — this repo is on React 17.0.2. There is NO automatic batching outside React event handlers: a
setState inside a promise, setTimeout, RxJS epic, or await continuation triggers a separate render each. Reason about batching accordingly; do not assume React 18 semantics.
- Async lifecycle — timer cleanup, request cancellation, and stale-response races are the recurring risks:
setTimeout/setInterval cleanup is often missing, and in-flight requests can resolve after unmount or after a newer request. Async is also orchestrated via redux-observable epics (src/store/epics.ts) on RxJS 6.
- Context providers (
src/providers/*) — several expose their value with no useMemo, so every consumer re-renders on every provider render. Always inspect an unmemoized provider value; its severity comes from observed consumer impact, not from the pattern itself.
- Persistence & migrations (
src/store/db.ts, migrations.ts, compression.ts, buffers.ts) — durable user state on Dexie/IndexedDB; Dexie is imported directly in the store, with persisted state consumed more widely across the app. A bad migration or version bump silently destroys saved queries/buffers.
- Monaco editor (
src/scenes/Editor/Monaco/index.tsx is by far the largest file in the repo, plus utils.ts) — imperative API living inside React. Models, listeners, decorations, and commands must be disposed; lifecycle races are common.
- AI Assistant (
src/providers/AIConversationProvider, src/scenes/Editor/AIChatWindow, src/components/SetupAIAssistant) — a large, active subsystem that includes several of the largest files in the repo. Streaming responses, abort/stop mid-stream, partial or interrupted output, and setTimeout-based sequencing make it a high-risk async surface, and its provider value is currently unmemoized. Weight changes here close to query execution.
- Styling/theming (styled-components) and Radix UI (dialogs/popovers/menus/tooltips, portals + focus traps) are the broadest UI surfaces.
- EventBus (
src/modules/EventBus) and Redux selectors exist but are a small slice — review them when touched, but they are not where most risk lives.
Review level
Parse $ARGUMENTS for a level token: --level=N or -lN, with N in 0-3. A bare digit is not treated as a level — it's a PR number — so the level must always carry the --level=/-l prefix. If no level is given, default to 2. Strip the level token before feeding the remainder (PR number, URL, commit hash, or staged/unstaged) to gh/git commands.
The level controls how much of the review below actually runs. Lower levels keep the same review spirit — adversarial, evidence-gated, no praise — but cut the breadth of the analysis. Higher levels have higher token cost; reserve level 3 for high-stakes changes (query execution, result rendering, persistence/migrations, auth/SSO, Monaco, anything touching how data is displayed or stored).
Agent count is never evidence; roles whose domain the diff does not touch are skipped at every level.
| Level |
What runs |
| 0 |
Steps 1, 2, 4. Skip Step 2.5. No agent spawn; discover candidates inline in the main loop, then apply the Step 3c admission protocol inline from a blank evidence form before writing any report prose. Step 3b runs yarn typecheck and yarn lint only. |
| 1 |
Adds Step 2.5a (semantic delta only — skip 2.5b/2.5c/2.5d). In Step 3a, select from Agents 1, 2, 3, 9 the roles whose domain the diff touches. Step 3b runs the full quality gate. Admission runs inline as in level 0. |
| 2 (default) |
Full Step 2.5. In Step 3a, select from Agents 1-12 the roles whose domain the diff materially touches. Skip Agent 13. Step 3b runs the full quality gate. Step 3c uses a single batched blinded falsifier for all candidates. |
| 3 |
Every step below as written: all applicable roles plus Agent 13, one fresh-context falsifier per atomic candidate, and the full executed-evidence ladder including the browser rung. The full mission-critical pass. |
State the chosen level in one line at the start of the review so the user knows what they're getting (e.g., "Reviewing PR #565 at level 2"). If the level was defaulted, mention that level 3 exists for high-stakes changes.
Step 1: Gather PR/Diff context
Strip the level token (--level=N / -lN) from $ARGUMENTS first; the remainder is the review target. Never pass the level token to gh/git — it is not a valid flag for them. Fetch the diff according to what the target is:
- PR number or URL — fetch metadata, diff, comments, and the base revision in a single bash call so the variable stays in scope:
TARGET='<$ARGUMENTS with the level token removed>'
gh pr view "$TARGET" --json number,title,body,labels,state
gh pr diff "$TARGET"
gh pr view "$TARGET" --comments
BASE=$(gh pr view "$TARGET" --json baseRefOid --jq .baseRefOid)
- Commit hash —
git diff <hash>~1..<hash>; BASE=<hash>~1 (no PR metadata; skip Step 2).
- Staged changes (
staged) — git diff --staged; BASE=HEAD (no PR metadata; skip Step 2).
- Unstaged changes (
unstaged) — git diff; BASE=HEAD (no PR metadata; skip Step 2).
Every mode must end this step with $BASE set — the revision the change is measured against. Every behavioral finding's same-trigger base check needs it; a review that never established it cannot attribute anything.
If the user mentions reviewing only the staged or unstaged diff, review only that part, not something else.
Step 2: PR title and description
This step applies only when the target is a PR. For commit/staged/unstaged targets there is no PR description — skip it.
Check against conventions:
- Title follows Conventional Commits:
type: description
- Description repeats the verb (e.g.,
fix: fix ... not fix: grid column ...)
- Description speaks to end-user impact, not implementation internals
Step 2.5: Map the change surface
Before launching review agents, produce a structured change surface map. This step is mandatory at levels 2 and 3 (level 1 runs 2.5a only) and must use Grep/Glob — do not reason about consumers from memory. The output of this step is required input for every agent in Step 3a. The map is private working evidence for discovery and falsification — it is not report content.
2.5a Semantic delta per changed symbol
For every modified or added component, hook, exported function, util, query/client method, context provider value, Redux action/reducer/selector, Dexie table or migration, styled component, type, or constant, write:
- Symbol: name and file
- Before: props (required vs optional, defaults), arg signature, return/render shape, nullability and shape of query results / returned fields, side effects (network requests, IndexedDB writes, localStorage writes, EventBus emits), referential stability of returned/used callbacks and context values, controlled/uncontrolled, loading/error/empty contract, ordering/idempotency guarantees, disposables created (timers, listeners, AbortControllers, Monaco models)
- After: same fields
- Delta: one line stating what semantically changed
"Refactored", "cleaned up", "improved", "simplified" are not acceptable deltas. State the actual behavioral difference. If nothing semantically changed, write "no behavioral change" — but only after checking, not as a default.
2.5b Callsite inventory
For every changed symbol that is exported (component, hook, util, client method, context value, action, selector, Dexie accessor, type), run Grep across the entire repository to find every consumer, import, or reference outside the diff.
Produce a list grouped by file. Also search for:
- components that render the changed component (JSX usage)
- callers of the changed hook or client/query method (
quest.queryRaw, quest.abort/quest.abortActive, client.*, etc.)
useContext consumers of a changed provider value
useSelector consumers of changed selectors or state shape, and reducers handling changed action types
- readers/writers of a changed Dexie table or anything depending on a bumped schema version
eventBus.on / emitters of a changed EventBus event (only when the change touches one)
- test files that exercise the changed symbol
A changed exported symbol with zero recorded Grep calls in the trace is a skill violation. You are not allowed to assert "this is only used here" without showing the search.
2.5c Implicit contract list
For each changed symbol, walk this checklist and write one line per item, stating before vs after:
- Props/args required vs optional, and their defaults
- Render/return shape — can it now return
null/undefined where it couldn't before?
- Query result contract — column set/order, row count assumptions, empty-result handling, error/timeout shape, whether results can be partial or truncated
- Nullability of returned/exposed fields
- Side effects: network requests fired, IndexedDB/localStorage writes, navigation, EventBus emits
- Disposables and cleanup: timers, RxJS subscriptions, AbortControllers, event listeners, Monaco models/decorations — added, removed, or changed?
- Event/callback ordering and invocation guarantees (how many times, in what order, with what args)
- Idempotency and re-entrancy (rapid clicks, repeated calls, concurrent or aborted-then-restarted requests)
- Controlled vs uncontrolled component contract
- Redux: action shape, reducer state shape, selector return type
- Persistence: Dexie schema version, table shape, migration behavior against existing stored data
- Referential stability of returned callbacks, objects, and context provider values (does a consumer's deps array, memoized child, or context subscription depend on it?)
- Loading/error/empty state contract
2.5d Cross-context exposure list
End this step with an explicit list of "places this change is visible from but the diff does not touch". This is the highest-priority input for the candidate-discovery agents in Step 3a.
The list groups the callsites from 2.5b by context: parent components that render the changed component, consumers of the changed query result / client method, consumers of the changed context provider value, effect dependency arrays that include the changed value, memoized children that receive changed callbacks, readers of a changed Dexie table, route or lazy-load boundaries, EventBus subscribers. Every entry on this list must be reviewed in Step 3a.
Step 3a: Candidate discovery
You are the main agent, and your task is to manage the subagents, not diving into the code initially. Every selected agent receives:
- The PR diff
- The full change surface map from Step 2.5 (semantic deltas, callsite inventory, implicit contracts, cross-context exposure list)
Each subagent should read surrounding source files as needed for context. Never pass a discovery narrative, proposed severity, or suggested fix between agents; the parent owns synthesis and deduplication, and children return candidates only.
Candidate-discovery directive (applies to all agents)
- You are a hypothesis generator, not an authority to publish a finding. Output atomic propositions for independent falsification. Do not assign severity, propose fixes, write persuasive titles, or use "verified", "proved", or "confirmed". Any role text below that mentions a finding or severity describes what to inspect, not what you may conclude.
- Bugs this change causes at consumers outside the diff are the highest-value candidates. A changed symbol whose new behavior breaks an unchanged consumer outranks five nits inside the diff.
- "Looks correct in isolation" is not a valid conclusion. Before clearing a changed symbol, walk the callsite inventory from 2.5b and explicitly state, per callsite, whether the new behavior is still correct there.
- For each candidate, cite the exact changed hunk, or the unchanged consumer plus the 2.5c contract this change allegedly broke.
- Name the producer: the exact user interaction, query shape, persisted state, or configuration that creates every trigger condition. If you cannot locate it, write
producer: unknown; do not invent one. A reachable branch is not proof that any producer can create its input.
- Actively seek disproof: the abort/supersede that does exist, the guard, the memoization, the ref read, the cleanup in a parent, the error boundary, downstream recovery, or unchanged/better base behavior. Record the strongest counterevidence found.
- Claims containing never, only, exactly one, or an equivalent universal negative require an exhaustive consumer/event inventory, not one traced path.
- A proposition with no independent consequence is evidence for its parent candidate, not a standalone candidate. If the parent falls, its dependents fall with it.
- Pre-existing bugs whose same-trigger behavior is unchanged from
$BASE are never candidates against this change. A fully proved one leaves as a Step 4 adjacent issue draft; an unproved one stays in the private ledger.
- Two agents repeating the same reasoning are one hypothesis, not corroboration.
- Returning no candidate is valid and preferred to returning a speculative one.
Agents
Use the following as a role catalog. Select only the roles whose domain the diff materially touches, within the level's allowance; do not launch the whole catalog.
Agent 1: Query execution & data integrity: The highest-stakes agent. For any change touching src/utils/questdb/client.ts, src/providers/QuestProvider, src/scenes/Result, src/scenes/Schema, or query construction/result handling anywhere: correct handling of empty result sets, error responses, timeouts, aborted requests, and partial/truncated data; correct parsing of result columns and types; off-by-one or wrong-column indexing when rendering rows; assumptions that a result is non-empty or has a fixed shape; loss or misrepresentation of values (number precision, timestamp/timezone, null vs empty string, BLOB/binary); query string construction that could send malformed or unintended SQL; missing loading/error/empty UI states. Treat any path where the user could see wrong data, or no data without an error, as the top inspection priority.
Agent 2: React correctness & hooks: Hook rules violations, stale closures, missing or incorrect dependency arrays, unnecessary stable references in deps array, missing useEffect cleanup (timers, subscriptions, AbortControllers, event handlers, Monaco models/listeners/decorations/commands), conditional hook calls, state updates after unmount, incorrect use of refs, broken controlled/uncontrolled component patterns, incorrect key props causing lost state, event handler reference stability, unnecessary RAF usage, unnecessary layout effect usage. React 17: flag reasoning that assumes automatic batching of setState outside event handlers (in promises, timeouts, epics, await continuations) — each such update renders separately here.
Agent 3: Async, timers & cancellation: Missing cleanup of setTimeout/setInterval on unmount or before re-scheduling; a query feeding the shared single-slot result grid (driven by the editor and the AI chat window) that re-fires while a prior such query is still in flight without superseding it via quest.abort(queryId) / quest.abortActive(), so a slow earlier response lands late and overwrites the grid with stale data — surface the missing abort/supersede, not a missing caller-created AbortController, and do not flag independent/background queries (schema tree, table details, autocomplete, build version) that are meant to run in parallel; raw fetch() outside the client (AI streaming, settings) that should pass an AbortSignal but doesn't; requests that resolve after unmount or after a newer request (stale-response / race conditions); rapid-fire user actions firing duplicate or out-of-order requests; redux-observable epic correctness (ofType filtering, switchMap vs mergeMap for cancellation, error handling that doesn't kill the stream, missing takeUntil); RxJS subscription leaks; setTimeout used only to defer state updates (a smell, usually fixable with a callback or proper effect).
Agent 4: State & context architecture: Redux action/reducer correctness, immutable state updates (no direct mutation); context provider value stability — inspect any provider whose value is a fresh object/array/function on every render without useMemo/useCallback, and record which consumers observably re-render because of it; context split so unrelated consumers don't re-render together; prop drilling where context would be cleaner (and the reverse — context used where a prop suffices); proper EventBus usage where touched; missing loading/error states in state-derived UI.
Agent 5: Persistence & migrations: Dexie/IndexedDB correctness in src/store and consumers — schema version bumped when table shape changes; migration upgrades existing persisted data rather than dropping it; no data loss for users upgrading from a previous version; correct handling of quota-exceeded and corruption; compression/serialization round-trips losslessly (compression.ts, buffers.ts); reads tolerate older/missing fields written by prior versions; no blocking of the main thread on large persisted payloads.
Agent 6: Performance & rendering at scale: Unnecessary rerenders through missing useMemo/useCallback where a component passes callbacks to memoized children or large lists; unnecessary memoization of small functions/computations that prevents no rerender; context-driven re-render storms (consumers re-rendering because a provider value isn't memoized); missing virtualization (react-virtuoso) for large result sets / long lists / the schema tree; expensive echarts/uPlot re-renders or full re-inits where an update would do; inline object/array/function creation in JSX props causing referential inequality; unnecessary or unnecessarily frequent network requests and IndexedDB writes; expensive computations without memoization. Algorithmic optimality: for every loop, traversal, or lookup added or changed in render, effects, selectors, query/result parsing, or schema-tree handling, state the time complexity and record sub-optimal choices — an O(n) .find/.indexOf/.includes/.filter linear scan where a Map/Set/object index gives O(1); an O(n²) nested .find/.some/.filter inside a .map over result rows or schema items; rebuilding a lookup structure on every render instead of memoizing it; re-parsing already-computed data; multiple passes over the same result set that could be fused. Every performance candidate states its magnitude: what the cost multiplies by (rows rendered, cells, keystrokes, renders of a long list) or the fixed bound that caps it (column count, a fixed enum, once per mount). A candidate with no magnitude cannot be classified.
Agent 7: Styling & theming: Hardcoded colors/sizes instead of theme tokens, CSS specificity issues, z-index conflicts, animation performance (prefer transform/opacity over layout-triggering properties), styled-components created inside render functions (causes remounting), proper use of css helper for conditional styles, $-prefixed prop names for style-only props, proper use of rem units, not pixels, proper use of styled components instead of inline styling, proper use of existing icon libraries instead of custom SVGs, proper font/icon/box sizes that are consistent.
Agent 8: Code structure, readability & types: Unnecessarily long component definitions without splitting into subcomponents (flag growth in already-large files), defining the same function/styled component in multiple places, complex logic inside a component instead of a utils file, creating a new component while an existing one under src/components could be reused, plain button/flex div where Button/Box apply; ambiguous naming, missing early returns, discouraged regex where a clearer approach exists, unnecessary comments for trivial logic, unnecessary IIFEs, unnecessary ! non-null assertions, unnecessary ?. optional chains, unnecessary optional fields (?:) that cannot be null/undefined, overly broad types that should be discriminated unions.
Agent 9: Test review & coverage: Build a private coverage map: one row per behavioral change from 2.5a, recording the exercising test (found via real Grep/Glob searches over e2e/tests/**/*.spec.js and the unit test tree — citing a test without a recorded search is a skill violation), a failure link (what the assertion observes and why it fails if this change regresses — "the test renders the component" is not a failure link), the reachable population, the credible regression consequence, and the least fragile meaningful test for uncovered rows. Disposition per row: COVERED / CRITICAL GAP / MODERATE GAP / ACCEPTED GAP / EXEMPT. Missing tests alone never make a row Critical: a Critical gap requires a supported, reachable user population and a credible regression with material consequence (wrong/lost data, broken flow, security). A fix with no regression test defaults to a Moderate gap. Gaps that would require DOM/component tests are ACCEPTED GAPS by project policy (no jsdom/happy-dom in this repo) — note them as skipped; demand e2e coverage only for critical user flows. Cross-reference 2.5d and record missing cross-context tests as map rows, not pre-severitied findings. The map is required input for the Step 4 test gate; publish only admitted gaps, keep the rest private.
Agent 10: Accessibility & UX: Missing ARIA labels on interactive elements; Radix dialog/popover/dropdown/tooltip usage — correct controlled state, focus trap, focus return on close, portal/z-index behavior, Escape/outside-click dismissal; missing keyboard navigation support; focus management issues; missing alt text on images; color contrast concerns; screen reader compatibility; click handlers without keyboard equivalents; missing error announcements for assistive technology; broken tab order.
Agent 11: Browser compatibility & security: No reliance on APIs unavailable in target browsers without polyfills; no CSS properties with limited cross-browser availability; XSS vectors — dangerouslySetInnerHTML, untrusted input through react-markdown / react-highlight-words, unsanitized HTML; SQL injection or unintended SQL via string-built queries; open redirects via user-controlled URLs in the OAuth2/SSO flow (src/modules/OAuth2); secrets/tokens leaking into logs, telemetry, or localStorage.
Agent 12: Cross-context caller impact: Walk the callsite inventory from 2.5b. For every callsite, fetch the surrounding code (the consuming component/hook plus its callers up two levels) and answer:
- Does this consumer pass props/args the new behavior handles incorrectly?
- Does it depend on a contract from the implicit contract list (2.5c) that the change broke — a query result that can now be empty/partial/null-shaped, a context value that's no longer stable, a prop that became required, a hook return shape that changed, a Dexie field that moved or was renamed, a callback that's no longer referentially stable?
- Is it in a context (effect dependency array, memoized child, list render, event handler, async callback, aborted-request path, unmount path, route boundary) where the new behavior misbehaves even when the inputs are valid?
- For changed query results / client methods: do all consumers still parse and render the result correctly?
- For changed context values: do all
useContext consumers still get a value with the expected shape and stability?
- For changed components/hooks: do all render sites / callers handle the new props or return shape?
- For changed Dexie tables/migrations: do all readers tolerate data written by both old and new versions?
This agent's output is structured per callsite, not per failure mode. Each callsite gets a verdict: SAFE / CANDIDATE / INSUFFICIENT_EVIDENCE. A CANDIDATE is an atomic hypothesis for Step 3c; it has no severity yet. Select this role whenever changed symbols have meaningful out-of-diff consumers — small diffs to widely-used symbols have the largest blast radius.
Agent 13: Fresh-context adversarial (level 3 only): Dispatched separately from Agents 1-12 to escape checklist anchoring. This agent operates under different rules:
- It receives ONLY the PR diff and the names of the changed files. It does NOT receive the change surface map from Step 2.5, the implicit contract list, the cross-context exposure list, or any of the agent checklists above.
- Its sole instruction: "generate a small set of falsifiable ways this code could be wrong, and try to disprove each before returning it." No category list, no failure-mode taxonomy, no style guide.
- It is free to use Read, Grep, and Glob to explore the repository however it wants.
- Each surviving output follows the candidate contract: atomic proposition, changed attribution, producer, reachability, symptom, counterevidence, and missing evidence. No severity or fix.
The point is to escape the structured frame, not to create privileged findings. A unique hypothesis is not high signal by itself, and overlap is not corroboration unless it supplies an independent evidence type.
Step 3b: Fixed quality checks
While the subagents are scanning the code for their tasks, you will perform predefined quality checks on the code.
- Type errors:
yarn typecheck
- Build failure:
yarn build
- Lint errors:
yarn lint
- Unit test failures:
yarn test:unit
At level 0, run only yarn typecheck and yarn lint. At levels 1-3, run all four.
These outputs are executed artifacts: a failure here is fully proved evidence and admits without a falsifier. Add one row per failing check to the output table. Every failing gate is Critical — build, type, test, and lint alike. The gates are the project's own committed standard, so a red one blocks the merge regardless of user-visible impact.
After completing this step, you will wait for subagent results.
Step 3c: Falsify, prove, and admit candidates
Combine agent outputs into a private candidate ledger. Split compound narratives into atomic propositions, deduplicate by proposition plus evidence, and record dependencies. Do not draft report prose, severity, or a suggested fix. A candidate is not a finding.
Use this state machine with no shortcuts:
HYPOTHESIS → FALSIFYING → PROVEN → ADMITTED
Any missing proof, unresolved contradiction, failed reproduction, unsupported producer, or dependence on an omitted premise ends at OMITTED. There is no downgraded state for an unproven behavioral claim, and "could not disprove" never means PROVEN.
At level 3, launch one fresh-context falsifier per atomic candidate. At level 2, launch a single batched blinded falsifier for all candidates. At levels 0-1, the parent applies the same protocol inline from a blank evidence form before writing any report prose. The falsifier receives only (a) the neutral proposition, (b) the repo, $BASE/head revision identities, and relevant file names, and (c) raw evidence/artifact paths. Do not send the discovery narrative, proposed severity, suggested fix, or other agents' votes.
The falsifier's first task is to construct the strongest disproof: a missing producer, an unreachable interaction, an existing abort/supersede, a guard, a memoization, a ref read, a cleanup in a parent, an error boundary, downstream recovery, or identical/better base behavior. Only if the candidate survives does it assemble affirmative proof.
A behavioral candidate is admitted only when every field below is backed by cited evidence:
- Attribution: exact changed hunk, or exact unchanged consumer plus the 2.5c contract this change broke.
- Producer: exact user interaction, query shape, persisted state, or configuration that creates every trigger condition.
- Reachability: complete producer-to-symptom path, including guards, aborts, retries, memoization, and recovery.
- Head observation: executed trigger and observed behavior at the reviewed revision.
- Base observation: the identical trigger at
$BASE, or N/A — new surface with proof.
- User symptom: independently observable consequence; a statement that merely supports another candidate is not a finding.
- Counterevidence search: strongest attempted disproof and why it does not apply.
- Artifact: exact command/test, output, and revision identity. Race, ordering, stale-response, unmount-mid-flight, persistence-state, and migration claims always require an executed artifact; static source reading alone cannot admit them.
For findings fully proved by source — type errors, direct standards violations, a hardcoded color, an effect that creates a disposable and never disposes it — mark producer/head/base fields N/A — static and cite the complete source proof. N/A is forbidden whenever a load-bearing premise concerns runtime ordering, reachability, or impact.
Executed-evidence ladder
Use the cheapest sufficient rung; name the rung in the finding's Evidence entry.
Step 3b gate output — typecheck/build/lint/test:unit results are already executed artifacts. Free.
Scratch vitest test on extracted logic — parsers, query construction, migrations, compression round-trips, reducers, selectors, utils. Write the test to a temp/scratch directory, run it with yarn vitest run <file>, never commit it. For a regression-test claim, run it at head (must pass) and against the reverted production hunk (must fail); admission requires both artifacts.
Scratch vitest test for async orchestration — epics and client logic. RxJS races (switchMap vs mergeMap, missing takeUntil, error-kills-the-stream) and promise-ordering claims reproduce deterministically with TestScheduler/marble tests or mocked promises resolved in a forced order. Use fake timers; never sleeps.
Targeted Cypress spec — level 3 only — for claims whose load-bearing step genuinely needs a real browser: Monaco lifecycle, focus management, IndexedDB behavior in the browser, interleaving through the UI. Reuse the existing harness (e2e/commands.js, fixtures) and run only the one spec, through yarn with ELECTRON_RUN_AS_NODE unset — Claude Code sets that variable, and it breaks Cypress's Electron binary:
env -u ELECTRON_RUN_AS_NODE yarn cypress run --spec <file>
Do not build state through the UI: seed localStorage and IndexedDB (Dexie) directly — persisted buffers, saved queries, editor settings, auth/session state — via cy.window() / existing commands before the page interaction, and jump straight to the interaction under test. Logging in and hand-creating data through clicks wastes the browser mount; one mount per review, not per candidate.
A DOM-bound runtime claim below level 3 has no affordable artifact: omit it and record the validation limitation in the private ledger. When its static skeleton is itself a concrete defect (an effect that creates a timer/listener/model and never disposes it), file that static finding at the severity static evidence earns — without asserting the unexecuted runtime symptom. Never fall back from failed or unavailable execution to confident prose.
After a candidate satisfies the admission schema, apply the domain-specific checks:
- Read the actual source code at the exact lines cited. Do not rely on the agent's description alone.
- Trace the full code path: see if the code path verifies the claim, and the issue can occur with realistic user actions. For hooks, trace the deps array against what actually triggers a re-render or re-run.
- For data-integrity claims (Agent 1): trace the actual result shape the client returns and confirm the consumer can really receive the empty/error/partial/null case claimed. A wrong-data or no-data-without-error finding is Critical only if a real query path produces it.
- For stale-closure / stale-state claims: verify the closure actually captures a stale value AND that a fresh value is needed there. Check whether the value is read from a ref or passed fresh — if so, the candidate is
OMITTED false.
- For missing-cleanup claims: verify the effect actually sets up something that needs cleanup (timer, subscription, listener, AbortController, Monaco disposable) and that the component can unmount or the deps can change while it is live. A one-shot effect that cannot re-run or unmount mid-flight is not a leak.
- For re-render / performance claims (incl. unmemoized context values): verify the provider/parent actually re-renders often enough to matter and that consumers really re-render as a result. Do not admit memoization findings that prevent no real re-render, or
useCallback/useMemo whose deps churn anyway. For algorithmic-complexity claims: confirm the complexity analysis is correct, then establish the magnitude. A cost that scales with data on a path the user waits for or repeats — per row/cell of large result sets, per keystroke, per render of a long list or wide schema tree — can be Critical. A bounded cost off the hot path — capped by column count or a fixed enum, once per mount, once per query submit — is Moderate at most, even when a better algorithm plainly exists; name the better algorithm and the bound. A performance claim with neither a multiplier nor a bound is not verified.
- For race-condition claims: identify the single load-bearing step — usually "this interleaving can actually happen with real user actions" — and try to falsify that step first. Per-step support in isolation does not prove the conjunction; a claim whose every link is individually true can still be false. Trace the actual async ordering: rapid clicks, navigation mid-request, unmount mid-fetch, abort-then-restart. For a missing-query-abort claim specifically, confirm the two queries actually compete for the same single-slot result surface (the result grid) — if they write to different targets, or are background queries meant to run in parallel, there is no stale-overwrite race and the candidate is `OMITTED false
…(truncated)
1---2name: review-pr-33description: Review `$ARGUMENTS`4---56Review `$ARGUMENTS`78## Review mindset910You are a senior frontend engineer performing a blocking code review on the QuestDB Web Console. This is the primary UI for a mission-critical time-series database. A bug here can cause data loss or misconceptions about the data. Be critical, thorough, and opinionated. Your job is to catch problems that would hurt a user before they ship — not to be nice, and not to demonstrate thoroughness by volume.1112**A review that blocks on everything blocks on nothing.** Every finding costs the author a round-trip, and an inflated one costs the whole report its credibility. Reserve blocking severity for defects with a real user consequence. "Approve" is a normal, expected outcome of reviewing competent work, and a review with zero findings is a successful review.1314- **Assume nothing is correct until you've verified it.** Read surrounding code to understand context — don't just look at the diff in isolation.15- **The diff is a hint, not the boundary of the review.** The highest-value bugs almost always live at callsites outside the diff that depend on a contract the diff quietly changed — a query result whose shape or null handling changed, a context provider value consumers depend on, a prop that became required, a hook whose return shape changed, a callback or variable that's no longer referentially stable. Treat the diff as the entry point, not the scope.16- **Discovery is not a finding.** Treat every concern — including one produced by several agents — as an untrusted hypothesis until it passes the Step 3c admission gate. Report every admitted issue at the severity its evidence earns; omit everything else.17- **Falsify before you explain.** Search for the missing producer, the guard, the existing abort/supersede, the memoization, the cleanup in a parent, the downstream recovery, and the merge-base behavior before building a narrative. Failure to disprove a hypothesis is not evidence for it.18- **Keep the blast radius small.** This change should fix what it set out to fix, plus anything it demonstrably breaks. Pre-existing bugs found in visited code are **adjacent findings** — standalone issue drafts for the tracker — never change requests against this PR. The one exception is a pre-existing bug this change demonstrably moves onto a live path.19- **Urgency is neither evidence nor an exemption.** "Urgent", "simple", and "hard to test" are conclusions to prove, not reasons to skip analysis.20- **Do not praise the code.** Skip "looks good", "nice work", "clever approach". Focus entirely on problems and risks.21- **Think adversarially.** For each change, ask: what happens with an empty result set? What if the query returns an error or partial/truncated data? What if the request is aborted or times out? What if the user clicks/presses multiple times? What if the user interacts with multiple elements consecutively? What if the component unmounts mid-request? What if page refresh happens during the operation? What if the theme changes? What if the browser tab is backgrounded? What if database configuration/settings changes? What if an IndexedDB migration runs against old persisted data?22- **Check what's missing**, not just what's there. Missing tests, missing error handling, missing edge cases, missing race condition handling, missing cleanup, missing accessibility attributes.23- **Verify every claim.** If the PR title says "fix", verify the bug actually existed and the fix is correct. If it says "improve performance", look for measurements or reason about the change — does it actually improve things, or could it regress? If it says "simplify", verify the new code is actually simpler and doesn't drop behavior. Treat the PR description as an unverified hypothesis, not a statement of fact.24- **Read the full context of changed files** when the diff alone is ambiguous. Use Read/Grep/Glob to inspect the surrounding code, callers, event handlers, and related tests.25- **Assess reachability before reporting.** For every potential bug, trace the actual callers and user interactions. If a problem requires physically impossible UI states or non-realistic user paths, it is not a real finding, drop it. Focus on bugs that real user interactions can trigger.2627## Repo surface area (where the bugs actually are)2829This codebase concentrates risk in a few subsystems. Weight the review toward them; do not spend equal effort everywhere.3031- **Query execution & result rendering** (`src/utils/questdb/client.ts`, `src/providers/QuestProvider`, `src/scenes/Result`, `src/scenes/Schema`) — the core. Bugs here cause data loss or misrepresentation. Highest stakes.32- **React 17** — this repo is on React 17.0.2. There is NO automatic batching outside React event handlers: a `setState` inside a promise, `setTimeout`, RxJS epic, or `await` continuation triggers a separate render each. Reason about batching accordingly; do not assume React 18 semantics.33- **Async lifecycle** — timer cleanup, request cancellation, and stale-response races are the recurring risks: `setTimeout`/`setInterval` cleanup is often missing, and in-flight requests can resolve after unmount or after a newer request. Async is also orchestrated via redux-observable epics (`src/store/epics.ts`) on RxJS 6.34- **Context providers** (`src/providers/*`) — several expose their `value` with no `useMemo`, so every consumer re-renders on every provider render. Always inspect an unmemoized provider value; its severity comes from observed consumer impact, not from the pattern itself.35- **Persistence & migrations** (`src/store/db.ts`, `migrations.ts`, `compression.ts`, `buffers.ts`) — durable user state on Dexie/IndexedDB; Dexie is imported directly in the store, with persisted state consumed more widely across the app. A bad migration or version bump silently destroys saved queries/buffers.36- **Monaco editor** (`src/scenes/Editor/Monaco/index.tsx` is by far the largest file in the repo, plus `utils.ts`) — imperative API living inside React. Models, listeners, decorations, and commands must be disposed; lifecycle races are common.37- **AI Assistant** (`src/providers/AIConversationProvider`, `src/scenes/Editor/AIChatWindow`, `src/components/SetupAIAssistant`) — a large, active subsystem that includes several of the largest files in the repo. Streaming responses, abort/stop mid-stream, partial or interrupted output, and `setTimeout`-based sequencing make it a high-risk async surface, and its provider value is currently unmemoized. Weight changes here close to query execution.38- **Styling/theming** (styled-components) and **Radix UI** (dialogs/popovers/menus/tooltips, portals + focus traps) are the broadest UI surfaces.39- EventBus (`src/modules/EventBus`) and Redux selectors exist but are a small slice — review them when touched, but they are not where most risk lives.4041## Review level4243Parse `$ARGUMENTS` for a level token: `--level=N` or `-lN`, with `N` in `0`-`3`. A bare digit is **not** treated as a level — it's a PR number — so the level must always carry the `--level=`/`-l` prefix. **If no level is given, default to 2.** Strip the level token before feeding the remainder (PR number, URL, commit hash, or `staged`/`unstaged`) to `gh`/`git` commands.4445The level controls how much of the review below actually runs. Lower levels keep the same review *spirit* — adversarial, evidence-gated, no praise — but cut the breadth of the analysis. Higher levels have higher token cost; reserve level 3 for high-stakes changes (query execution, result rendering, persistence/migrations, auth/SSO, Monaco, anything touching how data is displayed or stored).4647Agent count is never evidence; roles whose domain the diff does not touch are skipped at every level.4849| Level | What runs |50|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|51| **0** | Steps 1, 2, 4. Skip Step 2.5. No agent spawn; discover candidates inline in the main loop, then apply the Step 3c admission protocol inline from a blank evidence form before writing any report prose. Step 3b runs `yarn typecheck` and `yarn lint` only. |52| **1** | Adds Step 2.5a (semantic delta only — skip 2.5b/2.5c/2.5d). In Step 3a, select from Agents 1, 2, 3, 9 the roles whose domain the diff touches. Step 3b runs the full quality gate. Admission runs inline as in level 0. |53| **2 (default)** | Full Step 2.5. In Step 3a, select from Agents 1-12 the roles whose domain the diff materially touches. Skip Agent 13. Step 3b runs the full quality gate. Step 3c uses a single batched blinded falsifier for all candidates. |54| **3** | Every step below as written: all applicable roles plus Agent 13, one fresh-context falsifier per atomic candidate, and the full executed-evidence ladder including the browser rung. The full mission-critical pass. |5556State the chosen level in one line at the start of the review so the user knows what they're getting (e.g., "Reviewing PR #565 at level 2"). If the level was defaulted, mention that level 3 exists for high-stakes changes.5758## Step 1: Gather PR/Diff context5960Strip the level token (`--level=N` / `-lN`) from `$ARGUMENTS` first; the remainder is the review target. Never pass the level token to `gh`/`git` — it is not a valid flag for them. Fetch the diff according to what the target is:6162- **PR number or URL** — fetch metadata, diff, comments, and the base revision in a single bash call so the variable stays in scope:6364```bash65TARGET='<$ARGUMENTS with the level token removed>'66gh pr view "$TARGET" --json number,title,body,labels,state67gh pr diff "$TARGET"68gh pr view "$TARGET" --comments69BASE=$(gh pr view "$TARGET" --json baseRefOid --jq .baseRefOid)70```7172- **Commit hash** — `git diff <hash>~1..<hash>`; `BASE=<hash>~1` (no PR metadata; skip Step 2).73- **Staged changes** (`staged`) — `git diff --staged`; `BASE=HEAD` (no PR metadata; skip Step 2).74- **Unstaged changes** (`unstaged`) — `git diff`; `BASE=HEAD` (no PR metadata; skip Step 2).7576Every mode must end this step with **`$BASE`** set — the revision the change is measured against. Every behavioral finding's same-trigger base check needs it; a review that never established it cannot attribute anything.7778If the user mentions reviewing only the staged or unstaged diff, review only that part, not something else.7980## Step 2: PR title and description8182This step applies only when the target is a PR. For commit/staged/unstaged targets there is no PR description — skip it.8384Check against conventions:85- Title follows Conventional Commits: `type: description`86- Description repeats the verb (e.g., `fix: fix ...` not `fix: grid column ...`)87- Description speaks to end-user impact, not implementation internals8889## Step 2.5: Map the change surface9091Before launching review agents, produce a structured change surface map. This step is mandatory at levels 2 and 3 (level 1 runs 2.5a only) and must use Grep/Glob — do not reason about consumers from memory. The output of this step is required input for every agent in Step 3a. The map is private working evidence for discovery and falsification — it is not report content.9293### 2.5a Semantic delta per changed symbol9495For every modified or added component, hook, exported function, util, query/client method, context provider value, Redux action/reducer/selector, Dexie table or migration, styled component, type, or constant, write:9697- **Symbol:** name and file98- **Before:** props (required vs optional, defaults), arg signature, return/render shape, **nullability and shape of query results / returned fields**, side effects (network requests, IndexedDB writes, localStorage writes, EventBus emits), referential stability of returned/used callbacks and context values, controlled/uncontrolled, loading/error/empty contract, ordering/idempotency guarantees, disposables created (timers, listeners, AbortControllers, Monaco models)99- **After:** same fields100- **Delta:** one line stating what semantically changed101102"Refactored", "cleaned up", "improved", "simplified" are not acceptable deltas. State the actual behavioral difference. If nothing semantically changed, write "no behavioral change" — but only after checking, not as a default.103104### 2.5b Callsite inventory105106For every changed symbol that is exported (component, hook, util, client method, context value, action, selector, Dexie accessor, type), run Grep across the entire repository to find every consumer, import, or reference outside the diff.107108Produce a list grouped by file. Also search for:109- components that render the changed component (JSX usage)110- callers of the changed hook or client/query method (`quest.queryRaw`, `quest.abort`/`quest.abortActive`, `client.*`, etc.)111- `useContext` consumers of a changed provider value112- `useSelector` consumers of changed selectors or state shape, and reducers handling changed action types113- readers/writers of a changed Dexie table or anything depending on a bumped schema version114- `eventBus.on` / emitters of a changed EventBus event (only when the change touches one)115- test files that exercise the changed symbol116117A changed exported symbol with zero recorded Grep calls in the trace is a skill violation. You are not allowed to assert "this is only used here" without showing the search.118119### 2.5c Implicit contract list120121For each changed symbol, walk this checklist and write one line per item, stating before vs after:122123- Props/args required vs optional, and their defaults124- Render/return shape — can it now return `null`/`undefined` where it couldn't before?125- **Query result contract — column set/order, row count assumptions, empty-result handling, error/timeout shape, whether results can be partial or truncated**126- Nullability of returned/exposed fields127- Side effects: network requests fired, IndexedDB/localStorage writes, navigation, EventBus emits128- Disposables and cleanup: timers, RxJS subscriptions, AbortControllers, event listeners, Monaco models/decorations — added, removed, or changed?129- Event/callback ordering and invocation guarantees (how many times, in what order, with what args)130- Idempotency and re-entrancy (rapid clicks, repeated calls, concurrent or aborted-then-restarted requests)131- Controlled vs uncontrolled component contract132- Redux: action shape, reducer state shape, selector return type133- **Persistence: Dexie schema version, table shape, migration behavior against existing stored data**134- Referential stability of returned callbacks, objects, and **context provider values** (does a consumer's deps array, memoized child, or context subscription depend on it?)135- Loading/error/empty state contract136137### 2.5d Cross-context exposure list138139End this step with an explicit list of "places this change is visible from but the diff does not touch". This is the highest-priority input for the candidate-discovery agents in Step 3a.140141The list groups the callsites from 2.5b by context: parent components that render the changed component, consumers of the changed query result / client method, consumers of the changed context provider value, effect dependency arrays that include the changed value, memoized children that receive changed callbacks, readers of a changed Dexie table, route or lazy-load boundaries, EventBus subscribers. Every entry on this list must be reviewed in Step 3a.142143## Step 3a: Candidate discovery144145You are the main agent, and your task is to manage the subagents, not diving into the code initially. Every selected agent receives:1461. The PR diff1472. The full change surface map from Step 2.5 (semantic deltas, callsite inventory, implicit contracts, cross-context exposure list)148149Each subagent should read surrounding source files as needed for context. Never pass a discovery narrative, proposed severity, or suggested fix between agents; the parent owns synthesis and deduplication, and children return candidates only.150151### Candidate-discovery directive (applies to all agents)152153- **You are a hypothesis generator, not an authority to publish a finding.** Output atomic propositions for independent falsification. Do not assign severity, propose fixes, write persuasive titles, or use "verified", "proved", or "confirmed". Any role text below that mentions a finding or severity describes what to inspect, not what you may conclude.154- **Bugs this change causes at consumers outside the diff are the highest-value candidates.** A changed symbol whose new behavior breaks an unchanged consumer outranks five nits inside the diff.155- **"Looks correct in isolation" is not a valid conclusion.** Before clearing a changed symbol, walk the callsite inventory from 2.5b and explicitly state, per callsite, whether the new behavior is still correct there.156- For each candidate, cite the exact changed hunk, or the unchanged consumer plus the 2.5c contract this change allegedly broke.157- **Name the producer:** the exact user interaction, query shape, persisted state, or configuration that creates every trigger condition. If you cannot locate it, write `producer: unknown`; do not invent one. A reachable branch is not proof that any producer can create its input.158- **Actively seek disproof:** the abort/supersede that does exist, the guard, the memoization, the ref read, the cleanup in a parent, the error boundary, downstream recovery, or unchanged/better base behavior. Record the strongest counterevidence found.159- Claims containing **never**, **only**, **exactly one**, or an equivalent universal negative require an exhaustive consumer/event inventory, not one traced path.160- A proposition with no independent consequence is evidence for its parent candidate, not a standalone candidate. If the parent falls, its dependents fall with it.161- Pre-existing bugs whose same-trigger behavior is unchanged from `$BASE` are never candidates against this change. A fully proved one leaves as a Step 4 adjacent issue draft; an unproved one stays in the private ledger.162- Two agents repeating the same reasoning are one hypothesis, not corroboration.163- Returning no candidate is valid and preferred to returning a speculative one.164165### Agents166167Use the following as a role catalog. Select only the roles whose domain the diff materially touches, within the level's allowance; do not launch the whole catalog.168169**Agent 1: Query execution & data integrity:** The highest-stakes agent. For any change touching `src/utils/questdb/client.ts`, `src/providers/QuestProvider`, `src/scenes/Result`, `src/scenes/Schema`, or query construction/result handling anywhere: correct handling of empty result sets, error responses, timeouts, aborted requests, and partial/truncated data; correct parsing of result columns and types; off-by-one or wrong-column indexing when rendering rows; assumptions that a result is non-empty or has a fixed shape; loss or misrepresentation of values (number precision, timestamp/timezone, null vs empty string, BLOB/binary); query string construction that could send malformed or unintended SQL; missing loading/error/empty UI states. Treat any path where the user could see wrong data, or no data without an error, as the top inspection priority.170171**Agent 2: React correctness & hooks:** Hook rules violations, stale closures, missing or incorrect dependency arrays, unnecessary stable references in deps array, missing useEffect cleanup (timers, subscriptions, AbortControllers, event handlers, **Monaco models/listeners/decorations/commands**), conditional hook calls, state updates after unmount, incorrect use of refs, broken controlled/uncontrolled component patterns, incorrect key props causing lost state, event handler reference stability, unnecessary RAF usage, unnecessary layout effect usage. **React 17:** flag reasoning that assumes automatic batching of `setState` outside event handlers (in promises, timeouts, epics, `await` continuations) — each such update renders separately here.172173**Agent 3: Async, timers & cancellation:** Missing cleanup of `setTimeout`/`setInterval` on unmount or before re-scheduling; a query feeding the shared single-slot result grid (driven by the editor and the AI chat window) that re-fires while a prior such query is still in flight without superseding it via `quest.abort(queryId)` / `quest.abortActive()`, so a slow earlier response lands late and overwrites the grid with stale data — surface the **missing `abort`/supersede**, not a missing caller-created `AbortController`, and do **not** flag independent/background queries (schema tree, table details, autocomplete, build version) that are meant to run in parallel; raw `fetch()` outside the client (AI streaming, settings) that should pass an `AbortSignal` but doesn't; requests that resolve after unmount or after a newer request (stale-response / race conditions); rapid-fire user actions firing duplicate or out-of-order requests; redux-observable epic correctness (`ofType` filtering, `switchMap` vs `mergeMap` for cancellation, error handling that doesn't kill the stream, missing `takeUntil`); RxJS subscription leaks; `setTimeout` used only to defer state updates (a smell, usually fixable with a callback or proper effect).174175**Agent 4: State & context architecture:** Redux action/reducer correctness, immutable state updates (no direct mutation); context provider value stability — inspect any provider whose `value` is a fresh object/array/function on every render without `useMemo`/`useCallback`, and record which consumers observably re-render because of it; context split so unrelated consumers don't re-render together; prop drilling where context would be cleaner (and the reverse — context used where a prop suffices); proper EventBus usage where touched; missing loading/error states in state-derived UI.176177**Agent 5: Persistence & migrations:** Dexie/IndexedDB correctness in `src/store` and consumers — schema version bumped when table shape changes; migration upgrades existing persisted data rather than dropping it; no data loss for users upgrading from a previous version; correct handling of quota-exceeded and corruption; compression/serialization round-trips losslessly (`compression.ts`, `buffers.ts`); reads tolerate older/missing fields written by prior versions; no blocking of the main thread on large persisted payloads.178179**Agent 6: Performance & rendering at scale:** Unnecessary rerenders through missing useMemo/useCallback where a component passes callbacks to memoized children or large lists; unnecessary memoization of small functions/computations that prevents no rerender; context-driven re-render storms (consumers re-rendering because a provider value isn't memoized); missing virtualization (`react-virtuoso`) for large result sets / long lists / the schema tree; expensive echarts/uPlot re-renders or full re-inits where an update would do; inline object/array/function creation in JSX props causing referential inequality; unnecessary or unnecessarily frequent network requests and IndexedDB writes; expensive computations without memoization. **Algorithmic optimality:** for every loop, traversal, or lookup added or changed in render, effects, selectors, query/result parsing, or schema-tree handling, state the time complexity and record sub-optimal choices — an O(n) `.find`/`.indexOf`/`.includes`/`.filter` linear scan where a `Map`/`Set`/object index gives O(1); an O(n²) nested `.find`/`.some`/`.filter` inside a `.map` over result rows or schema items; rebuilding a lookup structure on every render instead of memoizing it; re-parsing already-computed data; multiple passes over the same result set that could be fused. **Every performance candidate states its magnitude:** what the cost multiplies by (rows rendered, cells, keystrokes, renders of a long list) or the fixed bound that caps it (column count, a fixed enum, once per mount). A candidate with no magnitude cannot be classified.180181**Agent 7: Styling & theming:** Hardcoded colors/sizes instead of theme tokens, CSS specificity issues, z-index conflicts, animation performance (prefer `transform`/`opacity` over layout-triggering properties), styled-components created inside render functions (causes remounting), proper use of `css` helper for conditional styles, `$`-prefixed prop names for style-only props, proper use of `rem` units, not pixels, proper use of styled components instead of inline styling, proper use of existing icon libraries instead of custom SVGs, proper font/icon/box sizes that are consistent.182183**Agent 8: Code structure, readability & types:** Unnecessarily long component definitions without splitting into subcomponents (flag growth in already-large files), defining the same function/styled component in multiple places, complex logic inside a component instead of a `utils` file, creating a new component while an existing one under `src/components` could be reused, plain button/flex div where `Button`/`Box` apply; ambiguous naming, missing early returns, discouraged regex where a clearer approach exists, unnecessary comments for trivial logic, unnecessary IIFEs, unnecessary `!` non-null assertions, unnecessary `?.` optional chains, unnecessary optional fields (`?:`) that cannot be null/undefined, overly broad types that should be discriminated unions.184185**Agent 9: Test review & coverage:** Build a **private coverage map**: one row per behavioral change from 2.5a, recording the exercising test (found via real Grep/Glob searches over `e2e/tests/**/*.spec.js` and the unit test tree — citing a test without a recorded search is a skill violation), a failure link (what the assertion observes and why it fails if this change regresses — "the test renders the component" is not a failure link), the reachable population, the credible regression consequence, and the least fragile meaningful test for uncovered rows. Disposition per row: **COVERED / CRITICAL GAP / MODERATE GAP / ACCEPTED GAP / EXEMPT**. Missing tests alone never make a row Critical: a Critical gap requires a supported, reachable user population and a credible regression with material consequence (wrong/lost data, broken flow, security). A fix with no regression test defaults to a Moderate gap. Gaps that would require DOM/component tests are **ACCEPTED GAPS by project policy** (no jsdom/happy-dom in this repo) — note them as skipped; demand e2e coverage only for critical user flows. Cross-reference 2.5d and record missing cross-context tests as map rows, not pre-severitied findings. The map is required input for the Step 4 test gate; publish only admitted gaps, keep the rest private.186187**Agent 10: Accessibility & UX:** Missing ARIA labels on interactive elements; Radix dialog/popover/dropdown/tooltip usage — correct controlled state, focus trap, focus return on close, portal/z-index behavior, `Escape`/outside-click dismissal; missing keyboard navigation support; focus management issues; missing alt text on images; color contrast concerns; screen reader compatibility; click handlers without keyboard equivalents; missing error announcements for assistive technology; broken tab order.188189**Agent 11: Browser compatibility & security:** No reliance on APIs unavailable in target browsers without polyfills; no CSS properties with limited cross-browser availability; XSS vectors — `dangerouslySetInnerHTML`, untrusted input through `react-markdown` / `react-highlight-words`, unsanitized HTML; SQL injection or unintended SQL via string-built queries; open redirects via user-controlled URLs in the OAuth2/SSO flow (`src/modules/OAuth2`); secrets/tokens leaking into logs, telemetry, or localStorage.190191**Agent 12: Cross-context caller impact:** Walk the callsite inventory from 2.5b. For every callsite, fetch the surrounding code (the consuming component/hook plus its callers up two levels) and answer:192193- Does this consumer pass props/args the new behavior handles incorrectly?194- Does it depend on a contract from the implicit contract list (2.5c) that the change broke — a query result that can now be empty/partial/null-shaped, a context value that's no longer stable, a prop that became required, a hook return shape that changed, a Dexie field that moved or was renamed, a callback that's no longer referentially stable?195- Is it in a context (effect dependency array, memoized child, list render, event handler, async callback, aborted-request path, unmount path, route boundary) where the new behavior misbehaves even when the inputs are valid?196- For changed query results / client methods: do all consumers still parse and render the result correctly?197- For changed context values: do all `useContext` consumers still get a value with the expected shape and stability?198- For changed components/hooks: do all render sites / callers handle the new props or return shape?199- For changed Dexie tables/migrations: do all readers tolerate data written by both old and new versions?200201This agent's output is structured per callsite, not per failure mode. Each callsite gets a verdict: SAFE / CANDIDATE / INSUFFICIENT_EVIDENCE. A CANDIDATE is an atomic hypothesis for Step 3c; it has no severity yet. Select this role whenever changed symbols have meaningful out-of-diff consumers — small diffs to widely-used symbols have the largest blast radius.202203**Agent 13: Fresh-context adversarial (level 3 only):** Dispatched separately from Agents 1-12 to escape checklist anchoring. This agent operates under different rules:204205- It receives ONLY the PR diff and the names of the changed files. It does NOT receive the change surface map from Step 2.5, the implicit contract list, the cross-context exposure list, or any of the agent checklists above.206- Its sole instruction: "generate a small set of falsifiable ways this code could be wrong, and try to disprove each before returning it." No category list, no failure-mode taxonomy, no style guide.207- It is free to use Read, Grep, and Glob to explore the repository however it wants.208- Each surviving output follows the candidate contract: atomic proposition, changed attribution, producer, reachability, symptom, counterevidence, and missing evidence. No severity or fix.209210The point is to escape the structured frame, not to create privileged findings. A unique hypothesis is not high signal by itself, and overlap is not corroboration unless it supplies an independent evidence type.211212## Step 3b: Fixed quality checks213While the subagents are scanning the code for their tasks, you will perform predefined quality checks on the code.214- Type errors: `yarn typecheck`215- Build failure: `yarn build`216- Lint errors: `yarn lint`217- Unit test failures: `yarn test:unit`218219At level 0, run only `yarn typecheck` and `yarn lint`. At levels 1-3, run all four.220221These outputs are executed artifacts: a failure here is fully proved evidence and admits without a falsifier. Add one row per failing check to the output table. **Every failing gate is Critical** — build, type, test, and lint alike. The gates are the project's own committed standard, so a red one blocks the merge regardless of user-visible impact.222After completing this step, you will wait for subagent results.223224## Step 3c: Falsify, prove, and admit candidates225226Combine agent outputs into a private **candidate ledger**. Split compound narratives into atomic propositions, deduplicate by proposition plus evidence, and record dependencies. Do not draft report prose, severity, or a suggested fix. A candidate is not a finding.227228Use this state machine with no shortcuts:229230`HYPOTHESIS → FALSIFYING → PROVEN → ADMITTED`231232Any missing proof, unresolved contradiction, failed reproduction, unsupported producer, or dependence on an omitted premise ends at `OMITTED`. There is no downgraded state for an unproven behavioral claim, and "could not disprove" never means `PROVEN`.233234At level 3, launch one fresh-context falsifier per atomic candidate. At level 2, launch a single batched blinded falsifier for all candidates. At levels 0-1, the parent applies the same protocol inline from a blank evidence form before writing any report prose. The falsifier receives only (a) the neutral proposition, (b) the repo, `$BASE`/head revision identities, and relevant file names, and (c) raw evidence/artifact paths. **Do not send** the discovery narrative, proposed severity, suggested fix, or other agents' votes.235236The falsifier's first task is to construct the strongest disproof: a missing producer, an unreachable interaction, an existing abort/supersede, a guard, a memoization, a ref read, a cleanup in a parent, an error boundary, downstream recovery, or identical/better base behavior. Only if the candidate survives does it assemble affirmative proof.237238A behavioral candidate is admitted only when every field below is backed by cited evidence:239240- **Attribution:** exact changed hunk, or exact unchanged consumer plus the 2.5c contract this change broke.241- **Producer:** exact user interaction, query shape, persisted state, or configuration that creates every trigger condition.242- **Reachability:** complete producer-to-symptom path, including guards, aborts, retries, memoization, and recovery.243- **Head observation:** executed trigger and observed behavior at the reviewed revision.244- **Base observation:** the identical trigger at `$BASE`, or `N/A — new surface` with proof.245- **User symptom:** independently observable consequence; a statement that merely supports another candidate is not a finding.246- **Counterevidence search:** strongest attempted disproof and why it does not apply.247- **Artifact:** exact command/test, output, and revision identity. Race, ordering, stale-response, unmount-mid-flight, persistence-state, and migration claims always require an executed artifact; static source reading alone cannot admit them.248249For findings fully proved by source — type errors, direct standards violations, a hardcoded color, an effect that creates a disposable and never disposes it — mark producer/head/base fields `N/A — static` and cite the complete source proof. `N/A` is forbidden whenever a load-bearing premise concerns runtime ordering, reachability, or impact.250251### Executed-evidence ladder252253Use the cheapest sufficient rung; name the rung in the finding's Evidence entry.2542551. **Step 3b gate output** — `typecheck`/`build`/`lint`/`test:unit` results are already executed artifacts. Free.2562. **Scratch vitest test on extracted logic** — parsers, query construction, migrations, compression round-trips, reducers, selectors, utils. Write the test to a temp/scratch directory, run it with `yarn vitest run <file>`, never commit it. For a regression-test claim, run it at head (must pass) and against the reverted production hunk (must fail); admission requires both artifacts.2573. **Scratch vitest test for async orchestration** — epics and client logic. RxJS races (`switchMap` vs `mergeMap`, missing `takeUntil`, error-kills-the-stream) and promise-ordering claims reproduce deterministically with `TestScheduler`/marble tests or mocked promises resolved in a forced order. Use fake timers; never sleeps.2584. **Targeted Cypress spec — level 3 only** — for claims whose load-bearing step genuinely needs a real browser: Monaco lifecycle, focus management, IndexedDB behavior in the browser, interleaving through the UI. Reuse the existing harness (`e2e/commands.js`, fixtures) and run only the one spec, through yarn with `ELECTRON_RUN_AS_NODE` unset — Claude Code sets that variable, and it breaks Cypress's Electron binary:259260 ```bash261 env -u ELECTRON_RUN_AS_NODE yarn cypress run --spec <file>262 ```263264 **Do not build state through the UI:** seed `localStorage` and IndexedDB (Dexie) directly — persisted buffers, saved queries, editor settings, auth/session state — via `cy.window()` / existing commands before the page interaction, and jump straight to the interaction under test. Logging in and hand-creating data through clicks wastes the browser mount; one mount per review, not per candidate.265266A DOM-bound runtime claim below level 3 has no affordable artifact: omit it and record the validation limitation in the private ledger. When its static skeleton is itself a concrete defect (an effect that creates a timer/listener/model and never disposes it), file that static finding at the severity static evidence earns — without asserting the unexecuted runtime symptom. Never fall back from failed or unavailable execution to confident prose.267268After a candidate satisfies the admission schema, apply the domain-specific checks:2692701. **Read the actual source code** at the exact lines cited. Do not rely on the agent's description alone.2712. **Trace the full code path**: see if the code path verifies the claim, and the issue can occur with realistic user actions. For hooks, trace the deps array against what actually triggers a re-render or re-run.2723. **For data-integrity claims (Agent 1):** trace the actual result shape the client returns and confirm the consumer can really receive the empty/error/partial/null case claimed. A wrong-data or no-data-without-error finding is Critical only if a real query path produces it.2734. **For stale-closure / stale-state claims:** verify the closure actually captures a stale value AND that a fresh value is needed there. Check whether the value is read from a ref or passed fresh — if so, the candidate is `OMITTED false`.2745. **For missing-cleanup claims:** verify the effect actually sets up something that needs cleanup (timer, subscription, listener, AbortController, Monaco disposable) and that the component can unmount or the deps can change while it is live. A one-shot effect that cannot re-run or unmount mid-flight is not a leak.2756. **For re-render / performance claims (incl. unmemoized context values):** verify the provider/parent actually re-renders often enough to matter and that consumers really re-render as a result. Do not admit memoization findings that prevent no real re-render, or `useCallback`/`useMemo` whose deps churn anyway. **For algorithmic-complexity claims:** confirm the complexity analysis is correct, then establish the magnitude. A cost that scales with data on a path the user waits for or repeats — per row/cell of large result sets, per keystroke, per render of a long list or wide schema tree — can be Critical. A bounded cost off the hot path — capped by column count or a fixed enum, once per mount, once per query submit — is Moderate at most, even when a better algorithm plainly exists; name the better algorithm and the bound. A performance claim with neither a multiplier nor a bound is not verified.2767. **For race-condition claims:** identify the single **load-bearing step** — usually "this interleaving can actually happen with real user actions" — and try to falsify that step first. Per-step support in isolation does not prove the conjunction; a claim whose every link is individually true can still be false. Trace the actual async ordering: rapid clicks, navigation mid-request, unmount mid-fetch, abort-then-restart. For a missing-query-abort claim specifically, confirm the two queries actually compete for the same single-slot result surface (the result grid) — if they write to different targets, or are background queries meant to run in parallel, there is no stale-overwrite race and the candidate is `OMITTED false277278…(truncated)