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.