synaptiai Project Modeling
Phase 2. Builds the one model that all 23 documents are views over, and the vocabulary they all use.
Iron Law
ONE MODEL, MANY VIEWS. If a view needs a new fact, the fact goes in the model first.
The moment a document invents a component name, an owner, or a boundary that the model does not carry, the package has two models. It will not notice, and the contradiction surfaces during diligence rather than during drafting.
What the model contains
| Element | Captures | Where it surfaces |
|---|---|---|
| Product intent vs implemented behaviour | What it is for, and what it actually does — separately | 01-project/ |
| Actors, journeys, roles, permissions | Who does what, and what they may do | 01-project/, 02-architecture/ |
| Components and deployment units | Purpose, owner, runtime, interfaces, state, criticality | 02-architecture/components-and-codebase.md |
| Interfaces and contracts | Producers, consumers, transport, versioning | 02-architecture/interfaces-and-integrations.md |
| Data and its lifecycle | Stores, classes, residency, retention, deletion | 02-architecture/data-and-ai.md |
| Infrastructure and environments | Topology, promotion path, differences between environments | 02-architecture/infrastructure-and-deployment.md |
| Boundaries | Control, data, trust, failure, tenancy | Everywhere. The most load-bearing element |
| Owners and decision rights | Who owns, who decides, who escalates | 00-control/terminology-and-ownership.md |
| Lifecycle and target state | What exists now vs what is planned | Every document, kept visibly distinct |
| Assets, dependencies, licenses, risks | Provenance and exposure | 05-due-diligence/ |
Every element is an evidence-backed claim. A component with no evidenced owner is unassigned — never the last committer, never the most active contributor. During an incident, a fabricated owner is worse than an admitted gap.
Classify first
Classify the project from evidence before modelling it, and record the classification with its supporting evidence IDs. The classification changes which elements carry weight — not which files exist. See references/project-type-adaptation.md.
Do not force web-service assumptions onto a library, a model, a device, or an offline tool. A library's "deployment" is a registry publish; a device's "rollback" may not exist at all.
Test the model against three flows
A model that has not been walked end to end is a diagram, not a model. Trace at least:
- One primary user or business flow — entry point through to the effect the user cares about
- One change-to-production flow — commit through test, review, build, deploy, and rollback
- One credible failure, recovery, or abuse flow — a dependency outage, a partial failure, a malicious input, or an incident from alert to recovery
Where one is genuinely inapplicable, substitute a different flow and explain why — never silently drop it. A project with no deployment still has an artifact-publication flow; a project with no users still has a consumer.
Each trace either confirms the model or produces a gap. Both outcomes are valuable; only the first is comfortable. Trace failures become AQ- or CT- rows before any drafting begins, because a model corrected in Phase 2 costs one edit and a model corrected in Phase 6 costs a rewrite of everything downstream.
These same traces are what verification pass B later attempts to falsify. Record them explicitly so the pass can execute them independently rather than inventing its own.
Canonical names
Every entity gets one authoritative name in TM-####, plus its aliases. Aliases are not noise — source material genuinely uses old names, and a reader who greps for the old one must land somewhere.
Name these classes: product and project; components, services, modules, repositories, packages; user, customer, administrator, and operator roles; environments and deployment units; external systems and partners; data classes and domain entities; interfaces and events; owners and teams.
Once recorded, the canonical name is used in all documents. A document that calls the same service by two names inside one file is a Medium finding; two documents disagreeing is a High one, because a reader cannot tell whether they describe one system or two.
Projecting to views
A view selects and abstracts. It never adds.
| Legitimate | Illegitimate |
|---|---|
| Omitting internal components from a partner view | Renaming a component to sound cleaner externally |
| Generalizing "PostgreSQL 15 on RDS" to "a managed relational database" | Describing a boundary that the model does not carry |
| Dropping evidence IDs from public text | Dropping a limitation that made the claim true |
| Summarizing five failure modes as "degrades to read-only" when that is what all five do | Summarizing them that way when one does not |
The public projection has its own rules and its own gate — see disclosure-gating. This skill's obligation is narrower and absolute: the underlying model must be identical across every view.
Current versus target
Keep them visibly separate in the model itself, not just in prose. A model that merges "the planned event bus" with "the current synchronous call" produces an architecture document describing a system nobody has built.
Planned elements carry a planned marker and the evidence for the plan — an approved decision record, not a conversation. A plan with no approved record is R at best and frequently U.
Output Format
Write the model to <outputRoot>/00-control/.project-model.json and the vocabulary to 00-control/terminology-and-ownership.md.
## Canonical Entities
| ID | Canonical name | Class | Aliases | Definition | Owner | Evidence |
|---|---|---|---|---|---|---|
| TM-0001 | {name} | component / role / environment / data-class / interface / external-system | {old names} | {one sentence} | {role or `unassigned`} | [EV-####] |
## Ownership
| Area | Component owner | Decision owner | Operational owner | Documentation owner | Bus-factor concern |
|---|---|---|---|---|---|
## End-to-End Traces
### Trace {N}: {name} ({primary | change-to-production | failure})
| Step | Component | Interface | State touched | Evidence | Confirms or contradicts model |
|---|---|---|---|---|---|
The ownership table's unassigned entries and bus-factor concerns feed 05-due-diligence/ directly. Do not soften them.
Rationalization Prevention
| Excuse | Response |
|---|---|
| "The partner guide needs a simpler name for this service" | Then the canonical name is wrong, or the simplification is a lie. Fix one; do not maintain two. |
| "I will trace the flows after drafting the architecture" | Then the architecture document is a hypothesis and everything downstream inherits its errors. |
| "This component has no owner in any file, but Alex touches it most" | unassigned. Commit frequency is not ownership, and paging the wrong person at 3am is a real cost. |
| "The diagram is clearer if I add this connection" | Every node and edge needs evidence. An inferred connection is labelled inferred, in the internal document, or it is not drawn. |
| "The team is migrating to the new architecture, so I will document that" | Document what exists, mark what is planned, and cite the approved decision. A target state written as current is a false statement. |
| "Both names appear in the code, so both are canonical" | One is canonical, the other is an alias. Pick using evidence and record the alias. |
| "The third trace does not apply to this project" | Then substitute one and say why. Silently running two traces is not running three. |
Integration
Invoked in Phase 2 of /dossier:baseline and re-validated by /dossier:refresh when the blast radius touches components, interfaces, data, or infrastructure. Loaded by dossier-pass-b-falsification, which attempts to break the traces recorded here. Every dossier-doc-drafter dispatch receives the model as input.
References: references/project-type-adaptation.md, references/register-schemas.md, references/package-contract-02-architecture.md.