generate

# Phase 2: Generate

Declarative phase skill. Invoked by the prd-taskmaster orchestrator when
`current_phase` is `GENERATE`. Never called directly by a user.

The one rule: **generate the spec, validate it catches placeholders, parse it
into tasks, expand every task into subtasks. Quality over speed.**

## Entry gate

1. Call `mcp__plugin_prd_go__check_gate(phase="GENERATE", evidence={})`.
   If the call returns `{gate_passed: false, violations: [...]}`, report the
   violations and stop. The gate protects against re-entering a completed
   phase or skipping ahead from DISCOVER.

   **Known issue (Mum dogfood feedback [10] — WORST):** check_gate(GENERATE)
   currently checks `task_count > 0`, `subtask_coverage >= 1.0`, and
   `validation_grade in (EXCELLENT, GOOD)` — all of which are GENERATE's
   OWN OUTPUTS, not entry preconditions. First-time entry deadlocks. State
   machine LEGAL_TRANSITIONS already prevents illegal entry — proceed past
   this gate on first entry. Semantic fix in flight (see morning brief).
2. Read the DISCOVER output (discovery summary + `CONSTRAINTS CAPTURED` block
   + scale classification). If any of these are missing, report and stop — the
   gate should have caught this, but belt-and-braces.

## Generate checklist

Copy into your response before running the procedure:

```
GENERATE CHECKLIST:
- [ ] Template loaded (comprehensive|minimal)
- [ ] Spec written with discovery answers (no bare placeholders remaining)
- [ ] CONSTRAINT CHECK: every DISCOVER constraint appears in the spec
- [ ] SCOPE CHECK: task count matches scale (Solo 8-12, Team 12-20, Enterprise 20-30)
- [ ] Validation score: ___ / ___ (grade: ___)
- [ ] placeholders_found: ___ (bare placeholders = 0 required)
- [ ] Warnings addressed or acknowledged
- [ ] Tasks parsed: ___ tasks created
- [ ] Complexity analyzed via TaskMaster: Y/N
- [ ] All tasks expanded into subtasks: Y/N
```

## Step 1: Choose and load template

Decide based on discovery depth:

- **Comprehensive**: 4+ detailed answers, complex project, Team / Enterprise scale
- **Minimal**: thin answers, user wants speed, Solo scale

**MCP (preferred)**: `mcp__plugin_prd_go__load_template(type="comprehensive")`

**CLI fallback**: `python3 script.py load-template --type comprehensive`

The template is the canonical shape — do not invent your own. If the template
load fails, report and stop. Do not paper over with a home-rolled skeleton.

## Step 2: Generate spec at `.taskmaster/docs/prd.md`

Fill the template with discovery answers. AI judgment required:

- Replace ALL placeholders with actual content pulled from DISCOVER.
- Expand with project-specific details — do not leave template prose verbatim.
- Add technical depth proportional to what the user provided in discovery.
- Generate domain-appropriate sections (pentest = threat model, app = user
  stories, business = success metrics, learning = assessment criteria).
- Document assumptions where discovery was thin — explicitly, not silently.

### CONSTRAINT CHECK (MANDATORY)

Verify EVERY constraint from the DISCOVER phase `CONSTRAINTS CAPTURED` block
appears in the spec. If "must use Python" was a constraint, the spec MUST
reference Python. Missing constraints = spec bug.

Emit the check explicitly:

```
CONSTRAINT CHECK:
- Tech stack (Python): FOUND in spec section "Technical Stack"
- Timeline (MVP in 2 weeks): FOUND in spec section "Milestones"
- ...
```

Every constraint must be marked FOUND. If any are MISSING, loop back and
fix the spec before proceeding.

### SCOPE CHECK (MANDATORY)

Use the scale classification from DISCOVER to set task count range:

| Scale      | Task Count | Subtask Depth    |
|------------|-----------|------------------|
| Solo       | 8–12      | 2–3 subtasks each |
| Team       | 12–20     | 3–5 subtasks each |
| Enterprise | 20–30     | 5–8 subtasks each |

If DISCOVER classified the project as Team but the spec implies 30 tasks,
that's a scope bug — narrow the spec or re-classify explicitly.

### Domain-neutral vocabulary

When the domain is unclear, default to neutral terms:

| Software term | Neutral equivalent | When to use neutral |
|---------------|-------------------|---------------------|
| tests         | verification criteria | pentest, business, learning |
| code          | deliverable        | business, learning |
| deploy        | execute / deliver  | business, learning |
| repo          | workspace          | non-software |
| PR            | output / submission | non-software |

If the domain IS software, use software terms. Neutral terms are for
non-software goals.

### Deferred decisions — the `reason:` convention

Every `[placeholder]`, `{{variable}}`, `[TBD]`, `[TODO]` must be either:

(a) Replaced with real content,
(b) Removed entirely, or
(c) **Paired with a `reason:` explanation** on the same line or the next line
    documenting why the decision is deferred.

Per the v4 spec: placeholders with `reason:` attribution are allowed and
surfaced in the validation output as `deferred_decisions`. A bare placeholder
is a validation failure; an attributed one is a known deferred decision with
accountability.

Examples:

```
# BAD — bare placeholder, fails validation:
Target latency: {{TBD}}

# GOOD — attributed, appears in deferred_decisions:
Target latency: {{TBD}} reason: awaiting load-test results scheduled 2026-04-20
```

Write the final spec to `.taskmaster/docs/prd.md`. This is the canonical
path — downstream tools read from here.

## Step 3: Validate spec quality

**MCP (preferred)**: `mcp__plugin_prd_go__validate_prd(input_path=".taskmaster/docs/prd.md")`

**CLI fallback**: `python3 script.py validate-prd --input .taskmaster/docs/prd.md`

Returns: `score`, `grade`, `checks`, `warnings`, `placeholders_found`.

**Optional AI-augmented review** (opt-in): pass `--ai` (CLI) or `ai=True` (MCP)
to additionally invoke TaskMaster's configured main model for a holistic
quality review. The deterministic regex checks always run first — AI review
is a