Ddd Review

DDD Review

Overview

Independent DDD compliance review that runs with fresh context — no attention degradation from prior coding work. Uses parallel subagent dispatch (one per bounded context + one cross-BC checker) so each BC gets isolated, fresh attention. Verifies structural compliance (architecture red lines, naming, layer responsibilities) AND behavioral correctness (business logic matches Phase 6 Behavioral Rules — state machines, invariants, scenarios) against Phase 6 Blueprint.

Foundational Principle: Review requires a baseline. Phase 6 Blueprint is the mandatory baseline for every review. Without it, the review has no reference for naming conformance, directory structure, or behavioral rules. If Phase 6 doesn't exist, this skill generates it before reviewing. There is no "lightweight review without Blueprint" path.

Architecture Principle: Each bounded context is reviewed by an independent subagent that loads only that BC's Phase 6 contract + code. This prevents context explosion (N BCs × contract size × code size) and guarantees fresh attention per BC — the same reason this skill exists in the first place.

When to Use

• Post-implementation: Orchestrator dispatches after each BC's coding-isolated-domains completes (primary use case)
• PR Review: Review a PR that modifies DDD domain/adapter code
• Periodic audit: Check DDD compliance of an established codebase
• Post-hotfix: Verify a hotfix didn't violate DDD constraints

Do NOT use when: Code has no DDD structure (use [mapping-legacy-landscape](../mapping-legacy-landscape/SKILL.md)), during initial Phase 7 coding (use [coding-isolated-domains](../coding-isolated-domains/SKILL.md) which embeds execution-time rules), or when only non-domain code changed (config, CI, docs).

Loading Guidance

This skill references supporting files on demand — do not preload them all:

• During Steps 2-7 (per-BC subagent dispatch): each subagent reads [review-subagent-reference.md](./review-subagent-reference.md) for the complete subagent prompt template, step execution details (Steps 2-7), auto-fixable vs STOP classification, and result file format.
• During Step 8 (cross-BC subagent dispatch): the cross-BC subagent reads [review-subagent-reference.md](./review-subagent-reference.md) § Cross-BC section for the cross-BC prompt template and result format.
• During Step 9 (report writing): read [review-report-reference.md](./review-report-reference.md) for the review-report.md format — History table (append-only) and Latest Review section (overwritten each round).

Quick Reference

| Step | Action | Output | |:---|:---|:---| | 1 | Ensure Phase 6 Blueprint exists and is fresh, determine BC list + project paths | Review baseline confirmed, dispatch plan ready | | 2-7 | Dispatch per-BC subagent (parallel): architecture red lines, convention tests, blueprint conformance, behavioral verification, adapter audit, magic strings | Per-BC violation list (structured) | | 8 | Dispatch cross-BC subagent (parallel with 2-7): cross-BC import scan + constraint file check | Cross-BC violation list | | 9 | Collect subagent results → handle STOP issues → persist report | docs/ddd/review-report.md + BC Progress updated |

Ambiguity Handling

Review STOP Triggers

| Ambiguity | Why STOP | |:---|:---| | Phase 6 doesn't exist and cannot be generated (no code, no Phase artifacts, empty project) | Cannot establish review baseline — review without baseline is opinion, not verification | | Complex violation found: business logic in wrong layer (server/app contains domain rules) | Requires architectural decision — moving logic between layers changes interfaces and tests | | Cross-BC boundary violation: Context A directly imports Context B's domain types | May require redesigning context boundaries or adding ACL contracts — architectural scope | | Code implements a state transition not in Phase 6 State Machine, or contradicts an invariant rule | Business logic error — may be code bug or Phase 6 spec gap. Either way, requires human judgment to determine which is the source of truth |

Review ASSUME & RECORD — proceed with explicit assumption:

| Ambiguity | Default assumption | |:----------|:------------------| | Blueprint entry for supporting utility files (helpers, converters) not found in directory scan | ASSUME legitimate domain placement if file contains only structural mapping or private helpers. RECORD in review report. | | grep path doesn't match project structure (no domain/{context}/ directories) | ASSUME standard DDD layout as described in Phase 6 Blueprint's Directory Layout section. RECORD adjustment note with actual paths used. | | Minor naming deviation from Phase 6 Blueprint (e.g., XxxService vs XxxAppService) | ASSUME acceptable if behavior matches the Blueprint's behavioral rules. RECORD deviation in review report. | | Phase 6 scenario has no matching test but the domain code logic appears correct by reading | ASSUME code is correct if logic matches Phase 6 Then/Error columns. RECORD missing test coverage in review report as a warning (not violation). |

Implementation

Step 1: Ensure Phase 6 Blueprint Is Fresh & Prepare Dispatch (Main Agent)

Phase 6 must be fresh — not just present. A stale Phase 6 makes behavioral verification meaningless and auto-fixes dangerous.

1. Check existence: Does docs/ddd/phase-6-behavior-contracts.md exist?
2. If it does NOT exist → generate:

a. Check if docs/ddd/phase-2-context-map.md exists (Phase 1-4 artifacts from snapshot or pipeline).

• If Phase 1-4 exist: Dispatch [spec-driven-development](../spec-driven-development/SKILL.md) to generate Phase 6 from existing artifacts.
• If Phase 1-4 don't exist: Dispatch [snapshotting-code-context](../snapshotting-code-context/SKILL.md) first to rebuild Phase artifacts from code, then dispatch [spec-driven-development](../spec-driven-development/SKILL.md).

b. STOP — present generated Phase 6 to human: "Phase 6 Blueprint was generated as a review baseline. Please review and confirm before I proceed with the DDD compliance review." c. Human confirms → continue. Human revises → update, then continue.

1. If it exists → check freshness: Use git diff to detect whether domain code has changed since Phase 6 was last committed. Compare the last commit touching docs/ddd/phase-6/ against the last commit touching the domain/app/adapter code directories.

• If code is newer than Phase 6 → refresh: Phase 6 is stale. Re-derive it:

a. Check if docs/ddd/phase-2-context-map.md exists (Phase 1-4 artifacts).

• If Phase 1-4 exist: Dispatch [spec-driven-development](../spec-driven-development/SKILL.md) in merge mode directly — Phase 1-4 are still valid, only code has drifted.
• If Phase 1-4 don't exist: Dispatch [snapshotting-code-context](../snapshotting-code-context/SKILL.md) first to rebuild Phase artifacts, then dispatch [spec-driven-development](../spec-driven-development/SKILL.md).

b. STOP — present refreshed Phase 6 to human: "Phase 6 Blueprint was refreshed because domain code has changed since it was last generated. Please review and confirm before I proceed." c. Human confirms → continue. Human revises → update, then continue.

• If Phase 6 is up-to-date → proceed.

1. Determine project paths: Read Phase 6 index to get BC list, then read only the § Directory Layout section from each docs/ddd/phase-6/{context}.md to extract code directory paths. Do NOT read the § Behavioral Rules sections — those are loaded by the subagents, not the main agent. If language-conventions is needed, identify the project language from build files.
2. Create result directory: mkdir -p docs/ddd/review-results/. This is where subagents will persist their results.
3. Prepare dispatch plan: List all BCs to review. Each BC becomes one subagent. Plus one Cross-BC subagent.

Steps 2-7: Per-BC Review (Subagent — one per BC, all dispatched in parallel)

Dispatch one subagent per bounded context. Read [review-subagent-reference.md](./review-subagent-reference.md) for the complete subagent prompt template including Steps 2-7 execution details.

Subagent input:

• The BC's Phase 6 contract file: docs/ddd/phase-6/{context}.md
• The BC's code directories (from Phase 6 Directory Layout)
• domain-architecture-reference.md (for red line definitions)
• Language-specific convention file path (if applicable)
• test-map.md path (if exists, for convention test regression)

Each subagent executes: Step 2 (architecture red lines), Step 3 (convention test regression), Step 4 (blueprint conformance), Step 5 (behavioral rules verification with Transition Comparison Matrix + Invariant Verification Table), Step 6 (adapter layer audit), Step 7 (magic string detection). Auto-fixable violations are fixed directly; STOP issues (unauthorized transitions, contradicted invariants, wrong-layer business logic) are reported back to the main agent.

Each subagent persists its result to docs/ddd/review-results/{context}.md before returning.

Step 8: Cross-BC Boundary Check (Subagent — dispatched in parallel with Steps 2-7)

Dispatch one cross-BC subagent. This subagent runs in parallel with the per-BC subagents. Read [review-subagent-reference.md](./review-subagent-reference.md) § Cross-BC section for the prompt template.

Subagent input:

• List of all BC names and their domain directory paths (from Step 1)
• Constraint files path pattern (e.g., .claude/rules/{context}.md)

The subagent checks cross-context domain imports (should go through contracts/ACL) and verifies constraint files exist with bidirectional import prohibitions. Persists result to docs/ddd/review-results/cross-bc.md.

Step 9: Collect & Report (Main Agent)

After all subagents return:

1. Collect results by reading docs/ddd/review-results/{context}.md for each BC + docs/ddd/review-results/cross-bc.md. These files were persisted by the subagents. If any expected file is missing (subagent failed), re-dispatch only the failed subagent(s) — do NOT re-run successful ones.
2. Handle STOP issues: If any subagent reported STOP issues (unauthorized transitions, contradicted invariants, business logic in wrong layer, cross-BC imports), present ALL of them to the human. Wait for resolution before marking review complete.
3. Persist review report to docs/ddd/review-report.md using the format from [review-report-reference.md](./review-report-reference.md). The file has two sections: a History table (one row per round, append-only) and the Latest Review (full details, overwritten each round). If review-report.md does not exist, create it with Round 1. If it already exists, read the History table to determine the next round number, append a new row, then replace the Latest Review section.
4. Update BC Progress: Update docs/ddd/ddd-progress.md Phase 7 BC Progress table (Verification column → ✅ if clean, ❌ if issues remain).
5. Clean up intermediate results: Delete docs/ddd/review-results/ directory. The individual result files are intermediate artifacts — review-report.md is the canonical output.

Single-BC Mode

When only one bounded context needs review (e.g., post-hotfix on a single BC):

1. Step 1 still runs (load index, confirm Phase 6 exists).
2. Dispatch only one per-BC subagent (no parallelism needed, but still use a subagent for context isolation).
3. Cross-BC subagent: dispatch if project has multiple BCs (a hotfix in one BC could introduce a cross-BC import). Skip if the project has only one BC — record Cross-BC check: SKIPPED (single-context) in the report.
4. Step 9 runs normally.

Orchestrator Mode Exception

When dispatched by an orchestrator after coding-isolated-domains, all steps run autonomously:

• Step 1: Phase 6 was freshly generated in the same pipeline run. The freshness check (git diff) will confirm code is not newer than Phase 6 — skip refresh. If Phase 6 is missing → return STOP to orchestrator immediately.
• Steps 2-7 subagents + Step 8 subagent: Dispatch all in parallel. Step 5 behavioral verification is especially critical post-implementation — the coding agent had attention degradation and is the most likely source of logic drift from Phase 6 specs.
• Step 9: Collect results. Return STOP for complex violations (including Step 5 unauthorized transitions and contradicted invariants). Update BC Progress.

Session Recovery

If a review session is interrupted:

1. Check docs/ddd/ddd-progress.md — read the Phase 7 BC Progress table's Verification column for each bounded context.
2. Check docs/ddd/review-results/ directory for intermediate result files. Each file represents a completed subagent:

• {context}.md exists → that BC's review (Steps 2-7) completed successfully
• cross-bc.md exists → Cross-BC check (Step 8) completed successfully
• Missing file → that subagent failed or was never dispatched

1. If Step 1 completed (Phase 6 confirmed) but no result files exist: Resume from subagent dispatch. Do NOT regenerate Phase 6.
2. If some result files exist but not all: Re-dispatch only the missing subagents. Do NOT re-run subagents whose result files exist — their work is already persisted.
3. If all result files exist but review-report.md not yet written: Resume at Step 9 — read result files and produce report.
4. If review-report.md exists and review-results/ is cleaned up: Review is complete. Check BC Progress for confirmation.

Run sh skills/full-ddd/scripts/session-recovery.sh for a quick status report.

Self-Check Protocol

Follow the [Persistence Defense Reference](../ddd-protocol/persistence-defense-reference.md) after Step 9, with these context-specific items:

1. Phase 6 Blueprint was loaded or generated — not assumed from memory. Verify docs/ddd/phase-6-behavior-contracts.md was read (not recalled from a prior session).
2. Each BC was reviewed by an independent subagent — verify subagent dispatch happened (not inline review). If platform doesn't support subagent dispatch, verify the limitation was noted.
3. Every subagent persisted its result file — before Step 9, verify docs/ddd/review-results/{context}.md exists for every BC and docs/ddd/review-results/cross-bc.md exists. Missing files mean subagent failed — re-dispatch before continuing.
4. Every subagent produced Step 5 Transition Comparison Matrix AND Invariant Verification Table — behavioral verification cannot be "all pass" without showing the comparison evidence. If any BC's Step 5 has no matrices/tables, it was skipped.
5. Cross-BC subagent was dispatched and persisted — verify docs/ddd/review-results/cross-bc.md exists (or Cross-BC was correctly skipped for single-context projects).
6. Review report persisted — Verify docs/ddd/review-report.md exists and contains results from ALL subagents.
7. Intermediate results cleaned up — Verify docs/ddd/review-results/ directory was deleted after review-report.md was written. If it still exists, the review is incomplete.
8. BC Progress updated — Verify docs/ddd/ddd-progress.md Verification column is updated for each reviewed bounded context.
9. Auto-fix code changes saved — If any subagent reported auto-fixes in its "Auto-fixed" section, spot-check one fixed file per BC to verify the change landed on disk.
10. Phase 6 generation confirmed — If Phase 6 was generated in Step 1 (not pre-existing), verify human confirmed it before subagent dispatch.

If any check fails → STOP. Complete the missing action before claiming review complete.

Note: This skill has no platform hooks. When invoked by an orchestrator ([full-ddd](../full-ddd/SKILL.md), [iterating-ddd](../iterating-ddd/SKILL.md), [piloting-ddd](../piloting-ddd/SKILL.md), [restructuring-ddd](../rest

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lockp111
• Source: lockp111/agent-ddd-engineering
• License: MIT

Install and usage instructions live in the source repository linked above.