Instruction file imported from federicogerardi/gen-app-2 (.github/instructions/dominio-ubiquitous-language.instructions.md). Copyright stays with the author.

Domain Ubiquitous Language — gen-app-2

Purpose

• Keep domain terminology consistent across all files: TypeScript source (src/, frontend/src/), tests, and documentation under docs/.
• Ensure the same concept is always named with one canonical term across all four bounded contexts.
• This instruction is the first reference to consult before naming, renaming, or reviewing any domain concept in code or docs.

Canonical DDD References (Read First)

Canonical GUI Governance Reference (Mandatory For GUI Work)

Apply this reference whenever the intervention touches GUI code or GUI-facing docs (for example React components, page layouts, table/list pages, design-system documentation).

Canonical Bounded Contexts (gen-app-2)

• Generation — artifact lifecycle, XState actors, stream/persistence pipeline
• Auth — user identity, sessions, roles, OAuth
• Usage/Quota — quota enforcement, audit history, project scoping
• Frontend/UI — tool page orchestration, briefing upload, step flow, readiness

Critical Term Pairs (must not be conflated)

Rules

• Define one canonical term per concept before editing docs.
• Reuse canonical terms in all sections, headings, and tables.
• If synonyms exist, keep one canonical term and list others as aliases in the glossary Aliases And Deprecated Terms table.
• Prefer domain terms over technical implementation jargon in user-facing docs.
• Mark uncertain terms as provisional until confirmed by DDD analysis.
• For GUI interventions, map each page to one UI archetype from frontend-ui-ubiquitous-language-spec.md before changing layout or naming.
• For GUI table pages, enforce Data Table View composition and canonical table behavior from frontend-ui-ubiquitous-language-spec.md.
• For tool input-file guidance and setup rules, enforce ToolInputFileRequirementPolicy (DDD-081): single-file tools keep the first file always required; multi-file tools keep only the first file always required and classify each subsequent file explicitly as required or optional by tool setting.
• For GUI layout composition, avoid nested cards by default. Use nested cards only when strictly necessary for semantic grouping that cannot be expressed with spacing, dividers, or typography; nested cards increase cognitive load and visual heaviness.
• For refactor-only interventions, keep terminology unchanged: if a new domain term is needed at implementation time, stop the change and register a DDD-NNN entry in docs/07-governance/domain-naming-decision-log.md before propagation.
• Prefer the smallest coherent terminology change, split broad language edits into atomic updates, and reuse established canonical terms or existing doc patterns before introducing new wording.
• When applying patches, keep terminology edits atomic per concept or section; avoid broad replacements that can fail match or accidentally rewrite unrelated language.

Required Output Conventions

• Write final domain artifacts in English.
• Keep definitions concise, unambiguous, and system-specific.
• Include source evidence (file path + line) when introducing or changing a canonical term.
• New terms require a DDD-NNN entry in docs/07-governance/domain-naming-decision-log.md before propagation.

Integration Checklist

• Update docs/01-requirements/domain-ubiquitous-language-glossary.md first, then propagate to related docs.
• When a new bounded context section is added to the glossary, also update docs/02-design/domain-bounded-context-map.md.
• Ensure docs/index-overview.md points to any newly added domain document.
• Avoid duplicate glossary files; extend existing domain docs whenever possible.