cfec11bb46
Some checks failed
ci/woodpecker/push/woodpecker Pipeline failed
stop-slop, taste-skill, terrashark had embedded .git dirs causing Woodpecker clone to fail on submodule update.
80 lines
3.1 KiB
Markdown
80 lines
3.1 KiB
Markdown
# Terraform Skill Token Efficiency Strategy
|
|
|
|
This page explains the token efficiency strategy that makes TerraShark the leanest Terraform skill available, and the empirical process used to validate every line of content.
|
|
|
|
## The Problem with Large Skills
|
|
|
|
Most Terraform skills dump huge walls of text into the AI's context window on every activation. This creates three problems:
|
|
|
|
1. **Wasted tokens** — context window space spent on skill content is unavailable for the user's codebase and conversation
|
|
2. **Signal dilution** — when everything is included, the model has difficulty finding what matters
|
|
3. **Redundancy** — LLMs already know basic Terraform syntax; restating it burns tokens with no quality improvement
|
|
|
|
## TerraShark's Approach
|
|
|
|
### Lean Activation (~600 tokens)
|
|
|
|
The core `SKILL.md` is 86 lines containing:
|
|
- No HCL examples
|
|
- No inline code blocks
|
|
- No tutorial material
|
|
- Pure procedure: a workflow the model follows
|
|
|
|
### Granular References (19 files)
|
|
|
|
Instead of 6 large files (as in alternatives), TerraShark uses 19 focused files. The model loads only the 1-2 files relevant to the diagnosed failure mode.
|
|
|
|
### Content Inclusion Rules
|
|
|
|
Content enters TerraShark only when at least one condition is met:
|
|
|
|
1. It materially lowers the probability of destructive or non-compliant changes
|
|
2. It prevents common plan/apply surprises
|
|
3. It encodes organizational guardrails that general model knowledge cannot infer
|
|
|
|
Content is excluded when:
|
|
|
|
1. It is generic Terraform/OpenTofu knowledge with low failure impact
|
|
2. It is provider-specific deep design that belongs in project docs
|
|
3. It duplicates an existing rule without adding a new decision signal
|
|
|
|
### Expansion Rule
|
|
|
|
If repeated failure patterns emerge, targeted lines are added for that specific failure mode instead of broad expansion.
|
|
|
|
## The Token Experiment
|
|
|
|
The content was empirically tested, not designed by intuition.
|
|
|
|
### Process
|
|
|
|
1. Started with significantly larger reference content
|
|
2. Built automated test suite of practical Terraform/OpenTofu tasks
|
|
3. Measured baseline quality (correctness, safety, completeness, hallucination rate)
|
|
4. Stripped sections one at a time, re-running the full test suite
|
|
5. If quality dropped: content was restored (load-bearing)
|
|
6. If quality stayed stable: content was permanently removed (redundant)
|
|
7. Continued until every remaining section was load-bearing
|
|
|
|
### What Survived
|
|
|
|
Content the model demonstrably needs help with:
|
|
|
|
- Module role boundaries and composition rules
|
|
- Migration playbooks (moved blocks, count-to-for_each, imports)
|
|
- Native test caveats (set indexing, computed values, mocked providers)
|
|
- CI delivery templates (policy checks, artifact integrity, env protection)
|
|
- Quick troubleshooting (stuck locks, backend migration, provider auth in CI)
|
|
|
|
### What Was Removed
|
|
|
|
Content the model already knows well:
|
|
|
|
- Generic HCL syntax tutorials
|
|
- Provider-specific resource deep dives
|
|
- Broad "best practice" prose without failure-mode framing
|
|
- Duplicate explanations
|
|
|
|
### Core Principle
|
|
|
|
**High signal density.** Every line must earn its token cost by preventing a specific failure mode or encoding knowledge the model demonstrably lacks.
|