---
name: speckit-token-budget-compact
description: 'Compact one or more Spec-Driven Development artifacts in place to reduce
  token cost on subsequent /speckit.* commands. Lossless on requirements, decisions,
  contracts, IDs; strips template scaffolding, examples, and prose padding. The original
  is preserved as <artifact>.full.md the first time an artifact is compacted.

  '
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: Tinesoft
  source: extension:token-budget
user-invocable: true
disable-model-invocation: false
---

# 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.

### Step 5 — Hard preservation guardrails (every level)
**Never** modify, paraphrase, or remove:
- Any line containing a token that matches `compact.preserve_id_patterns`
  (FR-001, NFR-002, T015, US-003, AC-007, etc.) — keep the line verbatim.
- Any heading that prefix-matches `compact.preserve_sections`.
- Any fenced code block when `preserve_code_blocks` is true (default).
- The contents of `contracts/*` schema files (OpenAPI, JSON Schema, GraphQL
  SDL). You may strip surrounding markdown prose but the schema bytes must
  be identical.
- The Constitution check matrix in plan.md.
- The acceptance test expectations in tasks.md.
- File path references (anything that looks like a path: `src/...`,
  `./...`, `/...`).

If at any point you are uncertain whether a transformation is lossless, do
**not** apply it. Compaction must never invent, summarize away, or merge
distinct requirements.

### Step 6 — Re-anchor headings
After stripping, ensure heading levels are still contiguous (no jump from
`#` to `###`). Promote orphan subheadings as needed. The artifact must
still parse as a valid spec-kit document of its kind.

### Step 7 — Stamp
Append a single line at the very bottom of the compacted file:

```
<!-- token-budget: compacted (level=<level>) on <ISO-8601-date>; original at <basename>.full.md -->
```

This marker lets `usage` and re-runs detect already-compacted files and
skip no-op work.

## Output

For each artifact processed, run the helper script to get character/token
counts before and after, then report:

```
spec.md           4,820 → 2,310 tokens   (-52.1%)   [backup: spec.full.md]
plan.md           6,140 → 3,580 tokens   (-41.7%)   [backup: plan.full.md]
research.md       3,200 → 1,180 tokens   (-63.1%)   [backup: research.full.md]
─────────────────────────────────────────────────
total            14,160 → 7,070 tokens   (-50.1%)
```

Then end the response. Do not narrate the steps you took — the file diff
is the deliverable.

## Scripts

The helper script `.specify/extensions/token-budget/scripts/bash/compact_helper.sh` provides:
- `snapshot <file>` — prints the current token count.
- `backup_if_needed <file>` — copies to `.full.md` if no backup exists yet.
- `summarize <before_path> <after_path>` — prints the one-line report row.
- `has_marker <file>` — exit 0 if file is already compacted.
- `stamp <file> <level>` — append the compaction marker.

Use it to keep your edits auditable and the output consistent. You do the
content rewriting; the script does the bookkeeping.

## Re-running

If an artifact already carries the `<!-- token-budget: compacted -->`
marker, re-compaction works against the `.full.md` backup, **not** the
current compacted version. This prevents lossy compounding across runs.