2.3 KiB

Raw Blame History

Invariants Template

Use this template to document tool invariants - behaviors that must never change regardless of improvements or refactoring.

How to Use

Copy the YAML block below into your tool's documentation
Fill in each field based on actual behavior, not aspirations
Review invariants after any significant change
Add new invariants when discovered through use

Template

# Tool: [name]

invariants:
  - "[Behavior that must not change]"
  - "[Constraint that defines the tool]"
  - "[Add more as needed]"

value_proposition: "[What makes this tool valuable - speed? reliability? flexibility?]"

deliberate_omissions:
  - reason: "[Why this was excluded]"
    pattern: "[Pattern intentionally NOT included]"
  - reason: "[Another reason]"
    pattern: "[Another omitted pattern]"

Field Definitions

invariants: Behaviors that define the tool's identity. If these change, the tool becomes something else. Test these after every modification.

value_proposition: The core reason users choose this tool. Guides prioritization when constraints conflict.

deliberate_omissions: Patterns you consciously decided NOT to include. Documents "why not" to prevent future reversion through well-intentioned additions.

Example: Filled-in Template

# Tool: skill-architect

invariants:
  - "Always uses subagent for creation work"
  - "Never creates files without reading existing patterns first"
  - "Always runs description-architect for frontmatter"
  - "Produces skills that pass audit workflow"

value_proposition: "Consistent, high-quality skills through mandatory patterns and automated validation"

deliberate_omissions:
  - reason: "Skills should be standalone; coupling creates maintenance burden"
    pattern: "Multi-skill creation in single invocation"
  - reason: "Descriptions require specialized knowledge"
    pattern: "Inline description generation (use description-architect instead)"
  - reason: "Audits provide feedback loop for improvement"
    pattern: "Skipping audit step for 'simple' skills"

When to Update

After discovering behavior that breaks user expectations
When refusing a "helpful" change that would violate core identity
When finding undocumented constraints through debugging
During retrospectives on tool failures

2.3 KiB Raw Blame History