blueprint

Write a blueprint to docs/plans/. Name it descriptively (e.g., YYYY-MM-DD-{topic}.md).

When to Use

Phase 0: Gather Inputs

Work from whatever is already known. Use all available inputs; no single source is required:

• Current conversation context, PRD / Jira / user description.
• CONTEXT.md and docs/adr/ — read them if they exist. ADRs are constraints for writing slices, not an after-the-fact gate.
• Codebase exploration.
• /grill-with-docs output — optional. Use it when available, do not require it.
• If CONTEXT-MAP.md exists, read it and read each context relevant to the topic; if unclear which context applies, ask the user.

If CONTEXT.md does not exist, infer terminology from code and the user's description and keep the terms self-consistent. Do not block or ask the user to run /grill-with-docs first.

What a Blueprint Is

A blueprint translates domain knowledge into executable work. It does NOT write code. It defines what behaviors to build (for TDD) and how to verify them in a running system (for integrate). TDD owns the implementation; integrate owns the deployment verification.

Output Structure

A blueprint has four required sections:

## Vision                    ← thinned PRD — concise intent, no implementation
## Vertical Slices           ← TDD input — one slice = one RED→GREEN→REFACTOR cycle
## Integration Test Requirements  ← integrate input — deployment-level verification
## Data Setup & Cleanup      ← optional — only when special data is needed

Section 1: Vision

A concise summary that captures WHY, WHAT, and BOUNDARY. This is NOT a full PRD — it gives TDD the intent behind each slice; the subsections below hold the supporting detail.

## Vision
**Context**: <context-name> (only when CONTEXT-MAP.md exists)

### User Stories
- As a <role>, I want <goal> so that <reason>
- ...

### Key Decisions
- Decision 1 (ref ADR-XXXX if applicable)
- Decision 2
- ...

### Pre-requisites (if applicable)
- Phase 0 work that must exist before any slice can start (e.g. shared library repo, DDL applied, external service available)
- Each pre-requisite states who owns it and how to verify it's satisfied

### Out of Scope
- Explicitly not doing X
- Explicitly not touching Y

Rules:

• User Stories are behavioural, not technical ("As an analyst, I want to filter STRs by submission date" — NOT "Add submissionDateFrom to Request DTO")
• Key Decisions reference ADRs where they exist; when no ADR exists, state the decision in one sentence
• Pre-requisites are external dependencies that your team cannot deliver through TDD and cannot verify within the blueprint's own integration environment. Java version, VPN connectivity, third-party service availability. Anything the agent can produce (code, DDL, config, seed data) belongs in a slice — regardless of what the source document calls it.
• Out of Scope is a safety rail — it prevents TDD from wandering into unrelated code
• No code. No file paths. No implementation hints.

Section 2: Vertical Slices

Each slice is a self-contained RED→GREEN→REFACTOR cycle. The slices are ordered by dependency — slice 1 has no blockers, slice 2 may depend on slice 1, etc.

## Vertical Slices

### Slice 1: <one-line behaviour description>

**Behaviour**: What the system does after this slice — user perspective, one sentence.

**Touches**: Direction only (e.g. "response DTO, SQL SELECT, service mapping"). No file paths, no code.

**Acceptance Criteria**:
- [ ] Criterion 1 — verifiable, behavioural
- [ ] Criterion 2

**Verified by**: IT-N — the integration test that verifies this slice's behaviour survives the full stack.

**Blocked by**: None / Slice N

- [ ] TDD done — `/tdd` ticks this only after every Acceptance Criterion is green and refactored

---

### Slice 2: ...

Rules for slices:

• Each slice cuts through ALL layers end-to-end. A slice that only touches the database (or only the API) is a horizontal slice — REJECT it.
• Behaviour and Acceptance Criteria describe observable outcomes, not implementation steps. "Search response contains submissionDate" — NOT "Modify SearchDissemDetail4ATrayDTO".
• Touches give directional guidance only — layer-level annotation (e.g. "response DTO, SQL SELECT, service mapping"). TDD decides exact implementation. No code snippets, no exact file paths.
• Verified by references one or more ITs in the Integration Test Requirements section. Slices never contain their own integration commands — /integrate runs only the IT section.
• Every slice ends with a TDD done checkbox, initially unchecked. Only /tdd ticks it, and only after the whole slice is green and refactored.
• The checkbox is a milestone, not a live health guarantee. Current health is re-verified by running the full test suite.
• Default: ≤3 Acceptance Criteria per slice. A slice with >3 AC is a complexity smell — it likely covers multiple behaviours. If exceeding 3, add a one-line justification in the slice (e.g. >3 AC because: all 14 entity strategies share the same interface and are verifiable through a single pattern).
• Blocked by is never empty if a dependency exists. "None" is only valid when the slice truly depends on nothing — no shared library, no DDL, no prior slice. "Assumes X exists" → Blocked by: X. If X can be delivered through TDD and verified in the integration environment, it must be a slice — reorder slices so the dependency comes first and other slices block on it. Pre-requisites are reserved for external dependencies the team cannot build or verify (Java version, VPN, third-party service availability).

