/forge-stats

user-invocable: false
description: Track command sizes, detect bloat, compare against baselines and thresholds
argument-hint: "[diff | baseline | full | cost]"
install: internal

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/forge-stats — Prompt Bloat Tracker

**Input**: $ARGUMENTS (default: `diff`; modes: `diff`, `baseline`, `full`, `cost`)

Tracks the size of every Forge command file over time. Detects bloat by comparing current sizes against the git-tracked baseline and per-command thresholds.

Config

Read project home from `forge.yaml` before running any mode:

CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
FORGE_HOME=$(yq e '.paths.root' "$CONFIG_FILE")
echo "Forge home: $FORGE_HOME"

**FORGE_HOME**: `$FORGE_HOME` (set from `forge.yaml` → `paths.root`)

---

Thresholds

Commands are classified by role. Each role has a max line count — beyond this, the prompt is too large for Sonnet to reliably follow all instructions.

| Role | Max Lines | Rationale | |------|-----------|-----------| | Orchestrator (work-on, orchestrate, review-pr) | 800 | Delegates to sub-agents; needs full pipeline logic | | Agent catalog (review-pr-agents, review-pr-staging) | 1000 | Reference file read on demand, not fed whole to one agent | | Specialist (milestone, analytics, sync-ecosystem, validate, etc.) | 400 | Single-purpose or multi-subcommand; Sonnet attention degrades past this | | Utility (cleanup, forge-stats) | 250 | Simple tasks; should stay lean | | Sub-file (quality-gate, pipeline-health) | 350 | Invoked by parent; shares context budget |

**Current overages (v1.1.0 baseline):**

• `work-on.md`: 289 lines (threshold 800) — OK (compressed from 1,565)
• `review-pr-staging.md`: 218 lines (threshold 1,000) — OK (compressed from 1,201)
• `qa-sweep.md`: 196 lines (threshold 400) — OK (compressed from 1,058)
• `review-pr-agents.md`: 815 lines (threshold 1,000) — OK
• `review-pr.md`: 796 lines (threshold 800) — OK
• `validate.md`: 97 lines (threshold 400) — OK (compressed from 679)
• `orchestrate.md`: 654 lines (threshold 800) — OK
• `analytics.md`: 856 lines (threshold 400) — **114% over**
• `sync-ecosystem.md`: 799 lines (threshold 400) — **99% over**

---

CI Spec-Size Budget

`scripts/check-spec-size.sh` (job `spec-size-budget` in `check-commands.yml`, PRs only) enforces a budget that is independent of the line-count `.baselines`; the baseline is refreshed on release via `/forge-stats baseline`. It compares bytes against the PR base:

• Every `commands/**/*.md` spec may not grow by more than 2% or 4 KB; a new spec may be at most 4 KB. Shrinking always passes.
• Per-file hard ceilings (`CEILINGS` in the script) cap a spec whatever its growth: `commands/issue.md` 15 KB (its procedure lives in `scripts/issue-create.sh`, #4164).
• No `commands/**` file may gain a copy of a canonical block (FORGE_ROOT bootstrap, TRUSTED_SCRIPT/HELPER_SCRIPT resolver, FENCE_BOOTSTRAP anchor); the per-file marker count may not rise. The shared helpers (`scripts/lib/forge-resolve.sh`, `scripts/lib/fence-bootstrap.sh`) are sourced through marker-free stubs, so a conversion reads as a net reduction.
• Exemption: the `spec-size-exempt` PR label only (needs triage rights; a PR-body marker is not honoured). The job summary lists the per-file delta and any waiver.

---

Mode: `diff` (default)

Compare current line counts against the last git commit. Shows what grew and what shrank.

cd "$FORGE_HOME"

echo "=== Forge Command Sizes — $(date +%Y-%m-%d) ==="
echo ""
printf "%-35s %6s %6s %6s %s\n" "Command" "Now" "Prev" "Delta" "Status"
printf "%-35s %6s %6s %6s %s\n" "-------" "---" "----" "-----" "------"

for cmd in commands/*.md; do
    name=$(basename "$cmd")
    current=$(wc -l < "$cmd")

    # Get line count from last commit
    previous=$(git show HEAD:"$cmd" 2>/dev/null | wc -l || echo 0)

    delta=$((current - previous))

    # Determine threshold based on filename
    case "$name" in
        work-on.md|orchestrate.md|review-pr.md) threshold=800 ;;
        review-pr-agents.md|review-pr-staging.md) threshold=1000 ;;
        cleanup.md|forge-stats.md) threshold=250 ;;
        quality-gate.md|pipeline-health.md) threshold=350 ;;
        *) threshold=400 ;;
    esac

    # Status
    if [ "$current" -gt "$threshold" ]; then
        overage=$(( (current - threshold) * 100 / threshold ))
        status="⚠ ${overage}% over (max ${threshold})"
    else
        headroom=$(( (threshold - current) * 100 / threshold ))
        status="OK (${headroom}% headroom)"
    fi

    # Delta formatting
    if [ "$delta" -gt 0 ]; then
        delta_str="+${delta}"
    elif [ "$delta" -eq 0 ]; then
        delta_str="="
    else
        delta_str="${delta}"
    fi

    printf "%-35s %6d %6d %6s %s\n" "$name" "$current" "$previous" "$delta_str" "$status"
done

echo ""
echo "Total: $(wc -l commands/*.md | tail -1 | awk '{print $(1)}') lines across $(ls commands/*.md | wc -l) commands"

**After running, flag any command where:** 1. Delta > +50 lines in a single commit → "Significant growth — review if this is necessary" 2. Current > threshold → "Over limit — consider splitting into sub-files or rewriting" 3. Total across all commands > 10,000 lines → "Pipeline total is growing — review for consolidation"

---

Mode: `baseline`

Record the current sizes as the new baseline. Run this after a deliberate refactor or rewrite.

cd "$FORGE_HOME"

echo "# Forge Command Baselines — $(date +%Y-%m-%d)" > .baselines
echo "# Auto-generated by /forge-stats baseline" >> .baselines
echo "" >> .baselines

for cmd in commands/*.md; do
    name=$(basename "$cmd")
    lines=$(wc -l < "$cmd")
    echo "${name}:${lines}" >> .baselines
done

git add .baselines
git commit -s -m "stats: update command baselines — $(date +%Y-%m-%d)"

---

Mode: `full`

Full analysis with git history trend. Shows how each command has grown over time.

cd "