Blueprint

Blueprint: thorough, validation-first planning

The point is not a longer plan. It is refusing to commit to a plan until the assumptions under it have been tested against reality — a plan on unverified assumptions is a confident-looking bug report from the future. /plan says "here's how I'd build it"; /blueprint adds why each load-bearing assumption holds, with the evidence.

Invoke for non-trivial features or refactors where a wrong approach costs hours, changes crossing component boundaries or touching invariants (data isolation, auth, billing), anything resting on third-party behaviour you have not personally verified, stated uncertainty ("would this even work?"), or a previous attempt that failed. Not for typo fixes, single-file edits, or mechanical renames — this skill is expensive on purpose.

Required references

This file is the skeleton; each reference holds a step's full rules. Read it at that step.

Principles

• Hypothesis first. Validation needs a target; without one, "research" wanders.
• Cheap experiments beat confident reasoning. A 10-line script that proves an API behaves as expected outranks a paragraph asserting it.
• Read the source on HEAD, not from memory. APIs change, specs evolve; verify now.
• Inverted pyramid for the user. Recommendation and blockers first; detail unfolds below, and the decisions the user still owes close the document.
• Loop until convergent. A refuted assumption sends you back to the hypothesis; never paper over it.

Workflow

1. Understand the problem. Restate it: goal, constraints, non-goals, success criteria — including what would prove the change doesn't work. Ambiguous or contradictory → ask the user; never invent answers to plug holes.
2. Form a hypothesis. Read references/validation.md now. A candidate specific enough to be wrong: the files and flows that change, the APIs it relies on, its 2–4 load-bearing assumptions — and the observation that would prove the shape wrong. If you cannot write the falsifier, sharpen the hypothesis; note fallbacks if several approaches are plausible.
3. Enumerate load-bearing assumptions — those the plan stops working without. Classify each Verified (cite file:line or doc), Plausible, or Risky.
4. Validate every unverified one with the cheapest thing that produces evidence: a script and its output, the library source, the migration files, a read-only query. Record confirmed / refuted / partial; refuted → back to step 2. Delegate batched reads to a read-only search subagent when the host has one.
5. Cross-validate with product specs. Read references/cross-validation.md now. Does the plan satisfy each affected requirement, violate any invariant, miss an acceptance criterion? A violation means the plan is not ready — or the spec needs a flagged change before code work.
6. Cross-validate with architecture and conventions. Boundaries, security, scalability and cost, observability, async machinery. Then the discipline check: enumerate the project's conventions from its own docs on HEAD — package manager, task-runner entry points, test framework and mocking policy, lint, migrations, ports — each cited and linked to the plan step it shapes, or marked "doesn't constrain" with a reason. Defaults from training data are the modal failure here.
7. Sweep the codebase for systemic conflicts no single assumption captures: in-flight work in the area, shadow duplication, caller-side drift when a contract changes, missing test infrastructure.
8. Loop or commit. Survived → step 8.5. Partially → adjust and re-validate the changed parts. Broken → back to step 2 with what you learned. Cap at ~3 rounds; then the problem itself likely needs reframing — surface that. 8.5. Counterfactual. Read references/plan.md now. Map every step-1 success criterion to the plan step that satisfies it: Confirmed, Confirmed with gaps (listed), or Unconfirmed — and unconfirmed means the plan is not ready.
9. Write the plan per plan.md § 9: headline (1–3 sentences), approach summary (3–10 sentences of prose), out of scope, ordered steps with file paths, assumptions with evidence, test plan, risks and mitigations, open questions last. The first two sections let a human accept or reject the shape before reading further; the whole is as long as it needs to be and no longer.
10. Present and gate. Ask open questions and wait. An architectural deviation, spec change, or risky migration needs explicit approval before implementation — never proceed on auto mode. Approved → normal implementation rules apply.

Definition of done

Every item in plan.md § Definition of done is answerable with evidence. One you cannot tick honestly sends you back to the step that produces it; a step you are tempted to skip sends you to references/rationalizations.md. If validation killed the hypothesis, the deliverable is the negative result and the reframing — not a salvaged plan.

Related skills

/plan when assumptions are mostly known · /rca when the failure has already happened · /examine to review the change once it is built.