plan-critic · diff
git:20260726.3115fd3 to git:20261004.cccdee6
62 added, 102 removed. Audit A to A.
---
name: plan-critic
description: >
- Critiques an implementation plan using pre-mortem, inversion, load-bearing
- assumption analysis, and consistency checks. Invoked as /plan-critic for
- ad-hoc plan critique, or used by the plan-critic sub-agent in the
- /feature workflow.
- ---
-
- # /plan-critic — Plan Critique
-
- Apply this skill to critique a draft implementation plan before any code is
- written. The goal is to find weaknesses in the plan itself, not to rewrite
- it. The developer reads the critique alongside the plan and decides what to
- amend.
-
- ---
-
- ## Stance
-
- Plans are load-bearing. If the plan is wrong, downstream review and QA
- mostly verify that the wrong thing was built correctly. Your job is to
- attack the plan before it becomes commitment.
-
- You do NOT critique writing quality, formatting, or template completeness.
- You critique whether the plan, as written, will produce a good outcome.
-
- ---
-
- ## Inputs
-
- You receive:
- - A draft implementation plan as markdown text.
- - Read-only access to the repository: ADRs in `docs/adr/`, product docs in
- `docs/product-context/`, existing source code, module-level `AGENTS.md`
- files.
-
+ Critiques a draft implementation plan with pre-mortem, inversion,
+ load-bearing-assumption and consistency checks; returns findings,
+ suggested amendments, and a confidence verdict. Use when the user asks to
+ review, challenge, or stress-test a plan before implementation.
+ license: MIT
+ metadata:
+ author: André Cunha
---
- ## Methods
-
- Apply EACH of the four methods below. Each must produce findings or an
- explicit "no concerns surfaced by this method, because [reason]" statement.
- Skipping a method silently is not acceptable.
-
- ### 1. Pre-mortem
- Assume this feature shipped 30 days ago and caused a production incident,
- support escalation, or regulatory complaint. Write 2–3 plausible failure
- scenarios in 1–2 sentences each. For each, identify whether the plan
- addresses it and how. Unaddressed scenarios become findings.
+ # /plan-critic
- ### 2. Inversion
- Read the plan as a recipe for guaranteeing failure. What could an
- adversarial implementer do, while technically following the plan as
- written, that would produce a broken or unsafe feature? List 2–3 such gaps.
+ Find weaknesses in a draft plan before code is written. Attack the plan's
+ outcome, not its writing quality, formatting, or template completeness.
- ### 3. Load-bearing assumptions
- List the 3 most load-bearing assumptions in the plan — assumptions about
- user behaviour, data shape, system state, regulation, third-party
- behaviour, or scale. For each, ask: what if it's wrong? Is the plan robust
- to that? If not, flag it.
+ ## Input
- ### 4. Consistency with prior decisions and product intent
- Read relevant ADRs and product docs in `docs/product-context/`. Flag any
- contradictions with past architectural decisions or the documented product
- vision/strategy that the plan does not acknowledge.
+ - Draft plan (markdown)
+ - Read-only repo access: `docs/adr/`, `docs/product-context/`, source code,
+ module-level `AGENTS.md`
- ---
+ ## Steps
- ## Base Lenses (any project handling personal data)
+ ### 1. Gather context
- Like the project-specific lenses below, these direct extra attention while
- applying the four methods above — they are not a separate checklist.
+ - ADRs in `docs/adr/` relevant to the affected areas
+ - Product docs in `docs/product-context/`
+ - Module `AGENTS.md` in directories the plan touches
- - **Personal-data leakage** — new data or rendering paths reaching public
- surfaces, logs, analytics, or URLs. Generic plans never mention these,
- and leaks are cheapest to catch before the code exists.
+ ### 2. Load lenses
- <!-- When the product grows consent and retention/deletion flows, add
- lenses for them here: consent lifecycle (not-given / withdrawn /
- re-consent) and right to erasure (how new data dies: cascade, TTL, or
- an explicit reason to retain). Until those flows exist as product
- features, per-plan attention to them is noise. -->
+ Lenses direct extra attention while applying the methods (step 3). They are
+ not a separate checklist; no severity or structure required.
- ---
+ - Base lens (any project handling personal data): **personal-data leakage**
+ — new data or rendering paths reaching public surfaces, logs, analytics,
+ or URLs
+ - Project lenses, first match wins:
+ 1. Repo-root `AGENTS.md` (not module-level) → *Review & Planning Guidance*
+ → "Planning guidance" entry → read the file it names
+ 2. No such section/entry → `docs/agent-rules/plan-critic.md`
+ 3. Entry names a missing file → treat as no file found, and say so
+ specifically in Confidence
+ - Any doc found (lens-format file, style guide, handbook, product docs)
+ applies the same way
+ - No file found → base lens alone
- ## Project-Specific Lenses
+ <!-- When the product grows consent and retention/deletion flows, add lenses
+ here: consent lifecycle (not-given / withdrawn / re-consent) and right
+ to erasure (cascade, TTL, or explicit reason to retain). -->
- This skill is project-agnostic; each project extends it without editing it.
- Check the repo-root `AGENTS.md` (not a module-level one) for a **Review &
- Planning Guidance** section. If it has a
- "Planning guidance" entry, read the file it names. If `AGENTS.md` has no
- such section, or the section exists but has no "Planning guidance" entry,
- fall back to checking `docs/agent-rules/plan-critic.md` directly. If an
- entry names a file that doesn't exist, treat it the same as "no file
- found" below, but say so specifically in the Confidence section.
+ ### 3. Apply ALL four methods
- Whatever is found — this skill's own lens format or a pre-existing project
- doc (a style guide, an engineering handbook, product docs) — apply it the
- same way: it lists this product's high-risk areas, the places where
- generic plans regularly miss issues that matter here. Like the base lenses
- above, it directs extra attention while applying the four methods; it is
- not a separate checklist, so no severity or structure is required of it.
+ Each yields findings or an explicit "no concerns surfaced by this method,
+ because [reason]". Never skip silently.
- If no file is found either way, apply the base lenses alone.
+ 1. **Pre-mortem**: assume it shipped 30 days ago and caused a production
+ incident, support escalation, or regulatory complaint
+ - Write 2–3 failure scenarios, 1–2 sentences each
+ - Per scenario: does the plan address it, and how? Unaddressed → finding
+ 2. **Inversion**: read the plan as a recipe for failure
+ - List 2–3 things an adversarial implementer could do while technically
+ following the plan that yield a broken or unsafe feature
+ 3. **Load-bearing assumptions**: list the 3 most load-bearing (user
+ behaviour, data shape, system state, regulation, third-party behaviour,
+ scale)
+ - Per assumption: what if wrong? Is the plan robust? If not, flag
+ 4. **Consistency**: check ADRs and product docs/vision
+ - Flag contradictions the plan does not acknowledge
- ---
+ ## Output
- ## Output Format
+ Markdown, concerns first, in this format:
```
### Pre-mortem Scenarios
- [scenario]: [whether the plan handles it; if not, the specific gap]
### Inversion Findings
- [gap]: [how the plan permits the broken outcome; suggested constraint]
### Load-bearing Assumptions
- [assumption]: [what happens if wrong; whether the plan is robust]
### Consistency Issues
- [contradiction]: [the relevant ADR/doc and the conflict]
### Suggested Plan Amendments
- [Concrete amendments the developer can choose to apply. Phrased as
- suggestions, not edits — the developer decides.]
+ [Concrete amendments, phrased as suggestions, not edits — the developer decides.]
### Confidence
- [Your overall confidence the plan will produce a good outcome:
- HIGH / MEDIUM / LOW, with one sentence of justification.]
+ [HIGH / MEDIUM / LOW, with one sentence of justification.]
```
- ---
-
## Constraints
- - Do NOT rewrite the plan or produce a revised version. Concrete
- amendment suggestions belong in the "Suggested Plan Amendments"
- section only. The developer decides what to adopt.
- - Do NOT write any files.
- - Do NOT propose implementation code.
- - A critique with empty sections requires explicit per-method
- justification (see Methods above).
+ - Never rewrite the plan or present a revised version; amendments go only in
+ *Suggested Plan Amendments*
+ - Write no files
+ - Propose no implementation code
+ - Empty section → per-method justification (step 3)