# Sdd Orchestrator

> Orchestrate SDD workflows across 8 layers (BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN) using the framework's per-layer weighted review crews (framework/governance/REVIEW_CREWS.yaml) with per-lens playbook injection, dispatched as parallel subagents.

- Skill: `vladm3105/sdd-orchestrator` (Agent Skill, multi-file: 166 files)
- Install (CLI): `npx skillmds@latest add vladm3105/sdd-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vladm3105/sdd-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: vladm3105 (https://skillmd.com/u/vladm3105)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/vladm3105/sdd-orchestrator

---


# SDD Orchestrator — Specification-Driven Development Workflow Engine

## Overview

You orchestrate the SDD lifecycle across 8 document layers using the framework's **per-layer weighted review crews** — the closed lens set defined in `framework/governance/REVIEW_CREWS.yaml` (one crew of ~5-6 weighted lenses per layer), each lens injected with its per-`(layer, lens)` playbook from `framework/playbooks/<NN>_<LAYER>/` (LAYER-PLAYBOOKS-001, `framework/governance/REVIEW_TEAM.md` §Playbooks). Unlike the legacy UCX system that concatenated all persona texts into a single prompt, you dispatch each crew lens as a **parallel subagent** for concurrent review, then reduce their per-lens scores to a weighted-average readiness score (see "Chairperson Scoring" below).

### Mandatory Governance Load (Before Any SDD Work)

Before creating, reviewing, or remediating ANY SDD document, load the governance protocol:

```
skill_view(name='sdd-orchestrator', file_path='references/governance-load-protocol.md')
```

This single file condenses the planning-first rules from GOVERANCE_RULES.md §2b/§3, DEFINITION_OF_DONE.md plan/IPLAN review level, and DEVELOPMENT_WORKFLOW_GUIDE.md §2. **Skip this load step = governance violation.**

If the protocol file is missing or stale (after a UCX framework sync), fall back to loading the three governance docs individually via:

```
skill_view(name='sdd-orchestrator', file_path='governance/GOVERNANCE_RULES.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEFINITION_OF_DONE.md')
skill_view(name='sdd-orchestrator', file_path='governance/DEVELOPMENT_WORKFLOW_GUIDE.md')
```

These docs contain the planning-first gates (§3), Definition of Done for plan/IPLAN review level,
the single-path layer model (§7 — no depth tiers; necessary-upstream contract), plan types and
storage rules (§2b), and the full agent operating model.

Governance docs are read **directly from the repository** (`framework/` tree); per D-0013 (aidoc-flow migration), there is no local sync — re-stale-checks are not needed.

## SDD Layer Sequence

```
BRD (L1) → PRD (L2) → EARS (L3) → BDD (L4) → ADR (L5) → SPEC (L6) → TDD (L7) → IPLAN (L8) → Code
```

### Layer Descriptions

| Layer | Artifact | Purpose | Upstream | Downstream |
|-------|----------|---------|----------|------------|
| L1 | BRD | Business requirements, objectives, scope | — | PRD |
| L2 | PRD | Product features, user stories, ADR topics | BRD | EARS |
| L3 | EARS | Formal requirements (WHEN-THE-SHALL-WITHIN) | BRD, PRD | BDD |
| L4 | BDD | Executable acceptance scenarios with spec_trace | BRD, PRD, EARS | ADR |
| L5 | ADR | Architecture decisions (Context-Decision-Consequences) | BRD, PRD, EARS, BDD | SPEC |
| L6 | SPEC | Component interfaces, data models, behavior contracts | BRD, PRD, EARS, BDD, ADR | TDD |
| L7 | TDD | Test case definitions, BDD-to-test mapping, quality thresholds | BRD through SPEC | IPLAN |
| L8 | IPLAN | Execution plan: file manifest, bash commands, session handoff | BRD through TDD | Code |

### What Was Cut from v2

| Cut | Replaced By |
|-----|-------------|
| SYS (L6) | ADR captures architecture; PRD captures scope |
| REQ (L7) | EARS + BDD spec_trace provide requirement-to-spec links |
| CTR (L8) | SPEC interface contracts handled inline |
| TSPEC (L10) | TDD (L7) with embedded test case definitions |
| TASKS (L11) | IPLAN (L8) execution bridge with session handoff |

## Review Crews (authority: `framework/governance/REVIEW_CREWS.yaml`)

The review model is **not** a flat pool of personas dispatched uniformly. Each layer
has one **weighted crew** — a closed set of ~5-6 lenses whose weights sum to 100 and
drive the weighted-average readiness score. `framework/governance/REVIEW_CREWS.yaml` is
the **single source of truth** for every crew's author lens, review lenses, and weights;
read it at dispatch time rather than relying on any copy. Lens names there (`architect`,
`business_analyst`, `auditor`, `chaos_engineer`, `security_engineer`, `tech_lead`,
`qa_lead`, `operator`, `integration_lead`, `requirements_specialist`, `product_owner`,
`synthesizer`, …) are the runtime identity — dispatch a subagent per lens.

**One illustrative crew** (BRD review), showing the shape — see `REVIEW_CREWS.yaml` for
the other eight (PRD, EARS, BDD, ADR, SPEC, TDD, IPLAN, CHG):

```yaml
BRD:
  author: business_analyst
  review: {architect: 30, business_analyst: 30, auditor: 20, chaos_engineer: 12, security_engineer: 8}
