# Invariants Template

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

## How to Use

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

## Template

```yaml
# 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

```yaml
# 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
