bulletproof-plan

name

bulletproof-plan

description

Produces a bulletproof implementation plan for a GitHub issue by collaborating with three specialist subagents — senior engineer, software architect, and technical writer — in parallel, validating every claim against CLAUDE.md, CONTEXT.md (when it exists), and any ADRs, then presenting the plan in plan mode for approval before any code is written. Every plan carries the full standard SDLC envelope (branch → implement → test → commit → review + self-review → fix → commit → PR → retrospective) so it lands a PR for sign-off. Use when the user wants to plan or spec out a GitHub issue, runs /bulletproof-plan with an issue number or URL, or asks for a rigorous multi-specialist implementation plan.

Bulletproof Plan

Turn a GitHub issue into a battle-tested implementation plan: three specialists analyze it in parallel, you reconcile and red-team their findings, then present the plan for approval before writing a line of code.

This whole skill is read-only research, so run it in plan mode. If you're not already in plan mode when invoked, enter it (EnterPlanMode) at the start — every phase here is plan-mode-safe.

Invocation

/bulletproof-plan <issue-number-or-url> — e.g. /bulletproof-plan 8. No argument? Ask which issue (or whether to plan the current conversation's context instead).

Workflow

Phase 0 — Ground yourself

1. Read the issue: gh issue view <number> --comments. Capture title, body, and comments.
2. Map the scope boundary against sibling issues. Plans over-reach by silently absorbing work that belongs to other issues. Build an explicit out-of-scope list before briefing specialists:
   • gh issue list --state open --limit 100 — skim every open title for adjacent work.
   • Pull every issue the target references (blocks #X, blocked by #X, see #X, part of #X, epic #X) and every issue sharing a label or milestone: gh issue view <n> --json title,body,labels,milestone,number.
   • For each adjacent open issue that touches the same files, domain term, or feature surface, record a one-line "#NN — owns: " entry. These are off-limits — the plan must stop at the seams between them.
   • If the target issue is silent on a capability that an adjacent issue clearly owns, that capability is out of scope here, even when bundling would be convenient. Record it as a dependency or follow-up instead.
   • If the issue's own scope is ambiguous, ask the user "Does this include X?" before continuing — narrow the slice to exactly what this issue owns.
3. Read the grounding docs so your specialist briefs are precise:
   • CLAUDE.md — the project's standing guidance. Load-bearing for planning: always verify your work (pnpm lint and pnpm build are the minimum bar for "done" — next build also type-checks the project; run npx tsc --noEmit for a faster standalone type-check), test proactively — no test runner is wired up yet, so when a slice adds logic worth testing (data transforms, the blog indexer, tRPC/server procedures, lib utilities) the plan should stand up a runner (Vitest suits this TS stack) and colocate the tests rather than defer them; never disable a rule to make a check pass, RTFM (check the Next.js/React/Prisma/tRPC docs while planning to guard against version drift and hallucinated APIs), and delight the user.
   • CONTEXT.md — the binding glossary, if it exists. If it (or CONTEXT-MAP.md) is absent, proceed silently — don't flag the absence or propose creating it upfront. When present, note which domain terms the issue touches and use them verbatim.
   • docs/adr/ — skim titles and pull any ADRs in the issue's area, if any exist (the directory may be empty). Proceed silently when there are none.
4. Locate the code the issue touches (Glob/Grep) so briefs can cite real file:line anchors. Routes and pages live under src/app/ (App Router — each blog post is its own src/app/blog/<slug>/page.tsx), shared UI under src/components/, server/tRPC procedures under src/server/, utilities under src/lib/, data and content metadata under src/data/, scripts like the blog indexer under src/scripts/, hooks under src/hooks/, and the database schema under prisma/.

Phase 1 — Parallel specialist analysis

Spawn all three subagents in one message for true parallelism. Each starts fresh with zero context, so every brief MUST be self-contained: paste the issue text inline, list the exact doc paths to read, name the files to inspect, and paste the Phase 0 out-of-scope list verbatim with the directive: "Do not propose work that belongs to any of these sibling issues — call the seam out as a dependency instead."

Role	subagent_type	Lens
Senior engineer	general-purpose (or Frontend Developer for component-heavy work)	Implementation path, edge cases, failure modes, and test/verification strategy: with no runner configured yet, how to keep logic testable (pull data transforms, the blog indexer, tRPC/server procedures, and lib utilities into plain modules), when to stand up a runner + first tests, and how else to verify — e.g. in the running app via pnpm dev.
Software architect	Software Architect (or Backend Architect for data/tRPC-heavy work)	System fit: Next.js App Router route boundaries (server vs client components), React component structure, tRPC/server-procedure design, the Prisma data model, and auth. Pattern choices, trade-offs, ADR alignment.
Technical writer	Technical Writer	Terminology vs the CONTEXT.md glossary (when it exists), naming, which docs/ADRs must change, user-facing clarity.

Direct each specialist to challenge assumptions and return: findings, assumptions questioned, doc/ADR validations (conflicts called out), risks, and their recommended slice with file:line pointers.

Phase 2 — Synthesize and red-team

1. Reconcile the three into one plan; where they disagree, decide and say why.
2. Flag ADR conflicts explicitly: "Contradicts ADR-XXXX (title) — but worth reopening because…" Never silently override an ADR.
3. Use the glossary's exact words when CONTEXT.md exists. A concept the glossary lacks (or the absence of a glossary altogether) is a signal — note it for /domain-modeling.
4. Red-team your own plan: name the single weakest assumption, the riskiest step, and what would make this fail — then resolve each. If specialists conflicted on something load-bearing, spawn one focused critique subagent rather than hand-wave.
5. Scope-creep check. Walk the ordered steps and ask of each: "does this belong to any sibling issue on the Phase 0 out-of-scope list?" If yes, cut it from the plan and record it as a dependency on that issue. If a step touches a sibling's surface but is genuinely required here, state the seam explicitly: what this plan changes vs. what the sibling will change.
6. Performance and SEO check. For a Next.js blog project, verify the plan doesn't regress page load times, doesn't break image optimization, and respects metadata/OG tag strategy.

Phase 3 — Present to build

Write the finalized plan to the plan file, then call ExitPlanMode to gate on approval before implementing (it reads the plan from the file — no plan content is passed as an argument). Pre-declare the build commands you'll need as allowedPrompts (e.g. pnpm lint, pnpm build, npx tsc --noEmit for a standalone type-check, plus pnpm db:generate if the slice touches the Prisma schema, pnpm blog:index if it touches blog content, and pnpm test once a runner exists) to cut prompts later.

Structure the plan: goal · the vertical slice · ordered steps (each naming its files) · risks + mitigations · assumptions & open questions · docs to update.

Every plan ships the full SDLC, not just the implementation. Unless the user explicitly says otherwise, the ordered steps MUST open with branch creation and close with the review → fix → PR → retrospective envelope, so that running this skill against an issue produces everything needed to land a PR the user signs off on. Wrap the issue-specific work in this scaffold:

1. First step — create the feature branch. Branch off main before any code is written (e.g. git checkout main && git pull && git checkout -b <type>/<issue-#>-<slug>). Never implement on main.
2. (…the issue-specific ordered steps go here — each naming its files, and each landing with its tests where the logic is testable and a runner is configured, per the "test proactively" bar above…)
3. When acceptance criteria are met — run the checks, commit, and kick off review. All work must pass pnpm lint and pnpm build (the project's bar for "done" — next build type-checks the project; use npx tsc --noEmit for a faster standalone pass), plus any tests the slice added — never disable a rule to make a check pass. Commit the work, push the branch, then run /code-review for an automated review of the diff. For a deeper pass on larger changes, note that the user can trigger /code-review ultra (multi-agent cloud review) — you can't launch it yourself.
4. Self-review in parallel. Don't block on the automated review — run your own review concurrently, looking for the things /code-review won't: scope creep vs. Phase 0, missing tests, terminology drift from the glossary, and CLAUDE.md violations.
5. After review — apply fixes. Triage the review findings and apply them with /code-review --fix (or /simplify for clarity-only cleanups), with per-change judgment. Re-run the checks after fixing.
6. After fixes — commit, push, and open the PR. Commit the fixes, push, and open the pull request for the user's final sign-off.
7. After the PR — run a retrospective and improve the process. Before declaring done, look back over the whole run and answer, in writing: What was missed? (scope gaps, late discoveries) · What bugs had to be solved? (and what earlier check would have caught them) · Which assumptions turned out invalid? (where the plan diverged from reality) · What would make the SDLC better going forward? Then act on at least one finding — don't just record it: open a follow-up issue, seed/amend CONTEXT.md or an ADR, tighten this skill or a sibling skill, or add a missing test/check. A retrospective that changes nothing is a missed step.

State these as real, numbered steps in the plan (not a footnote), so the implementing agent treats branch/tests/commit/review/fix/PR/retrospective as first-class deliverables.

Quality bar

• Plan ends in a PR, then a retrospective. The ordered steps open with feature-branch creation and close with the test → commit → review → fix → commit → PR → retrospective envelope. Running this skill against an issue should produce everything needed to land a PR for the user's sign-off, with no manual scaffolding left implicit.
• Every run feeds the next. The plan's final step is reflective: what was missed, what bugs were caught, which assumptions broke, and what would make the SDLC better — and it commits to at least one concrete improvement (issue, doc/ADR edit, skill tweak, or new check). Process improvement is a deliverable, not an afterthought.
• Tests are part of the slice, not after it. Keep testable logic (data transforms, the blog indexer, tRPC/server procedures, lib utilities) in plain modules and write tests alongside the code — verified to catch a real bug (break the code, confirm the test fails, fix). No runner is configured yet, so a slice that needs tests stands one up as part of the work rather than punting it. Reviews run concurrently: self-review never blocks on the automated /code-review.
• All work passes the checks. pnpm lint and pnpm build are green (plus any tests the slice added) unless the user explicitly overrides — and a rule is never disabled to make a check pass.
• Plan scope is explicitly bounded. Related work in other issues is called out by name; if overlap exists, the plan states what it excludes and why.
• Logic lives in the right place. The plan places logic deliberately — server vs client components, tRPC/server procedures, lib utilities, and the Prisma data model — respects the App Router's server/client boundary, and aligns with any ADR the project keeps.
• Honors CLAUDE.md — especially proactive testing, RTFM while planning (Next.js/React/Prisma/tRPC docs), delight, and never disabling a lint/type rule to make it pass.
• Treats imported/user-authored content (contact-form input, external API data such as Bluesky/atproto responses, blog/MDX content) as untrusted.

Handoffs

• Too big for one issue → split into tracer-bullet slices (per the seams found in Phase 0) and open separate issues.
• Terminology gaps, or no CONTEXT.md/ADRs yet → /domain-modeling to resolve the term or decision lazily.
• Async/AFK handoff → offer to post the plan via gh issue comment for later implementation.