```

Each dispatched lens is injected with its per-`(layer, lens)` playbook from
`framework/playbooks/<NN>_<LAYER>/<lens>.md` (LAYER-PLAYBOOKS-001, `REVIEW_TEAM.md`
§Playbooks). Do not maintain a second copy of the weights here — that drifts from the
authority.

---

---

## Hermes Agent as SDD Strategy Execution Runtime

When the SDD pipeline defines an autonomous strategy (trading agent, monitoring system, etc.), Hermes Agent can serve as the runtime orchestrator instead of building a custom execution engine. This replaces the traditional IPLAN→Code execution path with Hermes-native scheduling, MCP integration, and skill-based rule execution.

Pattern documented in: `references/hermes-agent-sdd-runtime-pattern.md`

Key integration points:

- **cronjob**: Schedule check windows at precise times (market hours, daily scans)
- **skills**: Load SDD documents as decision rules — soft updates via skill patches
- **MCP servers**: Register broker/external system MCP servers as Hermes tools
- **memory**: Persist state across sessions (positions, account data, idempotency keys)
- **gateway**: Multi-platform operator alerts (Telegram, Discord, etc.)

Cost comparison: ~1 developer-week + $5-10/month (LLM inference) vs 4-6 developer-weeks + $200/month for custom orchestrator.

See ADR-21 for a complete implementation example (TradeGent CC).

**NO SDD DOCUMENT MAY BE CREATED, REVIEWED, OR REMEDIATED WITHOUT A WRITTEN AND APPROVED PLAN.**

Before any document creation (Phase 1), the following planning package MUST exist and be explicitly approved by the human:

### Required Planning Artifacts

1. **Planning Roadmap** — `plans/ROADMAP.md` or `governance/plans/ROADMAP.md` listing all intended SDD layers and their dependencies
2. **Planning Index** — `governance/plans/README.md` or `.hermes/plans/README.md` listing required plan documents
3. **Changelog Plan** — Document tracking expected changes per layer
4. **IPLAN or Development Plan** — `governance/plans/PLAN-NNN_{slug}.md` (preferred) or `.hermes/plans/YYYY-MM-DD_HHMMSS-{slug}.md` per the `plan` skill

### Planning Gate Checklist (Execute Before Phase 1)

- [ ] Planning roadmap exists for project scope
- [ ] Planning index lists required plan artifacts
- [ ] Changelog plan exists for issue scope
- [ ] Planning gap review completed (resolved or deferred with rationale)
- [ ] IPLAN or development plan exists and is explicitly approved by human
- [ ] Human has explicitly approved proceeding to document creation

**If any checklist item is missing: STOP. Do not proceed to Phase 1. Create the missing artifact or ask the human for direction.**

For a deeper, 10-category audit covering changelog plans, gap reviews, index registration, dependency completeness, roadmap timing, ADR topic coverage, scope boundaries, section outlines, CHG governance, and validation pre-checks, see `references/plan-gap-review-checklist.md`.

### BRD-to-Source Coverage Audit (For BRD Layer Initialization)

When initializing a project's BRD layer from a large source document (rulebook, strategy doc, etc.):

1. **Extract all section headers** from the source document — use `grep -n '^# '` for markdown, or equivalent for the format
2. **Build a coverage matrix**: each source section → proposed BRD assignment + rationale
3. **Identify gaps**: unassigned sections, vague assignments ("folded into BRD-X" without explicit rationale), content blocks between section boundaries not captured by any header
4. **Verify 100% coverage** — every source unit must have an explicit BRD home or a deliberate exclusion with rationale
5. **Check for orphan content** — sections with no natural BRD home may indicate missing BRDs in the architecture

This audit must complete and be approved before any BRD extraction begins. The output is a table in the planning roadmap showing source section → BRD mapping with line spans.

### UCX Governance Compliance

This phase implements the UCX `DEVELOPMENT_WORKFLOW_GUIDE.md` §2 "Planning-First Requirement":
> Before implementation starts, complete this sequence: create planning roadmap → create planning index → define changelog plan → run planning gap review → create and approve IPLAN.

Reference: `governance/templates/PROJECT_KICKOFF_PLAN-TEMPLATE.md` for project-level planning structure.

---

### Batch ADR Generation from BDD

For the complete ADR generation pipeline across 19 documents (9 engine + 10 cross-cutting), see `references/adr-generation-from-bdd.md`. This reference captures:

- Pre-generation checklist (hash fixes, validation verification)
- Subagent timeout workaround (pre-extract upstream data, direct write_file, retry-on-timeout pattern)
- UCX sdd_validate template interference bug and workaround (moving 3 template files to /tmp)
- Benchmark-first strategy (ADR-01 + ADR-07 first, then batch engine ADRs, then cross-cutting)
- Cross-cutting ADR topics (Event Bus, Auth, Calendar, Idempotency, Regulatory/WORM, Observability, Alerting, Backpressure, Input Validation, Encryption)
- BDD deferred findings → ADR coverage matrix
- ADR numbering convention (ADR-01-09 = engines, ADR-10-19 = cross-cutting)

### Broker Backend Integration Architecture (Two-Layer MCP Pattern)

For the complete broker backend integration architecture — Internal API + per-broker MCP servers with Interactive Brokers — see `references/broker-mcp-architecture-pattern.md`. This reference captures the reusable pattern for any broker API integration project: two-layer separation, MCP protocol selection, connection lifecycle, idempotency strategy, and cross-cutting ADR dependencies (ADR-10/13/17/18/19). Also covers the full SDD pipeline (BRD-10→PRD-10→EARS-10→BDD-10→ADR-20) with scenario counts and document references.

### Cross-Document Registration Sweep (Layer Completion)

When a full pipeline (BRD→PRD→EARS→BDD→ADR) is completed for a document number NN, run a registration sweep across ALL index files:

1. `plans/README.md` — update plan status + add new rows in SDD Document Artifacts table for each layer
2. `01_BRD/BRD-00_index.md` — add to document registry table
3. `02_PRD/PRD-00_index.md` — add row after template row (format: `| [PRD-NN](./PRD-NN.yaml) \| Title \| Status \| Related BRD \| Features \| Priority \| Date |`)
4. `03_EARS/EARS-00_index.md` — add row after template row
5. `04_BDD/BDD-00_index.md` — add row after template row
6. `05_ADR/ADR-00_index.md` — add row to architecture index table
7. `CHANGELOG.md` — add pipeline entry under [Unreleased] with all layer versions and scores
8. `plans/BRD-PLANNING-ROADMAP.md` — update status to COMPLETE
9. Each layer document: update `downstream_expected` to reference the actual downstream document IDs (e.g., "see PRD-10", "see EARS-10")
10. ADR cross-cutting: verify the new ADR references all relevant cross-cutting ADRs (idempotency, rate limiting, validation, secrets, event bus)

### sdd_validate UCX Template Interference (ADR Layer)

The UCX validator discovers template files across the entire project tree AND framework directories.
Templates containing `id: ADR-NN` (or `_id: ADR-NN`) collide with the parse stream and cause spurious
validation failures even when the actual document is structurally valid.

**Files that must be temporarily moved (4 locations):**

- Project: `UCX/templates/layers/05_ADR/ADR-TEMPLATE.yaml`
- Framework: `framework/layers/05_ADR/ADR-TEMPLATE.yaml`
- MCP: `ucx_hermes/templates/ADR-TEMPLATE.yaml` AND `mcp_ucx/templates/ADR-TEMPLATE.yaml`
- Legacy: `ai_dev_ssd_flow_v2/05_ADR/ADR-TEMPLATE.yaml`

**Workaround**: Move all 4+ files to /tmp, validate, check score, restore. The document will show
1 error ("Missing canonical layer template") — this is a false positive. The actual document has
0 cross-section errors and 0 warnings.

**Do NOT patch `_id: ADR-NN` to `_id: ADR-00`** — the validator still discovers framework-level
templates that cannot be patched (read-only framework directories).

**Restore immediately after validation** — `sdd_init` regenerates any missing templates.

### Inline ADR Review (No Executor Required)

When UCX `sdd_review` executors are unavailable (no API keys, auth failures) or the 48KB
review prompt would time out subagent dispatch, run the 5-persona review **inline** in the main
agent context by reading ADR sections and applying persona criteria directly.

See `references/adr-review-inline-pattern.md` for the full pattern, review template structure,
metadata update conventions, and common P1 finding categories.

### Subagent Timeout Recovery (Large Document Generation)

When subagent generation times out at 600s on large documents (>50KB output expected):

- Pre-extract upstream data into the subagent prompt (don't make subagent read 6 files)
- Retry solo on timeout — check file mtime; if advanced, subagent wrote before timing out
- Fall back: build YAML via execute_code and write_file directly
- ADR-04 needed 5 dispatch attempts; ADR-09 needed direct write_file after 3 timeouts

### delegate_task Parameter Format

`delegate_task` has two modes. Do NOT mix them — the function rejects hybrid calls:

- **Batch mode**: `delegate_task(tasks=[{context, goal, role, toolsets}, ...])` — passes a JSON array
- **Single mode**: `delegate_task(context=..., goal=..., role=..., toolsets=[...])` — passes individual fields

Error symptom: "Provide either 'goal' (single task) or 'tasks' (batch)." This fires when you pass
both `tasks` (array) AND individual task parameters in the same call. Fix: pick one mode and use it
consistently. Batch mode is preferred for parallel dispatch. Single mode for targeted remediation.

### Batch PRD Generation from BRDs

After all BRDs are validated and reviewed, generate PRDs for each BRD.

### Quality Gate (from TradeGent CC 2026-05-07 Review)

**5/5 persona reviewers independently rejected "lightweight" PRDs as unbuildable stubs.**
A feature PRD with one generic core capability (e.g., "Product delivers [feature] as specified in BRD-XX" with acceptance criterion "All BRD acceptance criteria met — target 100%") IS NOT A VALID PRD. It is a placeholder shell. The EARS layer 3 cannot formalize requirements from stubs. The entire SDD pipeline stalls.

**Correct pattern**: Decompose EVERY BRD functional requirement into a PRD core capability with:

- Hash-level BRD references: `@brd: BRD.NN.07.xxxx` (not document-level `@brd: BRD-NN`)
- Populated diagram_contract with containers + data_flows (not empty `{}`)
- User journeys with alt/else error branches
- Feature-specific error messages with actionable guidance
- adr_topic_elaboration in traceability section
- 3-7 capabilities per feature PRD, 3-5 user stories, 370-450 lines

The umbrella PRD remains full-detail (500+ lines). Feature PRDs follow the same pattern at ~400 lines each.

For the complete batch generation script, see `references/batch-prd-generation-from-brds.md`.

### Batch Pipeline Execution — Single Feature Branch (BRD→BDD)

When a single new feature BRD needs to be carried through all downstream layers
in one session with inline review at each layer, use the sequence in
`references/batch-pipeline-execution.md`. Covers per-layer persona assignments,
common fix types, metadata update patterns, and cross-layer consistency checks.

## EARS Generation from PRDs (Layer 3)

After all PRDs are validated, reviewed, and remediated, generate EARS documents.

### EARS Syntax Enforcement (Critical — from TradeGent CC 2026-05-07)

PROHIBITED QUALIFIERS (replace with quantified targets):
  "real-time" → "WITHIN 60 seconds" | "immediate/immediately" → "WITHIN N seconds"
  "continuously" → "at each [event]" | "fast/quickly" → "p50 < Nms, p95 < Nms"
  "near X" → "within 0.0Y of X"

STRUCTURAL RULES:

  1. No compound WHEN with AND — split into atomic requirements
  2. No nested IF inside SHALL — each conditional path is a separate requirement
  3. WITHIN must reference a specific event (not orphaned "WITHIN 5 minutes")
  4. IF/WITHIN must reference the same event
  5. No subjective criteria ("acceptable", "reasonable", "significant")
  6. Atomicity: one testable concept per requirement
  7. Quantify interval ranges (not "every 15-25 min")

STATE MACHINE: every EARS touching operational modes MUST include a state_machine
  section with AUTONOMOUS → WARNING → HALTED → MANUAL → RECONCILING states and
  full transition triggers.

For the complete EARS rules, state machine template, and batch generation script,
see `references/ears-generation-pattern.md`.

### Benchmarks-First Strategy

1. Generate 2 benchmark EARS from the strongest upstream sources (umbrella + core feature)
2. Validate both with sdd_validate
3. Review with the EARS crew (per `REVIEW_CREWS.yaml`): requirements_specialist (35), tech_lead (25), qa_lead (20), chaos_engineer (12), security_engineer (8)
4. Remediate findings
5. Once validated, batch-generate remaining 7 EARS with execute_code

## Batch BDD Generation from EARS (Layer 4)

After all EARS are validated and reviewed, generate BDD acceptance scenarios with the same benchmarks-first strategy documented below. The full generation pattern — including the Python build_bdd() function, safe YAML serialization with comparison-operator quoting, and validation workflow — lives in `references/batch-bdd-generation-from-ears.md`.
For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see `references/bdd-batch-review-remediation.md`.
For the post-generation review, remediation, and deferral rules (5-persona parallel review, chairperson scoring, ADR-blocked deferrals), see `references/bdd-batch-review-remediation.md`.

After BDD layer completion (all docs health >= 8), plan the ADR layer before generation. `references/adr-layer-planning-and-gap-review.md` covers: topic inventory (BDD deferred findings + PRD adr_topics + BRD constraints), engine vs cross-cutting categorization, coverage matrix construction, gap review methodology, pre-generation checklist, and anti-patterns.

### BDD Scenario Mapping Rules

Every BDD document must translate EARS requirements into executable Given-When-Then scenarios:

- **Event-driven EARS** → success scenarios: extract WHEN from statement as Given/When, THE-SHALL as Then
- **State-driven EARS** → success scenarios: WHILE condition as Given, monitoring cycle as When, behavioral outcome as Then
- **Unwanted-behavior EARS** → error scenarios: IF condition as Given, detection as When, escalation/logging as Then
- **Ubiquitous EARS** → dedicated success scenarios: verify completeness across all decision types (queryable, immutable, structured)
- At least 1 recovery scenario per BDD (state transition restoration, post-failure reconciliation, transient retry)
- Minimum 5 scenarios per BDD: 3-4 success, 1-2 error, 1 recovery
- Benchmark BDDs (umbrella + core engine) should reach 13-19 scenarios after review/remediation

### Pragmatic Remediation Scope (What Belongs Where)

Not every finding from a persona review belongs at the BDD layer. Apply this triage:

| Finding Type | Remediate In | Rationale |
|-------------|-------------|-----------|
| Missing EARS requirement coverage | **BDD** | BDD's job is to cover all formal requirements |
| State machine transition gaps | **BDD** | Transitions are behavioral — testable as scenarios |
| Gherkin syntax/executability issues | **BDD** | BDD is the acceptance-test artifact |
| Tag/priority mismatches, dead data | **BDD** | Document quality, fix immediately |
| Alert dedup/idempotency scenarios | **BDD** | These are behavioral contracts |
| OAuth token lifecycle, credential storage | **ADR/SPEC** | Architecture and interface contracts, not acceptance tests |
| Regulatory reporting hooks | **ADR/SPEC** | Belongs in architecture decisions and interface specs |
| DST/market holiday, circuit breaker handling | **ADR/SPEC** | System-level behavior contracts |
| Concurrent failure, clock skew, cascading triggers | **ADR/SPEC** | Integration/chaos testing at SPEC/TDD level |

**Concrete ADR-deferral catalog** (TradeGent CC batch proven):

| BDD Finding | Deferred to | Why | Example |
|-------------|-------------|-----|---------|
| AuthN/AuthZ for scenario execution | SPEC §security | Needs role hierarchy and auth contract | OAuth2/OIDC, RBAC per role |
| Pre-trade risk gate (fat-finger, size limits) | ADR §risk-model | Needs gate placement decision | Max position size, notional cap |
| Idempotency and deduplication | SPEC §reliability | Needs exactly-once strategy | Duplicate scenario rejection |
| Race conditions and concurrent execution | ADR §concurrency | Needs locking model | Market-state transition race |
| Edge cases (DST, market holidays, clock skew) | ADR §calendar | Needs calendar service design | Holiday close → no trading |
| Timing assertions (WITHIN tolerance) | SPEC §performance | Needs latency contract | p95 < 200ms for alert dispatch |
| Parameterized tables (matrix scenarios) | SPEC §data | Needs data contract schema | Strike-price × expiry matrix |
| Circuit breakers and cascading failure | ADR §resilience | Needs resilience architecture | Broker-down → halt open orders |
| Regulatory reporting hooks | SPEC §compliance | Needs event stream design | SEC 606 report, audit log |

The general rule: if a scenario requires mocking an external service, time-travel harness,
or multi-system coordination to test, it likely belongs at SPEC (interface contracts) or TDD (integration test definitions), not BDD (user-facing acceptance criteria).

### Batch Delegate Concurrency

The `delegate_task` function enforces `max_concurrent_children` (default 3). When dispatching 5-persona BDD reviews, split into two calls: first call dispatches 3 subagents, second call dispatches 2. Both calls run in parallel since they're separate `delegate_task` invocations. Total wall-clock time equals the slower batch, not the sum.

```
# Correct — two parallel delegate_task calls, 3+2 split
delegate_task(tasks=[qa-lead, technical-lead, chaos-engineer])  # batch 1
delegate_task(tasks=[sre, security-auditor])                    # batch 2
```

## UCX Template Discovery for PRD Creation

The UCX `sdd_create_build` tool discovers available templates in the project tree:

```python
# Try layer-specific template first
sdd_create_build(doc_type="prd", layer="02_PRD", template="02_PRD-TEMPLATE.yaml")
# Fall back to generic
sdd_create_build(doc_type="prd", layer="02_PRD", template="PRD-TEMPLATE.yaml")
```

If templates are not found, run `sdd_init(project_path)` to scaffold the project with template files. After init, re-run `sdd_create_build` to confirm template discovery.

**Pre-flight checklist before PRD generation**:

1. `sdd_preflight(context="create")` — confirms project state and next action
2. `sdd_create_build` — confirms template availability
3. If either fails, run `sdd_init` then retry
4. Generate plan in `plans/PLAN-NNN_prd-generation.md` and get human approval

## PRD Diagram Section Placement

The UCX validator checks for `diagrams.items` at the **top level** of the PRD document, NOT nested under `functional_requirements` or other sections.

```yaml
# WRONG — validator sees this as missing
diagram_contract:
  diagrams:
    items: [...]

# RIGHT — top-level diagrams section
diagrams:
  id: "PRD.01.diagrams.a1b2"
  directory: "diagrams/"
  format: "SVG from Mermaid"
  items:
    - id: "PRD.01.diagrams.c3d4"
      title: "Container Diagram"
      file: "diagrams/prd-01_containers.mmd"
      source: "C4-L2 description"
      scope: "container"
```

### sdd_next_action Layer Gate

After all PRDs are generated and validated, call `sdd_next_action(document="02_PRD")` to confirm the layer's next stage. The response shows:

- `current_stage`: "created"
- `existing_artifacts`: list of all PRD files in the layer
- `next_action`: "validate" (or "review" if already validated)
- `next_tool`: "sdd_validate"

This gate confirms all documents are visible to the UCX tooling before proceeding to review or next layer (EARS).

### PRD-to-BRD Traceability

Every PRD must reference its upstream BRD:

```yaml
traceability:
  upstream:
    brd_references:
      - "@brd: BRD-01.04.78a9 (business_objectives.goals)"
      - "@brd: BRD-01.07.f79d (functional_requirements)"
  downstream_expected:
    - {type: "EARS", layer: 3, description: "Formal requirements"}
  cross_links:
    depends: ["@depends: BRD-01"]
    discoverability:
      - "@discoverability: PRD-02 (feature product requirements)"
```

For umbrella PRDs, populate `discoverability` with all 8 feature PRDs. For feature PRDs, reference the umbrella PRD and any directly related feature PRDs.

## Phase 1: Document Creation (UCC)

### Workflow

1. Receive the target document type and any reference/upstream materials
2. Load the appropriate YAML template from UCX (see Templates section below)
3. Dispatch the layer's **author lens** (the `author:` field of the layer's crew in
   `REVIEW_CREWS.yaml`) to draft the document following the template structure
4. Validate output against layer schema

### Creation Author

Each layer's author is the single `author:` lens of its crew in
`framework/governance/REVIEW_CREWS.yaml` (e.g., BRD → `business_analyst`, PRD →
`product_owner`, EARS → `requirements_specialist`, ADR/SPEC → `architect`, BDD/TDD →
`qa_lead`, IPLAN → `tech_lead`, CHG → `integration_lead`). Read the file for the current
assignment rather than relying on a copy. The multi-lens crew reviews the draft in Phase 2.

### Creation Prompt Rules

For BRD creation, enforce:

- All required sections present per the current `framework/layers/01_BRD/BRD-TEMPLATE.yaml` (that template is the authority for the section set — do not enumerate a fixed list here; it drifts from the schema)
- YAML frontmatter with `doc_id: "BRD-{NN}"`
- Element IDs: `TYPE.NN.SS.xxxx` (4-segment format per naming standards: e.g., `BRD.01.07.a7f3`)
- When uncertain about a requirement, DOCUMENT THE UNCERTAINTY rather than omit it
- No TBD/TODO items without explanation

For PRD creation, enforce:

- User stories with acceptance criteria
- Feature prioritization (MoSCoW)
- MVP scope boundary
- User personas and journeys

For ADR creation, enforce:

- Context-Decision-Consequences format
- Each decision has documented alternatives considered
- Trade-off analysis present

For TDD creation, enforce:

- Test pyramid: 70% unit / 20% integration / 10% e2e
- Every BDD scenario maps to one or more TDD test cases
- Test case format: inputs, expected outputs, edge cases
- Quality thresholds from SPEC must be reflected in test assertions
- Tests MUST be defined before implementation (test-first TDD)

For IPLAN creation, enforce:

- File manifest: one entry per deliverable file with status (NOT_STARTED/PARTIAL/COMPLETED)
- Bash commands: executable one-liners only, no interactive prompts
- Session handoff: `sessions: []` at creation — the trail is appended by each
  session as it ends, never carried forward while authoring
- Execution order: test files FIRST, then implementation files
- Partial work tracking: description of in-progress work for resumption

---

## Phase 2: Document Review (UCR)

### Workflow

1. Receive the document to review
2. Dispatch ALL listed persona subagents **in parallel**
3. Collect all findings from each subagent
4. Dispatch **fact-checker** to cross-validate all P0/P1 findings
5. Dispatch **board-chairperson** to synthesize, de-duplicate, score, and produce final manifest

### Review Persona Assignments (Dispatch Phase)

Dispatch **the layer's crew** from `framework/governance/REVIEW_CREWS.yaml` — one parallel
subagent per `review:` lens, each injected with its `framework/playbooks/<NN>_<LAYER>/<lens>.md`
playbook. Read `REVIEW_CREWS.yaml` for the current crew + weights; do not rely on a copy here.
(Illustrative: the BRD crew is `{architect: 30, business_analyst: 30, auditor: 20,
chaos_engineer: 12, security_engineer: 8}`.) The `synthesizer` lens plays the chairperson
reduce (see "Chairperson Scoring").

### Inline BRD Review (No Executor Required)

When UCX `sdd_review` executors are unavailable or the user prefers inline reviews,
use the BRD crew's lenses (per `REVIEW_CREWS.yaml`) directly in the main agent context.

See `references/brd-review-inline-pattern.md` for the full pattern, review template
structure, common P1 finding categories, and differences from the ADR inline review.

### Review Post-Processing (Sequential, After Parallel Dispatch)

After ALL parallel subagents return findings:

1. **fact-checker**: Cross-validate all P0/P1 findings against the document. Remove false positives, correct categories.
2. **board-chairperson** (the `synthesizer` lens): Synthesize verified findings, de-duplicate, compute the weighted-average lens score, produce final manifest with readiness verdict.

### Review Prompt Rules

- **FALSE NEGATIVES ARE UNACCEPTABLE.** When in doubt, FLAG IT.
- Every finding must include: Target File, Target Section, exact path
- Classify findings as P0 (critical/blocking), P1 (high), or P2 (medium)
- Pre-validation errors (YAML schema, missing fields) are infrastructure issues — report separately, do NOT count in P0 finding count

### Chairperson Scoring

The readiness score is the **weighted average of the crew's per-lens `lens_score`s**,
using the per-layer weights in `framework/governance/REVIEW_CREWS.yaml` (renormalised over
the lenses that actually ran), **then capped** by unresolved blocking findings:

- Each dispatched lens returns a `lens_score` (0-100) for the document.
- `score = Σ(lens_score × weight) / Σ(weight)` over the lenses that ran.
- **Cap:** an unresolved **P0** ⇒ fail (score 0); an unresolved **P1** ⇒ score capped
  below the gate threshold.
- **Coverage:** if the lenses that ran fall below the crew's quorum, flag *low-confidence →
  human review*.

The numeric score is **advisory**; the deterministic gate (per `REVIEW_TEAM.md`) is the
structural `sdd_doc_lint` floor **plus** "no unresolved P0/P1". Gate threshold: **≥90/100**
readiness before generating the next layer (implemented in
`platforms/hermes/src/mcp_server/review/review_scoring.py`).

---

## Phase 3: Remediation (UCRem)

### Workflow

1. Receive the UCR review report and target document
2. Pre-screen findings to determine which domain fixers are needed (adaptive loading)
3. Dispatch needed domaine fixers as parallel subagents
4. Dispatch **board-chairperson** to synthesize all fixes, resolve conflicts, produce final remediation report

### Remediation Persona Assignments

| Condition | Fixer Subagents to Dispatch |
|-----------|---------------------------|
| **Mandatory (always)** | chaos-engineer, board-chairperson |
| **Architecture findings present** | system-architect |
| **Compliance findings present** | security-auditor |
| **Test/QA findings present** | qa-lead |

### Remediation Rules

- Complete `llm_completion` items FIRST
- Address `llm_only` items second
- Handle other findings third
- Verify but do NOT modify `fixer_applied` items
- The chairperson produces the final remediation manifest with execution order (auto-safe → auto-assisted → manual)

### UCX `sdd_remediate` Limitation — Structural-Only Fixes

UCX `sdd_remediate` is a **structural/schema fixer**, not a content author. It detects:

- Placeholder tokens (`xxxx`, `TBD` without explanation)
- Invalid element ID formats
- Missing required sections

It does **NOT**:

- Add new scenarios to `scenario_structure.scenarios`
- Rewrite boilerplate Gherkin steps into domain-specific language
- Generate missing success/error/recovery/audit scenario blocks
- Apply findings from narrative markdown review reports (UCREM, chairperson manifests)

**Observed behavior (TradeGent CC, 2026-05-08):**

```
sdd_remediate(document=BDD-02.yaml, remediation_report=UCREM-REPORT.md)
→ findings: 2 tier2 (placeholder, element_id)
→ derived copy: BDD-02_remediate_v2.yaml
→ applied_changes: "none (copy-only deterministic baseline)"
→ md5sum(source) == md5sum(derived) — byte-for-byte identical
```

The UCREM report described 58 content-level findings (missing Gate 3 scenarios, audit logging, recovery paths, parameterized tables). `sdd_remediate` ignored all of them because they require semantic authoring, not structural repair.

**Correct content-remediation path:**

1. Parse chairperson manifest / UCREM report into a per-document fix list
2. Dispatch `delegate_task` fixer subagents (or scripted Python patching) to rewrite YAML content
3. Subagents must explicitly write `scenario_structure.scenarios.{success,error,recovery,audit}` blocks
4. After subagent writes, verify with `yaml.safe_load()` + scenario count diff
5. Run `sdd_validate` on the rewritten file for structural confirmation only

Never assume `sdd_remediate` with a markdown report will apply content fixes. It won't.

### Subagent Content Remediation Pattern (BDD Layer)

When `sdd_remediate` is confirmed structural-only (see reproduction above), use `delegate_task` fixer subagents for semantic authoring. Proven at TradeGent CC 2026-05-08 for 7 BDDs.

**Dispatcher setup:**

- `delegate_task` enforces `max_concurrent_children=3`. Split docs into batches of 3 (or fewer).
- Each subagent receives: original BDD path, upstream EARS path, per-document fix list, YAML structure rules.

**Fix list per document (example: BDD-02):**

```
doc_path: /path/to/BDD-02.yaml
priority: P1| P2
cross_links: ["@depends: BDD-01"]
add_success:
  - "Gate 3 — Fundamental Health (ROE>10%, debt/equity<50%, FCF>0)"
  - "Gate 4 — Price Behavior (200-day MA proximity, no >10% gap in 90 days)"
  - "Composite Scoring (multi-factor ranking with min/max thresholds)"
