| name | doc-design |
| description | Phase 3 (Design and Modeling). Use to model the data and behavior behind approved requirements - ask the SWE about entities, attributes, keys, relationships, and which flows need diagrams, then write the DDT + PlantUML and register entities. Trigger on "model the entities", "design the schema/ERD", "add a sequence/architecture diagram", "data dictionary". |
Doc: Design and Modeling (Phase 3)
Turn approved FR/UC into an explicit entity model (DDT + PlantUML) and the diagrams that describe behavior/structure. Owns Phase 3 only (ENTITY-GUIDE.md, Diagrams/README.md). Consumes doc-requirements; hands entity + design-component IDs to doc-implementation.
Inputs
- Approved FR/UC IDs and the entities named in their flows.
- Target package(s).
Process (elicitation loop)
- Read the FR/UC files and any existing
Packages/<Package>/Entities.md, Data/Entities.md.
- Ask the entity/diagram batch from the bank.
- Write: Entity Classification rows (Core/Column/Complementary + source FR/UC), attribute-level DDT rows, a PlantUML block covering the same entity set; register each entity in
Data/Entities.md; add diagrams under Diagrams/.
- Re-read; verify DDT and PlantUML describe the same entities; review each diagram for correctness (LLM diagrams must be asserted, not trusted); ask follow-ups.
- Repeat until DoD. Hand off to
doc-implementation.
Questions to ask (bank)
- Entities: Which entities appear in these requirements? Any not yet named?
- Attributes: For each entity, what attributes/columns? Which is the PK? Which are FKs (to what)?
- Types: Data type, length, nullability (Not Null Y/N) per attribute?
- Relationships: How do entities relate (1-1, 1-many, many-many)? Cardinality?
- Role: Per package, is each entity Core, Column, or Complementary?
- Ownership: Which package owns each entity?
- Diagrams: Which flows need a sequence diagram? Do we need an ERD, state, or architecture view?
Outputs (creates / updates)
Packages/<Package>/Entities.md: Entity Classification table + attribute-level DDT (Key / Data Type / Not Null / Length / FK Table / Description) + PlantUML.Data/Entities.md: entity -> package mapping + diagram reference + source FR/UC.Diagrams/: ERD / sequence / state / architecture artifacts.
Definition of Done (gate)
Every entity in a DDT row AND the package PlantUML, classified, registered with source FR/UC; each diagram reviewed for correctness. (LIFECYCLE.md Phase 3.)
Handoff
Entity + design-component references -> doc-implementation (for code-linkage) and inform doc-testing.
Guardrails
DDT and PlantUML stay in sync; attribute-level columns exact per ENTITY-GUIDE.md; ASCII; preserve templates; ask - do not speculate.
