write-standard

name	write-standard
description	Write a well-structured standard document with headers, rules, and examples

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:

   ---
   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

   ./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