plan-pipeline-eng-review

/plan-pipeline:eng-review: Engineering Architecture Gate

Post-direction, pre-implementation command. Takes validated product direction and returns a buildable technical spec with diagrams. Forces the system to think through architecture before a single line of implementation code is written.

Use after /plan-pipeline:ceo-review has locked direction. Still in plan mode.

---

The Problem This Solves

Once product direction is locked, the next failure mode is vague architecture. "The system will handle it" is not a plan. This command forces explicit answers to the hard technical questions before they become production incidents.

The key unlock: forcing diagram generation. Diagrams surface hidden assumptions that prose keeps vague. A sequence diagram makes you specify who calls what. A state machine makes you enumerate every failure mode explicitly.

---

When to Use

• After product direction is validated (post /plan-pipeline:ceo-review or equivalent)
• Before any implementation work starts on a non-trivial feature
• When the feature has async components, external dependencies, or multi-step flows
• Any time "the architecture is clear" needs to be proven, not assumed

---

What It Should Produce

---

Prompt Template

# /plan-pipeline:eng-review

You are in engineering manager / tech lead mode. Direction is locked.
Your job is to make it buildable: turn the product direction into a
technical spec that an engineer can implement without making architecture
decisions on the fly.

Do NOT question the product direction. Do NOT suggest scope changes.
Do NOT implement anything. Return a technical spec.

## Step 1: Restate the Feature

1-2 sentences: what is being built. Confirm you are working from the
correct brief.

## Step 2: Architecture Diagram

Draw the component architecture in Mermaid:
- All components involved (frontend, backend, jobs, storage, external APIs)
- Boundaries between components
- Data flow directions

```mermaid
graph LR
    ...

Step 3: Core Flow (Sequence Diagram)

Draw the happy path as a sequence diagram:

• Which components call which, in what order
• What data passes at each step
• Where async handoffs happen

sequenceDiagram
    ...

Step 4: State Machine

Draw the state machine for the core domain object:

• All valid states
• All transitions and their triggers
• Terminal states (success AND failure)

stateDiagram-v2
    ...

Step 5: Sync vs Async Decisions

For each operation in the flow, decide:

• Synchronous (blocks the request): why, and what is the latency budget
• Asynchronous (background job): why, what triggers retry, how does the caller know it succeeded

Step 6: Failure Mode Inventory

For each step in the flow, enumerate:

• What can fail
• How it fails (silently? loudly? partial success?)
• What the recovery path is
• What the user sees

Flag any failure that is currently silent.

Step 7: Trust Boundaries

For each external input (user uploads, API responses, webhook payloads):

• What do you trust? What do you validate?
• Where could malicious input cause harm?
• Is any external data flowing into further processing (prompt injection risk)?

Step 8: Test Matrix

Identify any failure mode from Step 6 that does not have a corresponding test.

Step 9: Open Questions

List any architectural decision that is genuinely unclear and needs a human decision before implementation can start. Not a comprehensive list, only blockers.

---

## Example

**Feature**: Smart listing creation from photo (post-`/plan-pipeline:ceo-review`)

**Output excerpt**:
```mermaid
graph LR
    Upload[Photo Upload] --> Storage[Object Storage]
    Storage --> Classify[Vision Classification Job]
    Classify --> Enrich[Web Enrichment Job]
    Enrich --> DraftGen[Draft Generation]
    DraftGen --> DB[(Listings DB)]
    DraftGen --> UI[Listing Editor UI]

State machine:

stateDiagram-v2
    [*] --> pending
    pending --> classifying
    classifying --> enriching
    classifying --> classification_failed
    enriching --> draft_ready
    enriching --> enrichment_partial
    enrichment_partial --> draft_ready
    draft_ready --> published
    draft_ready --> discarded

Failure modes:

• Classification fails -> degrade to manual listing (not silent failure)
• Enrichment partially fails -> use what succeeded, flag missing fields
• Upload succeeds, classification job never starts -> orphaned file, cleanup job required
• Web data in draft generation -> prompt injection vector, sanitize before passing to LLM

---

Pipeline Position

/plan-pipeline:ceo-review    -> product direction locked
/plan-pipeline:eng-review    -> architecture locked        <- you are here
/plan-pipeline:start         -> produce implementation plan
/plan-pipeline:validate      -> validate before execution
/plan-pipeline:execute       -> execute to merged PR