System design
Create the smallest set of views that answers the user's question. Prefer editable .drawio for formal diagrams; honor requested notation, format, course rubric, and existing files. A valid XML file is not proof of a correct model.
Workflow
- Establish the audience, system boundary, question, scenario, and abstraction level. Read supplied requirements/schema/code and any rubric. Record uncertain cardinalities, permissions, lifecycle rules, and external interfaces as assumptions; ask only when they materially change the answer. Do not invent infrastructure or mandatory relationships.
- Choose views using the routing table below. Read only the relevant references plus
diagram-validation.md. Distinguish current-state evidence from proposed design. Keep a small glossary with stable concept IDs when multiple diagrams share concepts. - Build a semantic inventory before placing shapes: participants/elements, relationships with direction and endpoint meaning, constraints, and requirement IDs. For a DFD, add a flow dictionary and decomposition boundary signatures; for a data model, identify keys and dependencies.
- Follow the diagram-specific drawing procedure. Set notation explicitly (e.g. UML 2, Crow's Foot, Gane–Sarson; context then level-0). Separate semantic rules from recommended layout choices. Resolve conflicting sources as described in
sources.md. - For Draw.io, read
drawio-rendering.mdandlayout.md. Create native shapes and connectors with stable IDs, using an XML serializer. Copy a relevant example only after replacing its domain facts. For other formats readfallbacks.md. - Run
python3 <skill-dir>/scripts/validate_drawio.py <file-or-directory>. Repair reported structural errors. Use the semantic and cross-view checklists: the script cannot prove UML, DFD, ERD, or BPMN correctness. - Open/import in diagrams.net or export using an available Draw.io renderer. Inspect every page for labels, arrow ends, clipping, containment and crossings; adjust and inspect again. If no renderer works, deliver the editable source and explicitly report rendering as unverified. Do not call XML parsing an openability test.
- Deliver source files, useful previews, and a brief verification/assumption note. State exactly which checks ran. Preserve existing manual layout and unrelated pages during edits; refresh stale previews.
Reference routing
| User's question | Read |
|---|---|
| UML choice / notation baseline | uml.md |
| Actors and user goals | use-case.md |
| Domain or software structure | class-diagram.md |
| One scenario across collaborators | sequence-diagram.md |
| Workflow, branches, concurrency | activity-diagram.md |
| One entity's event-driven lifecycle | state-machine.md |
| Instances, links, modules, runtime placement | structural-views.md |
| Communication, timing, interaction overview | advanced-interactions.md |
| Entities, relationships, relational schema | erd.md, normalization.md |
| Data movement and decomposition | dfd.md, context-diagram.md |
| Architecture levels | c4-model.md |
| Business collaboration/process | bpmn.md |
| Simple procedure or responsibility handoffs | flowchart-swimlane.md |
| Output generation / polishing | drawio-rendering.md, layout.md, fallbacks.md |
| Review / multi-view consistency | diagram-validation.md |
| Source provenance / editions / limitations | sources.md |
Output convention
Honor the user path. Otherwise use docs/diagrams/<system>-<view>.drawio, with matching .svg or .png previews when possible. Use <system>-assumptions.md for nontrivial assumptions and <system>-validation.md for multi-view audits. Keep temporary exports outside final deliverables. Use separate files for independently maintained views, or named pages for a coordinated set. Never silently replace a requested formal notation with a generic flowchart.
Non-negotiable checks
- Model facts must come from evidence or labeled assumptions.
- Check endpoint semantics; an arrow pointing the wrong way can remain syntactically valid.
- A DFD arrow carries data; UML/BPMN control flow carries execution meaning.
- Do not infer lifecycle ownership from a foreign key or a vague “has-a” phrase.
- Review relevant shared concepts; do not require identical contents across views of different scope.
- Keep drawings editable; an image embedded in a
.drawiofile is not a native diagram.
Examples and executable checks are in examples/ and scripts/. Package-specific testing evidence is in TEST-REPORT.md.