Slice granularity test: Can you demo this slice after implementing it? If not, it's too narrow. Would it require more than 3 tests to verify? If so, either split it or add a >3 AC because: justification.

Section 3: Integration Test Requirements

These are the end-to-end verification commands that /integrate will execute against a running application. They complement TDD's code-level verification with deployment-level confidence.

## Integration Test Requirements

### IT-1: <scenario name>
**What it verifies**: One sentence.
**Provided by**: Slice N (which slice creates the capability this IT exercises)
**Command**: Single self-contained command with expected result annotation.

- [ ] Integration passed — `/integrate` ticks this only after the IT passes in a complete regress-all run

### IT-2: ...

Rules:

• Each IT requirement targets a behaviour that matters at the deployment level — things TDD tests alone cannot guarantee (real Spring bootstrap, real DB connection, real serialisation).
• Every IT must reference at least one slice as its capability source (Provided by). If no slice creates the endpoint or behaviour the IT exercises, the blueprint is incomplete. No orphan ITs.
• Commands use curl / Invoke-RestMethod (API), SQL probes (data state), or file checks (artifacts). On Windows pwsh, write curl.exe or Invoke-RestMethod — bare curl aliases to Invoke-WebRequest.
• Commands must be idempotent and self-contained — regress-all on any failure must be safe.
• Use unique identifiers (timestamps, UUIDs) to avoid cross-command state coupling.
• Every command has an explicit expected result.
• Every IT ends with an Integration passed checkbox, initially unchecked. Only /integrate ticks it, and only after a complete run in which every IT passes.
• The checkbox is a milestone for the last complete run, not a live guarantee. /integrate re-runs every IT each time.

Section 4: Data Setup & Cleanup (last resort)

Generate this section only when ALL of the following are true:

• At least one IT requires database state that the public API cannot create
• The blueprint states, in one sentence, why API-created data is insufficient
• MCP database tools (describe_table + query + write) are available in this environment

If MCP is unavailable, do NOT write this section. All ITs must use HTTP + file checks only. Add a note: "MCP unavailable — DB-level verification disabled."

When the conditions are met, read data-setup-format.md for the complete format specification and rules.

Capability Check

Before the Quality Gate, verify the environment can execute every IT requirement:

1. Check DB tool availability: does your tool list contain tools matching the three semantics — describe schema / query / write? Tool names vary by platform; to avoid false matches, a matched tool's description must mention database/sql/schema.
2. MCP available → Data Setup & Cleanup is allowed. ITs may include SQL probes.
3. MCP unavailable → Data Setup & Cleanup must be absent. ITs must use HTTP + file checks only. Gate fails if Data Setup exists but MCP is missing.

Quality Gate

The gate is split into two parts: machine checks the agent can verify deterministically, and human confirmation for subjective judgements.

Machine Gate

All machine checks must pass before showing the blueprint to the user.

Structural

• Required sections present: Vision, Vertical Slices, Integration Test Requirements (+ Data Setup & Cleanup if needed)
• At least one Vertical Slice and at least one Integration Test Requirement exist
• Each slice has: Behaviour, Touches, Acceptance Criteria, Verified by, Blocked by, and an unchecked TDD done checkbox
• Blocked by references only earlier slices
• No slice has >3 Acceptance Criteria without a stated justification
• No slice contains code snippets or exact file paths

Integration Traceability

• Every IT has a Provided by field and an unchecked Integration passed checkbox
• Provided by references an existing slice
• Verified by references an existing IT

Environment / Format

• If Data Setup & Cleanup exists, MCP database tools are confirmed available
• If MCP is unavailable, all IT commands use HTTP + file checks only
• Every IT command has an explicit expected result

Human Confirmation

Machine Gate passed → present the draft and ask for confirmation.

Show:

• Inputs referenced: CONTEXT.md (if used) and each ADR consulted while writing slices
• Slice list: title, Blocked by, Verified by
• Slice paths: US-N → Slice x → Slice y → ...
• Pre-requisites: list them so the user can spot anything that looks agent-producible

Ask exactly:

1. Does the granularity feel right? (too coarse / too fine)
2. Are the blocking edges correct?
3. Should any slices be merged or split?
4. Does each slice path compose into a complete User Story?

Do not write the blueprint until the user approves. If the user asks for adjustments, update the draft, re-run Machine Gate, and re-present.

Gate Outcome

• Machine PASS + user approval → write the blueprint to docs/plans/. Done. Handoff to /tdd.
• Machine FAIL → do not write. Fix and re-run the Machine Gate. Maximum 3 loops; after that write docs/plans/{blueprint-name}.gate-failure.md.
• User not approved → keep iterating the confirmation; never write without approval.

Handoff

After saving the plan, tell the user:

"Blueprint saved to docs/plans/. {N} vertical slices for /tdd, {M} integration test requirements for /integrate. Ready to build."