# Big Work Plan Review > Use before implementing big work — new systems, pipelines, daemons, or anything stateful/concurrent — where a bug would be expensive to find after code exists. Requires a written implementation plan to pass multi-round adversarial review by two independent LLM reviewers before any code is written. Not for scoped bug fixes or single-file changes; see requirements-clarification for those. - Skill: `andr-ca/big-work-plan-review` (Agent Skill) - Install (CLI): `npx skillmds@latest add andr-ca/big-work-plan-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/andr-ca/big-work-plan-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: andr-ca (https://skillmd.com/u/andr-ca) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/andr-ca/big-work-plan-review --- # Big-Work Adversarial Plan Review Ported from a workflow validated on a real design (an ntfy ingestion + persona memory pipeline) that went from roughly 3.5/10 to roughly 8.5/10 across 4 review rounds — each round finding genuine production-breaking defects a single author missed: processed-before-persisted data loss, an LLM call blocking a shared stream thread, mutable-JSONL status corruption, an answer-handling path that let contradiction answers poison an importance-rule store, and free-text LLM writes into what should have been a structured graph. **This is a from-description port.** It was written from a GitHub issue proposal, not from the original Cursor-format draft it references (`~/.cursor/skills/big-work-plan-review/SKILL.md`, on the proposing operator's own machine) — that draft was unreachable from the session that built this file. Reconcile against the original draft if it surfaces later; treat this version as functionally complete in the meantime, not as a placeholder. ## When to use this Big, stateful, or concurrent work: new systems, pipelines, daemons, anything with multiple writers, ordering dependencies, or state that outlives a single request. The cost of a design mistake here is a production incident, not a failed test. **When NOT to use this:** a scoped bug fix with one clear resolution, a single-file change, or anything `requirements-clarification` already covers by itself. Running a two-reviewer adversarial loop on a small change is pure overhead — match the ceremony to the blast radius. ## The loop 1. **Research verified facts, not assumptions.** Probe the live systems this design touches — actual schemas, actual message shapes, actual failure behavior — before writing a line of the plan. Record findings in a "Current state (verified)" section so a reviewer can tell what you checked from what you assumed. 2. **Write the plan.** One doc in `docs/plans/`, with these sections at minimum: - Goal - Current state (verified) - Architecture - Exact schemas / DDL / message contracts - Module contracts (inputs, outputs, invariants each module owns) - Failure-modes table (what breaks, how it's detected, what happens next) - Testing approach - Out of scope 3. **Two independent reviewers, in parallel.** Spawn two reviewer subagents from **different model families** — not two instances of the same model — so they don't share blind spots. Give each the same structured brief: review headings to respond under, a word cap, and an explicit "no file edits, review only" instruction. Resume the *same* reviewer sessions across rounds rather than starting fresh each time, so later rounds build on what a reviewer already flagged instead of re-discovering it. 4. **Embed reviews verbatim as plan appendices**, one appendix per round per reviewer. Do not summarize or paraphrase a reviewer's findings into the body — the raw text is the audit trail. 5. **Fold accepted fixes into the plan BODY, not just the appendix.** A stale body next to an up-to-date appendix is itself a defect class reviewers will catch — the plan must read as internally consistent after each round, not as an original draft plus a pile of unresolved commentary. 6. **Record dispositions.** For every reviewer finding: adopted (folded into the body), or deliberately rejected with a stated reason. A rejected finding needs the same rationale discipline as an adopted one — "reviewer flagged X, rejected because Y" — so a later reader can tell a considered rejection from a missed comment. 7. **Shift later rounds to closure verification.** Once the body has absorbed a round of fixes, the next round's brief changes: not "find new problems" but "go item-by-item through the disposition list and mark each CLOSED or NOT CLOSED." End each closure round with an explicit verdict: **READY** or **NOT READY**. A verdict only counts for the exact plan version the reviewer actually saw — re-verify after any further edit, don't carry a verdict forward across a body change. 8. **Implement only after both reviewers issue READY** on the same plan version. ## Defect checklist Nine recurring defect classes that fell out of the validating run. Point reviewers at this list explicitly in later rounds — it catches categories, not just this-specific-bug instances: 1. **Ordering bugs** — an operation assumes something upstream already happened (e.g., data marked processed before it's actually persisted). 2. **Blocking hot paths** — a slow call (LLM, network, disk) running inline on a thread that something else depends on staying responsive (a shared stream, an event loop, a lock holder). 3. **Mutable append-only files** — a file meant to be append-only (JSONL, a log) that something also rewrites or truncates in place, racing readers or losing data on a crash mid-write. 4. **Multi-writer artifacts** — more than one process/thread writing the same resource without a coordination story (locking, single-writer ownership, CAS). 5. **Free-text references into structured stores** — an LLM (or any producer) writing natural-language references into a field a structured system will later parse or join on. 6. **Missing join keys** — two pieces of state that need to correlate later (a request and its eventual result, an event and its replay) with no stable key connecting them. 7. **Missing replay cursors** — a consumer of a stream or log with no durable position, so a restart either reprocesses everything or silently skips a gap. 8. **Unbounded retries** — a retry loop with no cap, backoff ceiling, or dead-letter path, able to spin forever on a permanently-failing input. 9. **Cross-contaminating handlers** — a handler for one kind of event able to affect state that a different event type also owns, with no isolation between them. ## See Also - `requirements-clarification` — for verifying a requirement's premise and scoping ambiguity on ordinary-sized work; use before this skill even applies, to confirm the work really is "big" and not just underspecified. - `code-review` / `security-review` — post-implementation review, once code exists. This skill is deliberately upstream of those: it reviews the plan, not the diff.