Skip to content

[DEBT] Trim trigger keyword dumps and fix over-limit descriptions (Lever A+C) #135

Description

@AdrienneBosch

Context

Only skill/command/agent description: frontmatter is preloaded into the
system prompt — it is paid on every turn of every session, whether or
not the item is ever used. Measured always-on cost today: ~3,840 tok
(github-workflow) + ~2,820 tok (local-workflow) = ~6,660 tok/turn when
both are installed.

The dominant driver is exhaustive Trigger: "...", "...", ... synonym
lists (e.g. setup ~16 phrases, pick-story ~11, report-issue ~11).
Claude already does semantic matching on the prose, so the synonym dumps
are largely redundant tokens. Two skill descriptions also exceed
Anthropic's hard 1,024-char limit and risk truncation:
code-review (~1,157) and execute (~934).

See docs/context-optimization-plan.md → Lever A and Lever C.

Requirements (acceptance criteria)

  • In every skill and command description, keep 3–4
    distinct-intent triggers
    and drop pure synonyms ("ship it"/"done"/"wrap
    up"/"submit" → keep one). Keep the "what it does + when to use" prose and
    the "Do NOT use for X (use Y)" disambiguation intact (trim, don't delete).
  • code-review and execute descriptions are brought under 1,024
    chars
    with margin (target ≤ ~900).
  • Edits are made to the canonical _shared-skills/ source where a skill
    is shared; ./sync-skills.ps1/.sh is run; canonical + synced copies are
    committed together (repo rule 1+2).
  • Affected plugin versions bumped (repo rule 3).
  • Quality gate passes: bash sync-skills.sh --verify && bash lint-skills.sh && bash run-tests.sh. The offline decision-logic
    (trigger/selection) tests stay green.
  • Before/after description diff attached to the PR; confirm each skill
    still has at least one trigger for every distinct user intent it covered.

Savings goal

~2,500 tok/turn reclaimed on always-on metadata when both plugins are
installed (~1,300 with one). Plus correctness: zero descriptions over
1,024 chars. Re-measure with count-tokens.sh and record the new baseline.

Metadata

Metadata

Assignees

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions