Keeping Your .dai File Current
A diagram is a living document - it stays useful only if it keeps matching reality.
The point of a .dai diagram is precision: every element says exactly one true thing about your project. That makes it a living document — a model of the plan — stale after every change you don’t apply back to it. Keeping it current is a discipline, not a rewrite.
When something changes, change the diagram
The common triggers and their one-step responses:
| What happened | What you do |
|---|---|
| Strategy or plan changes | Update the Objective, re-scope Rules, retire what no longer applies |
| A requirement is clarified | Edit the Requirement; adjust related stories and tests |
| A decision gets made | Add a Decision (Business, or Software for an ADR) with context → decision → consequences; update what it affects |
| A risk materializes or dies | Move the Risk’s status or delete it; drop mitigated ones |
| A bug ships | Add an Issue; resolve/remove it when it’s fixed |
| An open question comes up | Add a Question; record the answer and act on it, then delete it |
| An assumption is confirmed or broken | Update the Assumption’s status; if it broke, act on ifWrong and delete the parts of the plan that relied on it |
| A milestone lands | Mark it achieved; clear out the interim flags that mattered only until now |
Notice the pattern: add, edit, delete — rarely archive. Because the AI reads the whole file as ground truth, a stale node actively lies about the present. Deleting is often the right instinct; if history matters, one Markdown note summarizing what changed and why beats a graveyard of superseded elements.
Housekeeping that keeps you honest
- Rename to match usage. As a document’s purpose sharpens, rename it (status-bar click, or Document → Manage → Rename…) so the URL says what it actually is. Remember that renaming changes the URL — spread the new link if the document is shared (see Sharing & Visibility).
- Download before a big restructure. Planning to cut a region loose and rewire? Document → Export → Download .dai first for a one-click snapshot you can re-upload or diff later.
- Split when a diagram stops being about one thing. The moment a file contains two projects, cut the second into its own document — select it,
⌘C, create a new document,⌘V, then delete it from the original. A too-large diagram dilutes context instead of concentrating it. - Refresh the type dictionary when meaning shifts. The type descriptions in the workflow metadata (managed via the Library panel) auto-populate once and then are yours — re-describe what a type means now, in this project.
Let the AI help maintain it
The same copy loop that executes your diagrams can renew them. Paste the current file with a prompt like “read this .dai file, suggest improvements to its structure, completeness, and clarity, then produce an updated version” — the Improve this workflow prompt in Document → DAI Builder is exactly this — then apply what you accept by hand, paste the model’s XML onto the canvas with ⌘V, or upload the result as a new document to compare against the original. A periodic pass of “explain this workflow back to me” (Explain this workflow in the DAI Builder) is the cheapest staleness detector there is: wherever the explanation surprises you, the diagram is either stale or lying.
In short
- Keep diagrams small and true rather than big and exhaustive
- Delete stale elements; notes — not graveyards — for history
- Rename promptly, snapshot before surgery, split when ideas diverge
- Run the improve/explain loop on a cadence that matches how fast the project moves
The reward: every LLM you work with, every teammate you share the link with, reads the same current truth. Accounts & Documents covers the file management mechanics; Sharing & Visibility covers the links.