Writing Principles

Fragment convention Writing Principles

tags

conventionagent

These apply regardless of which design loop is active:

• Describe behaviour, not implementation. Requirements state what the system does, not how. “The system must store bookmarks” is a requirement. “Use PostgreSQL” is a design decision.
• Use must / must not for mandatory requirements. Avoid should, could, might in requirement bodies — those belong in MoSCoW priority attributes, not prose.
• \{% tldr %\} is mandatory on every document and must use scope="public agent".
• Never leave a reference unverified. Before writing a qualified id anywhere, confirm the document exists.
• Domains model behaviour; features expose UI. If a domain document is asked to include UI, redirect to a feature instead.
• Every new document starts with status: draft. Do not set status: ready unless the user explicitly confirms the document is complete.
• Flows are always standalone files. Never embed a flow inside a feature document.