# Writing Laws > Write formal laws and covenants for codebases using proper legal-style structure. Use when establishing inviolable standards, architectural constraints, or domain-specific rules that must be followed without exception. Use when this capability is needed. - Skill: `tomevault-io/writing-laws` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/writing-laws` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/writing-laws/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/writing-laws --- # Writing Laws Skill Use this skill when creating formal laws, covenants, or standards for a codebase. Laws are not suggestions or guidelines - they are inviolable requirements that govern behavior within a specific domain. ## Core Principle: Laws Define, They Do Not Persuade Laws state what IS and what SHALL BE. They do not: - Explain why (that belongs in preambles) - Describe consequences (that belongs in severity classifications) - Use conditional or hedging language - Appeal to preference or opinion ## Law Structure ### Section Numbering Laws use hierarchical section notation with the section symbol (§): ``` § I - Roman numerals for major laws § I.1 - Decimal for subsections § I.1.a - Lowercase letters for sub-subsections ``` ### Section Naming Each section receives a bracketed name that serves as its short identifier: ``` § VII [The Atom Suffix Convention] § VIII [The Confinement of Atoms] § XII [The Service Yield] ``` ### Internal References Reference other sections by their number and name: ``` As required by § III [The Export of the Live Layer], ... This law supersedes § IV.2 when ... See § IX [The Action Patterns] for related requirements. ``` ## Legal Language ### Mandatory Modal Verbs | Verb | Meaning | Usage | |------|---------|-------| | SHALL | Absolute requirement | `[Subject] SHALL [action].` | | SHALL NOT | Absolute prohibition | `[Subject] SHALL NOT [action].` | | MUST | Equivalent to SHALL | `[Subject] MUST [provide/include/satisfy].` | | MUST NOT | Equivalent to SHALL NOT | `[Subject] MUST NOT [action].` | | IS REQUIRED TO | Alternative to SHALL | `[Subject] IS REQUIRED TO [action].` | | IS PROHIBITED FROM | Alternative to SHALL NOT | `[Subject] IS PROHIBITED FROM [action].` | | IS HEREBY DECREED | Declarative establishment | `IT IS HEREBY DECREED that ...` | ### Definitional Language | Phrase | Purpose | |--------|---------| | `[Term] means ...` | Define a term | | `[Thing] is [classification]` | Classify something | | `Any [X] that [condition]` | Define scope by condition | | `For purposes of this section` | Limit scope of definition | | `includes but is not limited to` | Non-exhaustive list | ### Classification Language ``` Any [thing] that [exhibits property] is [classified as] [category]. Any [action] that [meets criteria] constitutes [violation type]. ``` ## Law Templates ### Simple Prohibition Law ```markdown ## § X [Name] **IT IS HEREBY DECREED** that [subject] SHALL NOT [prohibited action]. [Subject] that [exhibits prohibited behavior] constitutes a violation of this law. ``` ### Simple Requirement Law ```markdown ## § X [Name] **IT IS HEREBY DECREED** that [subject] SHALL [required action]. The [required element] MUST [satisfy condition]. [Additional requirements]. ``` ### Multi-Part Law ```markdown ## § X [Name] **IT IS HEREBY DECREED** that [general principle]. ### § X.1 [First Aspect] [Subject] SHALL [requirement 1]. ### § X.2 [Second Aspect] [Subject] SHALL NOT [prohibition]. ### § X.3 [Exception] This law does not apply when [exception condition]. ``` ### Definition Law ```markdown ## § X [Definitions] For purposes of these covenants: **"[Term A]"** means [definition]. **"[Term B]"** includes: - [item 1] - [item 2] - [item 3] **"[Term C]"** does not include [exclusion]. ``` ## Document Structure ### Preamble The preamble establishes WHY the laws exist. It uses WHEREAS clauses: ```markdown ## PREAMBLE WHEREAS [foundational truth 1]; WHEREAS [foundational truth 2]; WHEREAS [problem being solved]; NOW THEREFORE, the following LAWS are hereby declared and SHALL govern [domain] in perpetuity. ``` ### Laws Section Laws follow the preamble. Each law stands alone as a complete requirement: ```markdown ## LAW I: [The Principle Name] **IT IS HEREBY DECREED** that [core requirement]. [Elaboration of requirements, conditions, and constraints.] ```[language] // Code example showing compliance ``` ```[language] // FORBIDDEN: Code example showing violation ``` ### Severity Classification After all laws, classify violation severity: ```markdown ## SEVERITY CLASSIFICATION | Severity | Laws | Consequence | |----------|------|-------------| | CRITICAL | [Laws X, Y] | [Impact description] | | MAJOR | [Laws A, B, C] | [Impact description] | | MINOR | [Laws D, E] | [Impact description] | ``` ### Compliance Checklist Provide a verification checklist: ```markdown ## COMPLIANCE CHECKLIST Before [artifact] is considered complete: - [ ] **LAW I**: [Verification statement] - [ ] **LAW II**: [Verification statement] - [ ] **LAW III**: [Verification statement] ``` ## Good Law Writing ### Characteristics 1. **Precise** - No ambiguity about what is required 2. **Complete** - All cases covered 3. **Testable** - Compliance can be objectively verified 4. **Self-contained** - Each law understandable without external context 5. **Imperative** - Commands, not suggestions ### Examples **GOOD:** ```markdown ## § VII [The Atom Suffix Convention] **IT IS HEREBY DECREED** that all atom properties SHALL bear the `$` suffix. This convention provides immediate visual identification of reactive state. ```typescript export interface SessionVM { readonly inputValue$: Atom.Atom; // $ readonly history$: Atom.Atom; // $ readonly setInputValue: (value: string) => void; // No $ - not an atom } ``` **THE `$` SUFFIX** is the mark of reactivity. Its absence on an atom constitutes deception. ``` **BAD:** ```markdown ## Naming Things You should probably use the $ suffix for atoms because it makes them easier to identify. If you don't use it, other developers might get confused and that would be bad. Consider using it when you remember to. ``` ## What to Avoid ### Hedging Language | Avoid | Use Instead | |-------|-------------| | should | SHALL | | might | - (remove uncertainty) | | probably | - (state definitively) | | consider | IS REQUIRED TO | | try to | SHALL | | it's better to | SHALL | | you might want to | IS REQUIRED TO | ### Consequence Descriptions in Laws Laws define requirements. Consequences belong in severity classifications, not in the law itself. **AVOID in law body:** ```markdown If you violate this, bad things will happen and the codebase will become unmaintainable. ``` **ACCEPTABLE in severity section:** ```markdown | CRITICAL | VIII, XII | Immediate remediation required. Untestable code. | ``` ### Opinion and Preference Laws do not express preference. They establish fact. **AVOID:** ```markdown I think it's better to use namespace imports because they're cleaner. ``` **USE:** ```markdown [Subject] SHALL be imported as a namespace. Named imports are PROHIBITED. ``` ### Conditional Requirements If something is conditional, make the condition explicit and the requirement absolute: **AVOID:** ```markdown You might need to add spans if you want observability. ``` **USE:** ```markdown All asynchronous actions SHALL be wrapped with `Effect.withSpan()`. No exceptions. ``` ## Adding Laws to Existing Standards When extending an existing covenant document: ### 1. Identify the Next Law Number Review existing laws and use the next sequential Roman numeral. ### 2. Follow Established Patterns Match the structure, language, and formatting of existing laws in the document. ### 3. Add to Severity Classification Determine the appropriate severity for the new law and add it to the classification table. ### 4. Update Compliance Checklist Add corresponding verification item(s) to the checklist. ### 5. Cross-Reference Related Laws If the new law relates to existing laws, add cross-references in both directions. ## Example: Complete Mini-Covenant ```markdown # THE IMPORT COVENANTS ## PREAMBLE WHEREAS consistent import patterns reduce cognitive load; WHEREAS namespace imports preserve type and value unity; WHEREAS scattered named imports cause name collisions; NOW THEREFORE, the following LAWS are hereby declared and SHALL govern all import statements. --- ## LAW I: The Namespace Requirement **IT IS HEREBY DECREED** that all Effect module imports SHALL use the namespace pattern. ```typescript // CORRECT import * as Effect from "effect/Effect" import * as O from "effect/Option" // FORBIDDEN import { Effect, pipe } from "effect" import { none, some } from "effect" ``` --- ## LAW II: The Local Module Pattern **IT IS HEREBY DECREED** that local domain modules SHALL be imported as namespaces. ```typescript nocheck // CORRECT import * as Task from "@/schemas/Task" const task = Task.makePending({ ... }) // FORBIDDEN import { makePending, isPending } from "@/schemas/Task" ``` --- ## SEVERITY CLASSIFICATION | Severity | Laws | Impact | |----------|------|--------| | MINOR | I, II | Inconsistency. Compounds over time. | --- ## COMPLIANCE CHECKLIST - [ ] **LAW I**: All Effect imports use namespace pattern - [ ] **LAW II**: All local domain imports use namespace pattern ``` ## When to Use This Skill - Establishing architectural constraints that must never be violated - Codifying patterns that have proven essential to maintainability - Creating domain-specific standards for new areas of the codebase - Formalizing existing informal rules into enforceable covenants - Extending existing covenant documents with new laws ## Key Principles Summary 1. Laws use SHALL/SHALL NOT - never suggestions 2. Definitions are precise - no ambiguity 3. Structure follows § section notation 4. Preambles explain why; laws state what 5. Consequences belong in severity tables, not law bodies 6. Every law is testable and verifiable 7. Code examples show both compliance and violation 8. Cross-reference related laws explicitly 9. Compliance checklists enable verification 10. Laws define - they do not persuade --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/kriegcloud) — claim your Tome and manage your conversions.