# Ddd Aggregate

> DDD Aggregate Skill

- Skill: `thapaliyabikendra/ddd-aggregate` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add thapaliyabikendra/ddd-aggregate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thapaliyabikendra/ddd-aggregate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: thapaliyabikendra (https://skillmd.com/u/thapaliyabikendra)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/thapaliyabikendra/ddd-aggregate

---


# DDD Aggregate Skill

Reads existing DDD specification documents across all 5 layers for a specific feature scope and produces a unified Implementation Readiness Spec (IRS). Two output formats: **technical** (for GSD milestones, backend architects, sprint planning) and **business** (for GitLab issues, business analysts, stakeholder review).

This skill does NOT generate DDD layer documents -- that is the `ddd-docs` skill. This skill CONSUMES existing layer documents and synthesizes them into actionable feature specs.

## Prerequisites

Before using this skill, the bounded context must have at minimum:
- L1: VISION.md or GLOSSARY.md
- L2: At least one AGGREGATE_*.md or BC Spec
- L3: At least one BDS_*.md scenario set

L4 and L5 are optional but improve output quality. The skill will flag missing layers in the gap report.

## Workflow

### Step 1 -- Identify Feature Scope

When the user asks to aggregate specs, determine the scope:

| User says... | Scope type | What to scan |
|---|---|---|
| "aggregate specs for lc-management" | Full BC | All docs in `docs/layer{1-5}/lc-management/` |
| "aggregate IssueLC feature" | Single command | L2 aggregate owning the command + L3 BDS for that command + relevant L1/L4/L5 |
| "aggregate Document Presentation" | Single aggregate | L2 aggregate def + all L3 BDS referencing it + relevant L1/L4/L5 |
| "aggregate import LC issuance flow" | Feature slice | Multiple aggregates/commands involved in the flow + their L3 scenarios |
| "prepare GitLab issues for amendments" | Business format | Same as above but output in business format |

If scope is ambiguous, ask the user to clarify:
1. Which bounded context? (e.g., `lc-management`)
2. Which aggregates or commands? (e.g., `LetterOfCredit.IssueLC` or "the full amendment flow")
3. Which output format? (technical or business -- default to technical if unclear)

### Step 2 -- Locate Source Documents

Scan the documentation tree for the identified bounded context:

```
docs/
  layer1/{bc-slug}/     -- VISION.md, GLOSSARY.md, CONTEXT_MAP.md, BOOTSTRAP_GAP_REPORT.md
  layer2/{bc-slug}/     -- IMPORT_LC_SPEC.md, AGGREGATE_*.md, EVENT_CATALOG.md, *_CONTEXT_SPEC.md
  layer3/{bc-slug}/     -- BDS_*.md
  layer4/{bc-slug}/     -- CONTRACT_*.md (if exists)
  layer5/{bc-slug}/     -- DDR-*.md, ADR-*.md
```

Read every file in the matching directories. For command-scoped or aggregate-scoped requests, read all files but extract only relevant sections.

### Step 3 -- Extract Vertical Slice

For each source document, extract the sections relevant to the feature scope:

**From L1 (Strategic Intent):**
- VISION.md: Problem statement, target users relevant to this feature, success criteria
- GLOSSARY.md: Terms used by the aggregates and commands in scope
- CONTEXT_MAP.md: Relationships involving the bounded context that owns this feature
- BOOTSTRAP_GAP_REPORT.md: Open questions relevant to this feature

**From L2 (Domain Model):**
- BC Spec (e.g., IMPORT_LC_SPEC.md): Purpose, aggregates table, domain events, quality constraints, dependencies
- AGGREGATE_*.md: Identity, responsibility, invariants, lifecycle states, commands, domain events raised -- only for aggregates in scope
- EVENT_CATALOG.md: Events raised by commands in scope, their consumers and payloads

**From L3 (Behavioral Spec):**
- BDS_*.md: All scenarios for commands in scope -- happy path, failure, boundary conditions, idempotency
- Coverage matrix status for each command

**From L4 (Integration Contracts):**
- CONTRACT_*.md: Cross-context contracts where the in-scope bounded context is a participant
- Data schemas, failure protocols, ACL mappings

**From L5 (Decision Records):**
- DDR-*.md / ADR-*.md: Decisions that affect the aggregates, commands, or events in scope
- Active constraints from the Constraint Register that apply

### Step 4 -- Gap Check

Before generating output, check for missing coverage. Report gaps as one of three severities:

| Severity | Meaning | Example |
|---|---|---|
| `blocking-implementation` | Cannot generate implementation code without this | Command defined in L2 but no L3 BDS scenarios exist |
| `blocking-design` | Design ambiguity that must be resolved before implementation planning | L1 glossary term referenced in L2 but not defined; conflicting invariants |
| `informational` | Nice to have, does not block work | No L4 integration contract for a cross-context event consumer; no L5 DDR for a non-obvious choice |

Gap detection rules (apply all that match):

1. **Command without scenarios**: L2 aggregate defines a command but no L3 BDS file covers it -> `blocking-implementation`
2. **Aggregate without definition**: L3 BDS references an aggregate that has no L2 AGGREGATE_*.md -> `blocking-implementation`
3. **Event without catalog entry**: L3 BDS or L2 aggregate raises an event not in EVENT_CATALOG.md -> `blocking-design`
4. **Term not in glossary**: L2/L3 docs use a domain term not defined in L1 GLOSSARY.md -> `blocking-design`
5. **Cross-context event without contract**: EVENT_CATALOG.md lists external consumers but no L4 contract exists -> `informational`
6. **Non-obvious decision without DDR**: L2 aggregate has an `internal` method or unusual invariant but no L5 DDR explains why -> `informational`
7. **[TO BE DEFINED] placeholders**: Any source doc contains `[TO BE DEFINED]`, `[TBD]`, or `[TODO]` -> severity depends on section (invariant = `blocking-implementation`, quality constraint = `informational`)
8. **Missing layer entirely**: No L1 docs exist for the BC -> `blocking-design`; no L3 docs -> `blocking-implementation`
9. **Stale references**: A DDR references a document that no longer exists or has been renamed -> `informational`

### Step 5 -- Choose Output Format

Determine which format to produce based on user intent:

| User intent | Format | Template |
|---|---|---|
| GSD milestone, sprint planning, architecture review | Technical | `references/technical-format.md` |
| GitLab issue, stakeholder summary, business review | Business | `references/business-format.md` |
| Both | Both | Generate both files |

Read the appropriate template from `references/` before generating. Follow the template structure exactly.

Consult `references/aggregation-rules.md` for what to include vs. exclude per format.

### Step 6 -- Generate Aggregated Spec

Read the chosen template from `references/` and produce the output document. Key rules:

1. **Every claim must trace to a source document.** Use inline references like `(L2: AGGREGATE_LETTER_OF_CREDIT.md, INV-LC-003)` or `(L3: BDS_ISSUE_LC.md, Scenario 2)`.
2. **Do not invent information.** If a source doc does not cover something, flag it as a gap -- do not fill it with assumptions.
3. **Use the ubiquitous language from the glossary.** Do not paraphrase domain terms.
4. **Preserve invariant IDs, event names, and command names exactly as they appear in source docs.** These are load-bearing identifiers for downstream code generation.
5. **Group by feature flow, not by source layer.** The output should read as a coherent feature description, not as "here is what L1 says, here is what L2 says."
6. **Flag contradictions explicitly.** If L2 and L3 disagree on a command's behavior, note the contradiction and which document should be authoritative.

### Step 7 -- Write Output Files

Save output to `docs/features/{feature-slug}/`:

```
docs/features/{feature-slug}/
  FEATURE_SPEC.md           -- Technical format (if requested)
  ISSUE_SPEC.md             -- Business format (if requested)
  TRACEABILITY_MATRIX.md    -- Always generated
```

The `{feature-slug}` is a kebab-case name derived from the feature scope:
- Full BC: `lc-management` (same as bc-slug)
- Single command: `issue-lc`
- Single aggregate: `document-presentation`
- Feature slice: `lc-amendment-flow`

The TRACEABILITY_MATRIX.md is always generated regardless of format choice. It maps every section of the output back to the source documents with file paths and section headings.

## Output Quality Checks

After generating, verify:

- [ ] Every invariant ID referenced matches an invariant in the source L2 doc
- [ ] Every scenario referenced matches a scenario in the source L3 doc
- [ ] Every event name matches the EVENT_CATALOG.md entry
- [ ] Every domain term matches the GLOSSARY.md entry
- [ ] No [TO BE DEFINED] placeholders were silently dropped -- they appear in the Open Questions section
- [ ] The TRACEABILITY_MATRIX.md has an entry for every section of the output
- [ ] Gap check results are included in the output (Open Questions section for technical, Open Questions section for business)
- [ ] Implementation stories (technical format) reference specific commands and aggregates, not vague descriptions

## Key Principles

- **This skill is a reader, not a writer of DDD docs.** If gaps are found, recommend running `ddd-docs` to fill them -- do not generate L1-L5 docs from this skill.
- **Traceability is non-negotiable.** Every statement in the output must trace to a source document. If it cannot be traced, it is either a gap (flag it) or an invention (remove it).
- **The output serves two audiences.** Technical format serves developers and architects who will implement the feature. Business format serves analysts and stakeholders who will validate scope and acceptance criteria. Never mix the two -- keep each format focused on its audience.
- **Preserve machine-readable identifiers.** Invariant IDs (INV-LC-003), event names (LCIssued), command names (IssueLC), error codes (INSUFFICIENT_MARGIN) must appear exactly as in the source docs. These identifiers are used by the `ddd-docs` consistency checker and by code generation tools.
- **Freshness matters.** Always read source documents at generation time -- do not rely on cached knowledge of what the docs contain. Documents evolve between skill invocations.