Reference — generated from the toolkit

Source of truth: toolkit/skills/design-generation/spec.md. Edit it there; this page is regenerated on build.

Skill: design-generation

• Owner: AI + Design (with Data)
• Version: 0.1.0
• Lifecycle: draft
• Phase: design

Trigger

UX flows are approved and the technical design artefacts need drafting: C4 sketches and a data model that Build agents can consume without inventing shapes. Invoked once per product/feature after flows pass review, and re-invoked when an approved flow changes.

Inputs → outputs

• Inputs: approved UX flows (Mermaid + narrative), the ready PFD, the domain brief, and the reference architectures.
• Outputs: C4 context + container sketches (Mermaid) mapped to a reference-architecture shape, and a draft data model — ERD in Mermaid/DBML with every field sensitivity-classified (public / internal / client-confidential / regulated-PII), retention noted, and ACORD mapping candidates listed. Both are drafts for the Data + Security review at the Design Review gate.

Procedure

1. Parse the approved flows; derive candidate entities, relationships and state transitions from what the flows actually touch — including error and empty states.
2. Draft the ERD per the data-model template; apply the data-model governance naming conventions.
3. Classify every field's sensitivity and note retention. Where classification is uncertain, default to the more restrictive class and raise it as a question — never leave a field untagged.
4. Propose ACORD mappings where entities align with standard elements; mark non-mappings explicitly.
5. Sketch C4 context and container diagrams, mapping the product onto a reference-architecture shape and noting the UK-insurance non-negotiables (audit trail, PII handling, retention).
6. List every derivation it could not ground in a flow or the PFD as an open question, and emit the pack for Data + Security review.

Guardrails & permissions

• Read-only on flows, PFD and brief; writes only the design artefacts. Standard agent guardrails apply.
• No untagged fields, ever — an untagged field is a hard failure, not a warning.
• Does not select technology — containers in the C4 sketch are shapes and responsibilities, not product names. Stack choice belongs to Tech Selection.
• Outputs are drafts: Data + Security review is required and cannot be waived at the Design Review gate. Schema migrations downstream are irreversible actions — this skill only ever proposes.

Failure modes

• Under-classifying PII (mitigated: restrictive-by-default rule; detected: Data + Security review, PII-tagging lint).
• Inventing entities or fields no flow touches — speculative modelling (mitigated: every entity must trace to a flow step or PFD rule; detected: traceability check at review).
• Missing entities implied by error/empty states (mitigated: procedure step 1 explicitly walks non-happy paths).
• ACORD mis-mapping (mitigated: mappings are candidates for the Data specialist, never asserted).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
MTA journey flows	fixture flows + PFD	data model with policy/MTA/party entities, all seeded PII fields tagged regulated-PII	100% field tagging; seeded PII correctly classed
Ambiguous entity	flow referencing an undefined "account holder"	open question raised, restrictive placeholder classification	question flagged, no silent guess
Speculative-model bait	flows covering a narrow slice	no entities beyond what flows/PFD ground	zero unfounded entities at review