# Principle Driven Development catalog These principles are starting points. Adopt only the rules that tell the truth about your system. --- # PDD-01@v1 — Use Ubiquitous Language Version: v1 Lineage: Domain-Driven Design (DDD) ## Rule Use Ubiquitous Language in conversations, documents, tests, interfaces, and code. Give each domain concept one stable name. Use that name in every layer. Keep the established DDD name for this pattern. The name connects the rule to the wider domain model. ## Lineage Ubiquitous Language is a pattern from Domain-Driven Design (DDD). The name helps an agent examine related concepts, such as bounded contexts, entities, value objects, and domain events. These related concepts are not automatic rules. Before you adopt a concept, make sure that the domain needs it. ## Benefit People and agents can discuss the same model across every layer. Good names remove many explanatory comments. The recognized pattern name also gives new agents useful context before they inspect the implementation. ## Problem this prevents Placeholder names survive after the domain concept becomes clear. Different layers then use different words for the same idea. Agents treat those words as different concepts. They add translation code, duplicate types, and comments that explain the mismatch. Generic names also hide the connection to DDD. An agent then misses relevant modeling judgment. ## What this changes - Domain experts and code use the same vocabulary. - One concept keeps one name inside a bounded context. - Placeholder names do not survive without a reason. - Reviews treat naming as part of correctness. - Comments explain hidden constraints, not unclear names. ## Exceptions External protocols keep their standard terms at the boundary. After the boundary, translate those terms into the Ubiquitous Language. If two bounded contexts use one word differently, name the context at the integration boundary. ## Start here List the terms that domain experts and developers use differently. Agree on one name and one short definition for each concept. --- # PDD-02@v1 — Validate at Use Version: v1 Lineage: Time-of-check/time-of-use (TOCTOU) ## Rule When code uses an artifact, validate the important facts. A check from creation or preview does not stay true. Make stale artifacts harmless. The use boundary must refuse an artifact that is no longer valid. ## Benefit One use-time check protects every path that reaches the boundary. Earlier code does not need to keep the artifact valid forever. Agents can stop closing each timing gap with a lock, cleanup job, or new state machine. ## Problem this prevents Code checks a fact at one time and uses the result later. The fact can change between those two actions. This gap is called a time-of-check/time-of-use issue, or TOCTOU issue. Agents often fix one gap and then find another. They repeat this work until the design contains unnecessary coordination and state. A use-time check gives all paths one correctness boundary. Earlier stale data no longer creates a safety problem. ## What this changes - Consumers check the current facts that control use. - Artifacts carry enough identity for a new check. - Revocation does not require perfect cleanup. - Background jobs check again at a clear batch boundary. - Tests change facts between creation and use. ## Exceptions An immutable fact cannot change. Name that fact before you omit the use-time check. ## Start here Name the use boundary. Then list the smallest set of facts that it must check. --- # PDD-03@v1 — Use Simplified Technical English Version: v1 Lineage: ASD-STE100 Simplified Technical English, Issue 9 Reference: https://www.asd-ste100.org/ ## Rule Use the structural rules of ASD-STE100 Simplified Technical English for technical prose. Apply these rules to agent instructions, documentation, commits, comments, reviews, errors, and release notes. If a trained reviewer does not use the official standard, do not claim formal ASD-STE100 compliance. ## Standard [ASD-STE100 Issue 9](https://www.asd-ste100.org/) is an international standard for technical documentation. The standard helps readers worldwide understand complex systems and tasks. It controls sentence structure, vocabulary, and word meaning. The standard includes 53 writing rules and a controlled dictionary. This principle does not reproduce or replace that dictionary. ## Benefit Short, active sentences reduce the number of possible interpretations. One term for one meaning helps people and agents connect text across files and sessions. Clear conditions and commands help an agent distinguish a requirement from advice or possibility. Commits and comments become useful repository evidence instead of incomplete memory. ## Problem this prevents Agents can write fluent text that hides several instructions in one sentence. A weak modal verb can turn a requirement into an option. Synonym changes can make one concept look like several concepts. Long comments and commits also hide the decision that a future contributor needs. ## What this changes - Procedural sentences contain no more than 20 words. - Descriptive sentences contain no more than 25 words. - Each procedural sentence contains one instruction. - Active voice names the person or system that does the action. - A required condition comes before its command. - One concept keeps one term. - Requirements use `must`. Possibilities use `can`. - Technical names, code, commands, paths, and quoted errors stay exact. - Necessary domain terms stay available as technical nouns and technical verbs. ## Tooling No plugin is required. A repository can enforce the rule through review, examples, lint rules, or an agent instruction. A tool can report suspicious text. A tool cannot prove that the text is correct or formally compliant. ## Exceptions If marketing copy carries no technical instruction, it can use its brand voice. Quoted text, code, identifiers, commands, and external protocol terms keep their exact form. ## Start here Add this principle to `AGENTS.md`. Then apply it to the next agent instruction, commit message, and code comment. Look first for long sentences, changing terms, passive voice, contractions, and weak modal verbs. --- # PDD-04@v1 — Do Not Let Sunk Costs Decide Version: v1 Lineage: Sunk cost fallacy ## Rule Keep work because it has current value, not because someone already spent time on it. Delete work that has no current use and no committed plan. When a real need returns, rebuild it. Git history is sufficient recovery for deleted work. The active tree must describe the current system. ## Benefit The codebase stays small and current. Contributors inspect fewer files, branches, abstractions, and configuration paths. Agents do not mistake an unused draft for an approved direction. They make decisions from active evidence. Fast implementation makes later rebuilding cheaper than continuous preservation. ## Problem this prevents Unused work becomes codebase slop. It adds files, concepts, tests, dependencies, and maintenance without current value. Agents assume that preserved code has authority. They connect new work to abandoned designs and preserve even more unused structure. The original effort then becomes the reason for more effort. This pattern is the sunk cost fallacy. ## What this changes - Current value or a committed plan must justify each preserved path. - Reviews reject speculative abstractions without a current caller. - Superseded drafts leave the active tree. - Deleted work stays recoverable through version control. - A later implementation starts from current requirements. ## Exceptions Keep work that has a named owner, a committed delivery plan, and a near review date. Until the repository reaches a recorded removal condition, keep required compatibility code. ## Start here Find files and abstractions with no caller, owner, or scheduled use. Delete them and run the repository checks. --- # PDD-05@v1 — Cite the rule, do not copy it Version: v1 ## Rule When code depends on a principle, cite its versioned token. State only the local fact that the code needs. Do not copy the full principle into comments. The principle file remains the authority. ## Benefit A version change creates a complete review list. Each old token points to code that can depend on the old meaning. Comments stay short because the full explanation remains in one place. ## Problem this prevents Copied text becomes old after the source rule changes. The copied text can still sound correct, so reviewers miss the conflict. Agents can update the main rule and leave old instructions in comments, tests, or tool descriptions. An unversioned citation creates the same problem. It does not show which meaning the code used. ## What this changes - Tokens use one stable form, such as `PDD-05@v1`. - CI rejects unknown or old tokens. - A meaning change increments the version. - A person or agent reviews each old citation before updating it. - Spelling changes do not increment the version. ## Exceptions Commit messages and merged review threads are history. They do not need citation reviews. ## Start here Add a repository search for versioned tokens. After the first principle gains code citations, add a checker. --- # PDD-06@v1 — Mark accepted risks beside the code Version: v1 ## Rule Put an `ACCEPTED-RISK:` marker beside code that accepts a known risk. State the scenario, reason, and review condition. Add this versioned principle token to the marker. One repository search must list every accepted risk. ## Benefit A future reader can see that the team made a deliberate trade. The reader does not need to repeat the original investigation. The review condition prevents permanent acceptance after the facts change. ## Problem this prevents Without a marker, a reader cannot tell a deliberate trade from an unknown defect. Agents can repeatedly report the same scenario. They can also treat an accidental behavior as approved design. Vague risk comments create another problem. Teams can use them to hide ordinary unfinished work. ## What this changes - The scenario states exactly what can go wrong. - The reason compares impact and chance with the cost of a fix. - The review condition names an observable change. - Reviewers can challenge the acceptance. - Deferred work stays in the issue tracker. ## Exceptions There are no exceptions for accepted risks. An unmarked risk has no accepted status. ## Start here Add a CI rule that requires `PDD-06@v1` on every `ACCEPTED-RISK:` marker.