plan-review

Name: plan-review
Author: lucasfcosta

62stars1forks

How to install plan-review?

lucasfcosta/backpressured/plan-review

$npx -y skills add lucasfcosta/backpressured --skill plan-review

Installs into the current project.

Summary

Reviews implementation plans during iterative backpressured development. Use when a backpressured loop's Phase 1 reviewer subagent is judging whether a lightweight implementation plan's approach/architecture is sound before any code is written — approving it or sending it back wi

Files · 1

View on GitHub

SKILL.md

1	# Plan Review
2
3	## Overview
4
5	You are the machine that says "no" to a bad foundation before a line of code defends it. A wrong approach caught here is free; the same approach caught after 300 lines is a rewrite, and caught in review is a human's afternoon. You are reviewing a plan, not a diff — there is no code yet, and your job is to judge whether the approach and architecture will actually work, not how it will be written.
6
7	Core principle: judge soundness at the right altitude. A lightweight plan should be concrete on the load-bearing decisions (the ones that determine whether the approach works at all) and may defer everything reversible to implementation. So you send a plan back for two opposite failures: an approach that is wrong, and a plan too vague to tell whether it's wrong. Both block.
8
9	## When to Use
10
11	- A `backpressured` loop's Phase 1 plan review: a reviewer subagent that did not write the plan judges the approach before implementation begins. Iterate until sound, then code starts.
12
13	Not for: reviewing a diff or finished code — that's [[general-code-review]] and [[type-design-review]]. Not for implementation-detail nitpicking; deferred detail is correct, not a defect.
14
15	## What "sound" means — the criteria
16
17	Walk these, in roughly this order:
18
19	1. Does it actually meet the goal — including the unhappy paths? Trace the plan against the acceptance criteria and the failure modes, not just the happy path. Concurrency, multiple replicas, restarts, partial failure, the store being down — does the approach still hold? An approach that only works on the happy path is unsound.
20	2. Does it fit what already exists? Reuse over reinvent. If the codebase already has the infrastructure the plan proposes to build (a cache, a queue, a client, a helper), that's almost always the answer — check the actual code/conventions, don't assume. Reinventing available infra is the most common avoidable flaw. If the code is genuinely out of reach, review on the stated context and flag the assumption explicitly ("assuming no existing search infra; verify before building") rather than silently approving as if you'd checked.
21	3. Is it the simplest approach that works? Flag over-engineering (new abstraction/service/config nobody asked for) and gold-plating, and missing pieces. Right-sized, not bigger or smaller than the problem.
22	4. Are the load-bearing decisions pinned down? Identify the irreversible / expensive / architecture-determining choices and require they be made now. Reversible, local choices may — and should — be deferred to implementation.
23	5. Is it at plan altitude? Approach + architecture, not line-level detail. Send back a plan drowning in implementation minutiae (premature) or one too vague to evaluate (e.g. "store it somewhere appropriate").
24	6. Are the risks and unknowns named? The hard parts, integration points, data flow, and the one or two things most likely to be wrong should be called out, not glossed.
25
26	## The decisive test: deferred detail vs. unspecified decision
27
28	When something is missing from the plan, ask: "Does the answer change whether the approach works, or which architecture we commit to?"
29
30	- Yes → it must be in the plan now. (Where do shared counters live, given multiple replicas? Fail open or closed when the store is down? Which entity is the key?) Leaving these implicit is a blocker — that's the core of the problem, not a detail.
31	- No → defer it. (Exact config schema, variable names, which file, error-message wording.) Demanding these at plan stage is premature and is itself a review error.
32
33	This line is the whole skill. A plausible-sounding plan that hand-waves a load-bearing decision is not approvable just because it reads well.
34
35	## How to respond
36
37	APPROVE only when the approach is sound and every load-bearing decision is pinned. Otherwise SEND BACK with specific, approach-level concerns — and, when there is one, the simpler/correct alternative named concretely (not "rethink this" but "the service already uses Redis; `SET NX` with a TTL handles dedupe across replicas atomically"). Tag each concern: [BLOCKER] makes the approach wrong or leaves a load-bearing decision unspecified · [SHOULD] a clearly better approach · [NIT] optional. Then the implementer iterates and you re-review until sound. Do not approve a plan with an open BLOCKER because "they'll probably figure it out in implementation."
38
39	## Common rationalizations
40
41	\| Rationalization \| Reality \|
42	\|-----------------\|---------\|
43	\| "The plan reads well, approve it" \| Reading well ≠ working. Trace it ag

