# Codebase-review prompt + framework

A reusable, Fable-5-tuned prompt for a deep **read-only review** of the whole
`videoclaw-v3` codebase. Authored with the `prompting-fable-5` skill
(give-the-reason, assessment-only boundary, parallel-subagent fan-out,
progress-grounding, lead-with-outcome report, no echo-your-reasoning).

This is the **review** counterpart of `docs/IMPROVE_PROMPT.md`: it produces a
ranked, adversarially-verified findings report and **changes nothing**. Run this
first when you want to know where the codebase stands; hand its report to an
improvement pass (`docs/IMPROVE_PROMPT.md` / the `improvement-run` skill) when
you want things fixed.

## The framework (why the prompt is shaped this way)

**Review = fan-out → adversarially verify → rank by user impact → report.**

1. **Fan out by dimension, not by directory.** Independent reviewers each take
   one *failure class* across the whole tree, because bugs cluster by class,
   not by folder. The standing dimensions for this repo:
   - **Spend-safety & gates** — paths where real money can be spent without
     `--confirm-spend`/`--dry-run`/the director gate; batch/pool/auto-chain
     re-spend on resume; stale-output skips that fake success.
   - **Correctness & silent failure** — swallowed errors, empty-catch
     degradation that hides real faults, wrong-but-plausible outputs.
   - **Contract drift** — schemas vs writers, `cli-schema.ts` vs dispatch vs
     help text vs docs, README claims vs behavior.
   - **Concurrency & state** — artifact locks, resumable drivers
     (auto-chain/pool/render-scenes), TOCTOU on checkpoints/candidates,
     shared-workspace hazards.
   - **Test adequacy on load-bearing seams** — execution runtime, reference
     budget/merge, review-state ladder, provider transports: is the behavior
     pinned, or just exercised?
   - **Onboarding & packaging** — what a stranger hits: published-tarball
     integrity, keyless paths, personal/machine-specific residue.
2. **Findings are claims, not facts.** Every finding gets a fresh-context
   adversarial pass that tries to REFUTE it before it reaches the report. On
   the 2026-06-13 run, roughly **a third of raw audit findings were wrong** —
   usually because a test already pinned the behavior as intended, or the
   claimed spend path was actually request-only. A review that skips this step
   ships noise and erodes trust in the whole report.
3. **Evidence standard.** A finding without `file:line` plus a concrete
   failure scenario ("with inputs/state X, Y goes wrong, user sees Z") is not
   a finding — it's a vibe. Severity ranks by *user impact*: money lost or
   spent twice > wrong render presented as done > operator misled by
   status/docs > developer friction.
4. **Fixed decisions are constraints, not findings.** The ADRs
   (no-silent-fallback across routes, on-disk project as source of truth,
   Seedance identity via Asset Library, director-mode approval gate) and the
   review-state ladder are settled. Reporting them as problems is a review
   defect.
5. **The report states its own coverage.** What was reviewed, what wasn't,
   and what's healthy — a review that only lists faults can't be told apart
   from a review that stopped early.

## How to run

- Set effort to **xhigh** — adversarial verification is the hardest-range part.
- It's read-only end-to-end: no checkpoints needed; it runs to the report.
- Findings format (keep it, the improvement pass consumes it):
  `TITLE | file:line | evidence | failure scenario | impact H/M/L | effort S/M/L | fix sketch | test-that-would-catch-it | verdict CONFIRMED/PLAUSIBLE`

## Prompt

```text
You're reviewing videoclaw-v3 (the `vclaw` CLI; npm package `videoclaw`) — a
TypeScript/Node 20, strict-NodeNext-ESM, multi-provider video pipeline CLI targeting
Veo (Flow/UseAPI/Omni), Seedance, Runway, and Dreamina. It's a solo-creator tool that
ships real client video work, so the stakes rank: real money spent wrongly > a wrong
render presented as done > an operator misled by status or docs > developer friction.
I want an honest, evidence-backed picture of where this codebase actually stands —
a review, not a fix-up: change NOTHING, produce a report.

Read first, then judge. Read CLAUDE.md, MERGE_PLAN.md, docs/ARCHITECTURE.md, the ADRs
in docs/adr/, and the memory index at
~/.claude/projects/-Users-davendrapatel-Documents-GitHub-videoclaw-v3/memory/MEMORY.md.
These encode settled decisions (no silent fallback across provider routes; the on-disk
project as source of truth; Seedance identity via the Asset Library; the director-mode
approval gate; the review-state ladder; position-sensitive import.meta.url path math in
handlers). Treat them as constraints — reporting a settled decision as a defect is a
review error, not a finding.

Review by failure class, not by folder. Fan out parallel read-only subagents, one per
dimension, each sweeping the whole tree for its class, and keep synthesizing while they
run: (1) spend-safety — any path where money can be spent without --confirm-spend, a
--dry-run default, or the director gate, including re-spend on resume in the batch
queue, pool, and auto-chain drivers, and stale-output skips that fake success; (2)
correctness and silent failure — swallowed errors and advisory degradation that would
hide a real fault, and wrong-but-plausible output paths; (3) contract drift — schemas
vs writers, cli-schema.ts vs the dispatch table vs printHelp vs README and
docs/CLI_REFERENCE.md; (4) concurrency and state — the artifact locks, the three
resumable scene drivers, TOCTOU on checkpoints and candidate stores, shared-workspace
hazards; (5) test adequacy on the load-bearing seams — execution runtime, reference
budget and merge, the review-state ladder, provider transports: is behavior PINNED by
an assertion or merely executed; (6) onboarding and packaging — what a stranger hits
installing the published package with zero keys, and any personal or machine-specific
residue in shipped code. Each subagent must report only what it verified by reading
the code, in this format: TITLE | file:line | evidence | failure scenario | impact
H/M/L | effort S/M/L | fix sketch | test-that-would-catch-it.

Then treat every finding as a claim and try to kill it. For each, run a fresh-context
adversarial pass that attempts to REFUTE it: check whether an existing test pins the
behavior as intended, whether the claimed spend path is actually request-only, whether
a guard upstream already covers it. Expect roughly a third to die here — that is the
point. Mark survivors CONFIRMED (you reproduced the reasoning against the code and
found no refutation) or PLAUSIBLE (couldn't refute, couldn't fully confirm), and drop
the rest with one line saying why. A finding without file:line and a concrete failure
scenario doesn't go in the report at all.

Before reporting, audit each claim against an actual tool result from this session —
a file you read, a test you ran, a grep you can point to. If you ran the suite or a
smoke, show the counts; if you didn't, say so. Do not pad: if a dimension comes back
healthy, that's a result, and it goes in the report as one.

Deliver one report, and lead with the outcome: a one-paragraph verdict on the
codebase's real state, then the CONFIRMED findings ranked by user impact (money >
wrong-render > misled-operator > friction), then PLAUSIBLE ones, then what's
demonstrably healthy, then what you did NOT review and why. Write it for someone who
didn't watch you work: plain sentences, every file reference clickable as file:line,
no working shorthand, no jargon you invented mid-review. Recommend — don't perform —
the top three fixes; the fixing itself belongs to a separate improvement pass.
```