67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
|
# 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
|