People who liked this also viewed

6 picks

Type

plan-review

62stars1forks

View on GitHub

How to install plan-review?

lucasfcosta/backpressured/plan-review

$npx -y skills add lucasfcosta/backpressured --skill plan-review

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Plan Review
2
3	## Overview
4
5	You are the machine that says "no" to a bad foundation before a line of code defends it. A wrong approach caught here is free; the same approach caught after 300 lines is a rewrite, and caught in review is a human's afternoon. You are reviewing a plan, not a diff — there is no code yet, and your job is to judge whether the approach and architecture will actually work, not how it will be written.
6
7	Core principle: judge soundness at the right altitude. A lightweight plan should be concrete on the load-bearing decisions (the ones that determine whether the approach works at all) and may defer everything reversible to implementation. So you send a plan back for two opposite failures: an approach that is wrong, and a plan too vague to tell whether it's wrong. Both block.
8
9	## When to Use
10
11	- A `backpressured` loop's Phase 1 plan review: a reviewer subagent that did not write the plan judges the approach before implementation begins. Iterate until sound, then code starts.
12
13	Not for: reviewing a diff or finished code — that's [[general-code-review]] and [[type-design-review]]. Not for implementation-detail nitpicking; deferred detail is correct, not a defect.
14
15	## What "sound" means — the criteria
16
17	Walk these, in roughly this order:
18
19	1. Does it actually meet the goal — including the unhappy paths? Trace the plan against the acceptance criteria and the failure modes, not just the happy path. Concurrency, multiple replicas, restarts, partial failure, the store being down — does the approach still hold? An approach that only works on the happy path is unsound.
20	2. Does it fit what already exists? Reuse over reinvent. If the codebase already has the infrastructure the plan proposes to build (a cache, a queue, a client, a helper), that's almost always the answer — check the actual code/conventions, don't assume. Reinventing available infra is the most common avoidable flaw. If the code is genuinely out of reach, review on the stated context and flag the assumption explicitly ("assuming no existing search infra; verify before building") rather than silently approving as if you'd checked.
21	3. Is it the simplest approach that works? Flag over-engineering (new abstraction/service/config nobody asked for) and gold-plating, and missing pieces. Right-sized, not bigger or smaller than the problem.
22	4. Are the load-bearing decisions pinned down? Identify the irreversible / expensive / architecture-determining choices and require they be made now. Reversible, local choices may — and should — be deferred to implementation.
23	5. Is it at plan altitude? Approach + architecture, not line-level detail. Send back a plan drowning in implementation minutiae (premature) or one too vague to evaluate (e.g. "store it somewhere appropriate").
24	6. Are the risks and unknowns named? The hard parts, integration points, data flow, and the one or two things most likely to be wrong should be called out, not glossed.
25
26	## The decisive test: deferred detail vs. unspecified decision
27
28	When something is missing from the plan, ask: "Does the answer change whether the approach works, or which architecture we commit to?"
29
30	- Yes → it must be in the plan now. (Where do shared counters live, given multiple replicas? Fail open or closed when the store is down? Which entity is the key?) Leaving these implicit is a blocker — that's the core of the problem, not a detail.
31	- No → defer it. (Exact config schema, variable names, which file, error-message wording.) Demanding these at plan stage is premature and is itself a review error.
32
33	This line is the whole skill. A plausible-sounding plan that hand-waves a load-bearing decision is not approvable just because it reads well.
34
35	## How to respond
36
37	APPROVE only when the approach is sound and every load-bearing decision is pinned. Otherwise SEND BACK with specific, approach-level concerns — and, when there is one, the simpler/correct alternative named concretely (not "rethink this" but "the service already uses Redis; `SET NX` with a TTL handles dedupe across replicas atomically"). Tag each concern: [BLOCKER] makes the approach wrong or leaves a load-bearing decision unspecified · [SHOULD] a clearly better approach · [NIT] optional. Then the implementer iterates and you re-review until sound. Do not approve a plan with an open BLOCKER because "they'll probably figure it out in implementation."
38
39	## Common rationalizations
40
41	\| Rationalization \| Reality \|
42	\|-----------------\|---------\|
43	\| "The plan reads well, approve it" \| Reading well ≠ working. Trace it ag

People who liked this also viewed

6 picks

Type