write-standard

# Write Standard Skill Create a new standard document that defines clear rules for a specific aspect of your project. ## Context You're documenting a pattern, convention, or requirement that your team should follow. The standard becomes the source of truth — it's wired into agent context and used to verify compliance in ceremonies and enforcement. ## Domain Context Standards in claude-standards follow the format established in `levels/L1-context/library/`. Each standard: - Starts with frontmatter (category, standard name, version, customize flag) - Has an Overview section explaining the "why" - Contains Rules — numbered, actionable, specific - Includes Examples — right and wrong patterns - Defines Exceptions — when the standard doesn't apply - Contains [CUSTOMIZE] markers for project-specific values Reference: `levels/L1-context/README.md` ## Instructions 1. **Identify scope** — What rule are you documenting? (e.g., "error handling", "API design", "test coverage") - Which files does it affect? - Why does this standard matter to the team? - Deliverable: A clear 1-sentence summary 2. **Check if standard already exists** — Search `docs/standards/` for related files - Run: `grep -r "keyword" docs/standards/*/README.md` - If found, consider updating the existing standard instead of creating a new one - If not found, proceed to step 3 3. **Draft the standard** — Follow the template: ```markdown --- category: [engineering|design|quality|operations|architecture] standard: [kebab-case-name] version: 1.0 customize: [true|false] --- # Standard Title ## Principles [Why this matters — 2-3 paragraphs] ## Rules 1. **Rule Name** — What must be true - Details and context - [CUSTOMIZE]: Project-specific value needed here 2. **Rule Name** — What must be true ## Examples ### Right ✓ [Code/pattern that follows the standard] ### Wrong ✗ [Code/pattern that violates the standard] ## Exceptions When this standard does NOT apply: - [Scenario where exception is valid] ## Compliance Checklist - [ ] [Verifiable check 1] - [ ] [Verifiable check 2] ``` - Deliverable: Complete draft in `docs/standards/[category]/[standard-name].md` 4. **Add to category README index** — Update `docs/standards/[category]/README.md` - Add reference: `- [Standard Title](./standard-name.md) — One-line description` - Verify the index is alphabetized - Deliverable: Updated README with new entry 5. **Wire into agent context** — Update context files to reference the standard - In `CLAUDE.md`: Add reference if widely applicable - In `AGENTS.md`: Link if agents should know about it - In `.cursor/rules/` or equivalent: Create rule file if applicable - Rule: Always reference, never duplicate the standard content - Deliverable: Updated context files with relative paths to standard 6. **Verify with check-doc-index.sh** — Run verification ```bash ./levels/L2-ceremonies/scripts/check-doc-index.sh ./levels/L2-ceremonies/scripts/check-standards-refs.sh ``` - Fix any orphaned docs or broken references - Deliverable: All verification scripts pass ## Anti-Patterns 1. **Duplicating content into CLAUDE.md** — Wrong approach - Standard lives in `docs/standards/`, agent files reference it - Agent files must never duplicate the standard text - Guard: If you find yourself copy-pasting from a standard into CLAUDE.md, stop and instead add a reference 2. **Vague rules that can't be verified** — Unclear standards - Rule: "Code should be clean" is not verifiable - Right: "No function longer than 50 lines; all functions have JSDoc" - Guard: For each rule, ask "How would a machine check this?" 3. **Missing [CUSTOMIZE] markers** — Makes standard unusable by other projects - Every project-specific value needs a marker - Examples: tool names, file paths, specific version numbers - Guard: Search the draft for proper nouns or version numbers — mark them 4. **Standards hoarding** — Writing standards for everything - Don't document every single detail as a standard - Standards are for patterns that appear 3+ times and have enforcement value - Guard: Before writing a standard, ask: "Would this affect ceremonies or enforcement?" ## Further Reading - `levels/L1-context/README.md` — How the library is organized - `levels/L1-context/library/quality/governance.md` — Example standard - `AGENTS.md` — How to wire standards into agent context - `levels/L2-ceremonies/ceremonies/pr-gate.md` — How standards are verified