add_error: []              # if none, omit
add_recovery: True         # "Recovery from Data Source Failed"
add_audit: True            # "Audit Logging for Screening Decisions"
rewrite_gherkin: True      # replace placeholders with concrete Given/When/Then
add_timing: True           # add WITHIN assertions per EARS
timing_assertions:         # exact thresholds from EARS
  - "WITHIN 5 minutes"
  - "WITHIN 10 seconds"
fix_spec_trace: True       # replace "5 (Behavior — X)" with actual EARS refs
health_score: "6/10"       # realistic, not fabricated
```

**Subagent rules:**

- Overwrite the original file; do NOT create a new path
- Scenario IDs: `BDD.NN.SS.xxxx` where `xxxx` = first 4 chars of SHA256("BDD.NN:{section}:{name}")
- After writing, verify with `yaml.safe_load()` and report scenario count breakdown
- Include upstream EARS requirement text in `spec_trace` entries (not placeholders)

**Dispatcher verification (mandatory after each batch):**

```python
import os, yaml
for f in bdd_files:
    # Check modification time
    mtime = os.path.getmtime(f)
    # Check scenario count
    with open(f) as fh:
        data = yaml.safe_load(fh)
    sc = data.get("scenario_structure", {}).get("scenarios", {})
    total = sum(len(sc.get(k, [])) for k in ["success","error","recovery","audit","edge","performance","security"])
    print(f"{f}: modified={mtime} scenarios={total}")
```

- Reject any subagent result where `mtime` is unchanged or scenario count matches pre-remediation
- Re-dispatch timed-out subagents individually (common for complex docs like BDD-05 with pre-trade risk)

**Post-remediation validation:**

- Run `sdd_validate` on each rewritten file to confirm structural compliance
- Expected: PASS, 0 errors, 0 warnings
- Do NOT rely on the subagent's own "verification" claim — validate independently

### Verification After Remediation — Disk State

Any claim that remediation is "applied" MUST be verified with a tool call in the same turn:

| Check | Tool/Method | Pass Criteria |
|-------|-------------|---------------|
| File modified | `os.path.getmtime()` | mtime > pre-remediation baseline |
| Content changed | `md5sum original derived` | Hashes differ (or mtime changed) |
| YAML valid | `yaml.safe_load()` | No YAMLError |
| Scenarios added | Count `scenario_structure.scenarios.*` | Count matches fix list |
| Structure valid | `sdd_validate` | 0 errors / 0 warnings |

**Anti-pattern**: The UCREM report claimed BDD-02 went from 7 to 15 scenarios, but `yaml.safe_load()` on the original file still showed 7. The report described intended fixes; the files were untouched. Always verify the file, never the report.

See `references/ucx-remediate-content-limitations.md` for the full reproduction transcript, the expected-vs-actual comparison, and the scripted vs. subagent remediation paths.

---

## Templates & Layer Assets

All templates are unified YAML files available as linked files in this skill:

- `framework/layers/01_BRD/BRD-TEMPLATE.yaml`
- `framework/layers/02_PRD/PRD-TEMPLATE.yaml`
- `framework/layers/03_EARS/EARS-TEMPLATE.yaml`
- `framework/layers/04_BDD/BDD-TEMPLATE.yaml`
- `framework/layers/05_ADR/ADR-TEMPLATE.yaml`
- `framework/layers/06_SPEC/SPEC-TEMPLATE.yaml`
- `framework/layers/07_TDD/TDD-TEMPLATE.yaml`
- `framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml`

Load the appropriate template from `framework/layers/<NN>_<TYPE>/<TYPE>-TEMPLATE.yaml` in the repository (e.g. `framework/layers/01_BRD/BRD-TEMPLATE.yaml`). Use the standard file-read mechanism — `skill_view` does **not** apply since templates live outside the skill (D-0013).

| Layer | Template | Upstream Tags |
|-------|----------|---------------|
| L1 BRD | `framework/layers/01_BRD/BRD-TEMPLATE.yaml` | — |
| L2 PRD | `framework/layers/02_PRD/PRD-TEMPLATE.yaml` | @brd |
| L3 EARS | `framework/layers/03_EARS/EARS-TEMPLATE.yaml` | @brd @prd |
| L4 BDD | `framework/layers/04_BDD/BDD-TEMPLATE.yaml` | @brd @prd @ears |
| L5 ADR | `framework/layers/05_ADR/ADR-TEMPLATE.yaml` | @brd @prd @ears @bdd |
| L6 SPEC | `framework/layers/06_SPEC/SPEC-TEMPLATE.yaml` | @brd @prd @ears @bdd @adr |
| L7 TDD | `framework/layers/07_TDD/TDD-TEMPLATE.yaml` | @brd @prd @ears @bdd @adr @spec |
| L8 IPLAN | `framework/layers/08_IPLAN/IPLAN-TEMPLATE.yaml` | @brd @prd @ears @bdd @adr @spec @tdd |

**All documents use `.yaml` format.** Markdown is for indexes and reference docs only.
**No subtypes** — SPEC and TDD use unified templates (no CSPEC/DSPEC/UXSPEC/RISKSPEC/PROCSPEC; no UTEST/ITEST/STEST/FTEST/PTEST/SECTEST).

Load the appropriate template before beginning creation or review.

---

## YAML Pitfalls and Safe Writing

### Values Starting with Comparison Operators

YAML parsers choke on unquoted values that begin with `>=`, `<=`, `>`, or `<`
because the leading `>`/`<` is interpreted as a block scalar chomping indicator.
This hits frequently in SDD documents where `target`, `criterion`, and `metric`
fields contain thresholds like `target: >=90%`.

**Rule: quote any field value that starts with `>=`, `<=`, `>`, or `<`.**

```yaml
# WRONG — YAMLError: expected chomping or indentation indicators
target: >=90% of candidates remain qualified

# RIGHT
target: '>=90% of candidates remain qualified'
```

### Inline Parentheses With Comparison Operators

Multi-line values with inline `>=` (e.g., `beat rate >=60%)`) also break parsing
when spread across lines. **Collapse into a single quoted string or use block
scalar (`|-`) without the problematic inline operators on separate lines.**

### Programmatic Document Generation

When generating any SDD YAML document (BRD, PRD, etc.) programmatically via
`execute_code` — including single documents with many element IDs — use the
pattern documented in `references/programmatic-sdd-generation.md`. This covers:
Python dict assembly from template structure, content-based element ID hashing,
YAML quoting post-processing, and layer-specific quality 

…(truncated)