generate-realization

What this skill does

# Generate Use Case Realization

**You are the Core Orchestrator** for use case realization generation — producing the behavioral specification layer (Layer 3) that bridges use cases (Layer 2) to implementation.

## Your Role

**You orchestrate multi-agent workflows. You do NOT execute bash scripts.**

When the user requests this flow (via natural language or explicit command):

1. **Interpret the request** and confirm understanding
2. **Read this template** as your orchestration guide
3. **Identify target use case(s)** — single or batch
4. **Launch agents via Task tool** in correct sequence
5. **Synthesize results** and finalize artifacts
6. **Update traceability** and report completion

## Natural Language Triggers

Users may say:
- "Generate realization for UC-001"
- "Create behavioral spec for UC-042"
- "Realize UC-007"
- "Generate all use case realizations"
- "Create the Layer 3 specs"
- "Realize all use cases"
- "Build the behavioral specifications"
- "Generate realizations for all architecturally significant use cases"
- "Create sequence diagrams for UC-NNN"
- "Add DES-UCR for UC-NNN"

You recognize these as requests for this orchestration flow.

## Parameters

### UC-NNN (positional, required unless --all)

The use case ID to generate a realization for: `UC-001`

The orchestrator reads the use case document from `.aiwg/requirements/UC-NNN.md` (or any `.aiwg/requirements/UC-NNN*.md` match).

### --all (optional)

Batch generate realizations for all use cases found in `.aiwg/requirements/UC-*.md` that do not already have a corresponding realization in `.aiwg/requirements/realizations/`.

When `--all` is set:
- Glob all `UC-*.md` files in `.aiwg/requirements/`
- Skip any UC that already has a `DES-UCR-NNN.md` in `.aiwg/requirements/realizations/`
- Process remaining use cases sequentially to control context budget
- Report a completion table at the end

### --guidance (optional)

**Purpose**: User provides upfront direction to tailor the realization approach.

**Examples**:
```
--guidance "Focus on security flows — this system handles PII"
--guidance "Emphasize async patterns, we use event-driven architecture"
--guidance "Be thorough on error paths — this is a payment flow"
--guidance "Include state machine specs for all stateful entities"
```

**How to Apply**:
- Pass guidance verbatim to all agent prompts as additional context
- Guidance influences: depth of error path coverage, security emphasis, diagram density
- Guidance does not override completeness criteria

### --interactive (optional)

**Purpose**: Ask clarifying questions before generating to tailor output.

**Questions to Ask** (if --interactive):

```
I'll ask a few questions to tailor the realization:

Q1: What is the primary architectural concern for this use case?
    (e.g., security, performance, reliability, data consistency)

Q2: Are there known integration points or external systems involved?
    (Help me include the right participants in sequence diagrams)

Q3: Should I generate supplementary specs if I find stateful entities
    or complex branching? (State machine specs, decision tables)

Q4: Are there existing ADRs that constrain this realization?
    (e.g., "we use event sourcing", "REST only, no gRPC")

Q5: Who will review this realization?
    (Helps me calibrate depth and formality)
```

## Multi-Agent Orchestration Workflow

### Pattern

```
Architecture Designer (primary author)
    ↓ draft DES-UCR-NNN.md
Parallel Reviewers (single message, all at once):
    ├── Security Architect     → auth/authz gap analysis
    ├── Test Architect         → testability + test scenario extraction
    └── Domain Expert          → business logic accuracy
    ↓ all reviews complete
Documentation Synthesizer
    ↓ merges feedback → final DES-UCR-NNN.md
Archive → .aiwg/requirements/realizations/
```

**Critical**: Launch all three parallel reviewers in a **single message** with multiple Task calls.

---

### Step 1: Initialize

**Your Actions**:

1. **Parse parameters** — determine UC-NNN or --all batch mode
2. **Read the target use case(s)**:
   ```
   Glob: .aiwg/requirements/UC-NNN*.md
   Read: matched file(s)
   ```
3. **Read architecture inputs**:
   ```
   Read: .aiwg/architecture/software-architecture-doc.md
   Glob: .aiwg/architecture/adr/*.md
   Read: matched ADR files
   ```
4. **Check for existing realizations** (skip if present):
   ```
   Glob: .aiwg/requirements/realizations/DES-UCR-NNN.md
   ```
5. **Ensure output directory exists**: `.aiwg/requirements/realizations/`

**Communicate Progress**:
```
✓ Use case loaded: UC-NNN — {title}
✓ Architecture document loaded
✓ ADRs loaded: {count} decisions
⏳ Starting realization generation...
```

---

### Step 2: Primary Author — Architecture Designer

**Purpose**: Create the initial use case realization draft with sequence diagrams and component mapping.

```
Task(
    subagent_type="architecture-designer",
    description="Create use case realization draft for UC-NNN",
    prompt="""
    Read the use case realization template:
    $AIWG_ROOT/agentic/code/frameworks/sdlc-complete/templates/analysis-design/use-case-realization-template.md

    Read the target use case:
    .aiwg/requirements/{UC-NNN}.md

    Read the architecture document:
    .aiwg/architecture/software-architecture-doc.md

    Read all ADRs from: .aiwg/architecture/adr/

    Using the template and source documents, generate a complete use case realization:

    REQUIRED SECTIONS:
    - Metadata block (ID: DES-UCR-NNN, status: draft, dates, related IDs)
    - Traceability (parent UC, SAD section, ADRs referenced)
    - Use Case Summary (actor, scope, level, trigger, pre/postconditions)
    - Participating Components table (every actor and component with interface)
    - Main Success Scenario — MermaidJS sequenceDiagram
    - Alternate Flows (≥2 alternates if present in UC)
    - Exception Flows (all exception paths from the UC)
    - Component Responsibilities section
    - Completeness checklist (all items evaluated)

    DIAGRAM REQUIREMENTS:
    - Use MermaidJS sequenceDiagram syntax
    - Maximum 15 participants per diagram; split into sub-diagrams if needed
    - Every UC step must map to at least one message in the sequence diagram
    - Show activation boxes for long-running operations
    - Include return messages for synchronous calls

    SUPPLEMENTARY SPECS — generate these if applicable:
    - State machine spec (DES-SM-NNN.md) if the UC involves stateful entities
      (entities with lifecycle states like: order, session, workflow, subscription)
    - Decision table (DES-DT-NNN.md) if the UC has ≥3 branching conditions
    - Method interface contracts (DES-MIC-NNN.md) for each key method identified
      in the sequence diagrams (one contract per method, minimum 3 for complex UCs)

    ADDITIONAL GUIDANCE (if provided):
    {guidance}

    Save the primary draft to:
    .aiwg/working/realizations/DES-UCR-NNN-draft.md

    If supplementary specs are generated, save to:
    .aiwg/working/realizations/DES-SM-NNN-draft.md (if applicable)
    .aiwg/working/realizations/DES-DT-NNN-draft.md (if applicable)
    .aiwg/working/realizations/DES-MIC-NNN-draft.md (if applicable)

    At the end of your output, list:
    - SUPPLEMENTARY_SPECS: [SM | DT | MIC | none]
    - STATEFUL_ENTITIES: [entity names or none]
    - BRANCH_CONDITIONS: [count or 0]
    - KEY_METHODS: [method names or none]
    """
)
```

**After primary author completes**:
```
✓ DES-UCR-NNN draft complete
⏳ Launching parallel review (3 agents)...
```

---

### Step 3: Parallel Review (single message — all three at once)

**Launch all three reviewers in one message:**

```
# Reviewer 1: Security Architect
Task(
    subagent_type="security-architect",
    description="Security review of DES-UCR-NNN realization draft",
    prompt="""
    Read the use case realization draft:
    .aiwg/working/realizations/DES-UCR-NNN-draft.md

    Read the original use case:
    .aiwg/requirements/{UC-NNN}.md