Speckit Token Budget Compact

Token Budget Compact Skill

/speckit.token-budget.compact

The user has invoked /speckit.token-budget.compact with arguments: $ARGUMENTS.

Your task

Compact one or more SDD artifacts in the active feature so that downstream spec-kit commands consume fewer tokens, without losing any requirement, decision, contract, ID, user story, or acceptance criterion.

Inputs

1. Resolve the active feature directory (typically specs/<NNN-feature-name>/) from the current git branch using the existing spec-kit conventions. If the user is not on a feature branch, ask which feature to operate on and stop.

2. Parse $ARGUMENTS:

   • empty → compact every artifact in the active feature directory.
   • spec | plan | tasks | research | data-model | contracts | quickstart | constitution → compact only that one (or that group, in the case of contracts).
   • a relative or absolute path → compact that file.
   • --level=light|medium|aggressive → override the configured level for this run only.
   • --dry-run → report what would change, write nothing.

3. Load token-budget-config.yml from the extension directory if present, otherwise use the template defaults. The keys you care about are: compact.level, compact.preserve_sections, compact.drop_sections, compact.preserve_code_blocks, compact.preserve_id_patterns, compact.keep_full_backup.

Algorithm — apply in order, per artifact

Step 1 — Backup

If keep_full_backup is true and <artifact>.full.md does not yet exist, copy the current artifact to <artifact>.full.md. Never overwrite an existing backup. The backup is the source of truth for re-compaction at a different level later.

Step 2 — Lossless strips (every level)

• Remove HTML comments left over from templates (<!-- ... -->), except the spec-kit machine-readable markers (e.g. <!-- INSERT_STATUS_BELOW -->) if present.
• Remove sections whose heading prefix-matches any entry in compact.drop_sections.
• Collapse runs of 3+ blank lines into a single blank line.
• Remove decorative ASCII separators (---, ===, repeated * or _ runs) that are not Markdown horizontal rules between meaningful sections.
• Strip repeated cross-reference reminders that the same artifact already states (e.g. "see spec.md FR-001" appearing in three sibling sections — keep the first occurrence per section, drop the rest).
• Strip phrase-level filler: "Note that", "It should be noted that", "As mentioned above", "For your reference", "Please be aware that", "It is important to understand that", and similar leading hedges. Keep the substantive clause that follows.

Step 3 — Medium level (default)

In addition to Step 2:

• Convert prose paragraphs that enumerate items into bullet lists when the prose contains "first ... second ... third", "as well as", or comma- separated noun clauses. Only when conversion is lossless — if in doubt, leave the prose alone.
• Collapse multi-sentence paragraphs that restate a single requirement into one sentence per requirement.
• For tables that have an "Example" or "Notes" column with prose larger than 20 words, condense to ≤ 12 words per cell.

Step 4 — Aggressive level

In addition to Steps 2–3:

• Drop sections titled "Rationale", "Alternatives Considered", "Background", "Motivation" — these are valuable for humans but the decision they justify is captured elsewhere in the artifact.
• Drop the leading framing paragraph of each top-level section if a structured list immediately follows that conveys the same information.
• Replace prose in "Research" findings with a one-line conclusion plus a bulleted evidence list.