view-budget

name

view-budget

description

Use this skill when the user wants to inspect (read-only) the active claude-code-complexity-guard budget — show which `.cogcomp.yml` is in effect, what preset is active, the per-metric `(enabled, threshold, block)` triples for CCS / HSI / DR, and the most-recent entries from the session violations ledger. Triggers on "show my budget", "what preset is active", "view violations history", "view-budget", "what is cogcomp blocking on", "what does my .cogcomp.yml resolve to". Does NOT modify any file — for editing the config use `configure-budget` instead.

View Budget

/claude-code-complexity-guard:view-budget [--all] resolves the active .cogcomp.yml for the current working directory, prints the effective preset + per-metric policy, and tails the session violations ledger written by the PostToolUse hook (Phase 4.1).

This skill is read-only. It never writes or modifies any file. To edit the config, use configure-budget. To audit a git rev-range, use audit-patch.

Usage

/claude-code-complexity-guard:view-budget
/claude-code-complexity-guard:view-budget --all

Default: print the most-recent 20 entries from the violations ledger. Pass --all to print every recorded entry instead.

What it does

• Walks upward from cwd to find the closest .cogcomp.yml (same resolution the PostToolUse hook uses).
• Prints the resolved config path, or (none — using V1 release default advisory) when no file is found.
• Prints the effective preset name and the (enabled, threshold, block) tuple for each of the three runtime metrics: CCS, HSI, DR.
• Tails <repo-root>/.claude/cogcomp-cache/session-<id>/violations.jsonl, one line per (timestamp, path, violation count).
• When the ledger does not yet exist (no PostToolUse fire has been recorded for this session), prints (no violations history yet) and exits 0.

Output format

Config: /path/to/repo/.cogcomp.yml
Preset: default
CCS: enabled=True threshold=30 block=True
HSI: enabled=True threshold=0.01 block=True
DR:  enabled=True threshold=0.0 block=True

Recent violations (last 20):
  2026-05-09T14:22:01.123456Z  src/lib/foo.py  violations=2
  2026-05-09T14:22:33.987654Z  src/lib/bar.py  violations=0
  ...

When no .cogcomp.yml is present:

Config: (none — V1 release default)
Preset: advisory
CCS: enabled=True threshold=30 block=False
HSI: enabled=True threshold=0.01 block=False
DR:  enabled=True threshold=0.0 block=False

(no violations history yet)

Workflow

1. From inside the repo whose budget you want to inspect, run /claude-code-complexity-guard:view-budget.
2. Read the printed Config: line to confirm which file is active. If it's (none — V1 release default) and you expected a file, your .cogcomp.yml is not where the upward walk found it — move it to the repo root or a closer ancestor.
3. Read the per-metric block. block=False means the metric will warn only; block=True means the PostToolUse hook will exit non-zero on threshold breach. To change either, use configure-budget.
4. Read the violations tail. Entries with violations=0 are clean PostToolUse fires; entries with violations>N indicate the hook surfaced N findings on that path. To see the full per-violation detail, inspect the ledger directly with cat <repo-root>/.claude/cogcomp-cache/session-*/violations.jsonl.

Implementation

The skill is pure orchestration over lib/budget.py and lib/cache_dir.py. Two Python one-liners do all the work.

Effective budget

from pathlib import Path
from lib.budget import load_budget, find_config_file

config_path = find_config_file(Path.cwd())
budget = load_budget(Path.cwd())
print(f"Config: {config_path or '(none — V1 release default)'}")
print(f"Preset: {budget.preset_name}")
print(f"CCS: enabled={budget.ccs.enabled} threshold={budget.ccs.per_function} block={budget.ccs.block}")
print(f"HSI: enabled={budget.hsi.enabled} threshold={budget.hsi.threshold} block={budget.hsi.block}")
print(f"DR:  enabled={budget.dr.enabled} threshold={budget.dr.threshold} block={budget.dr.block}")

Violations tail (default N=20; --all prints every entry)

import json
from pathlib import Path
from lib.cache_dir import session_cache_dir, _resolve_repo_root

repo_root = _resolve_repo_root(Path.cwd())
ledger = session_cache_dir(repo_root) / "violations.jsonl"
if ledger.exists():
    lines = ledger.read_text(encoding="utf-8").splitlines()
    tail = lines if "--all" in __import__("sys").argv else lines[-20:]
    label = "all" if "--all" in __import__("sys").argv else f"last {len(tail)}"
    print(f"\nRecent violations ({label}):")
    for line in tail:
        record = json.loads(line)
        print(f"  {record['timestamp']}  {record['path']}  violations={len(record['violations'])}")
else:
    print("\n(no violations history yet)")

Files inspected (read-only)

• <cwd>/.../path/to/.cogcomp.yml — resolved by upward walk via lib.budget.find_config_file (same logic the PostToolUse hook uses).
• <repo-root>/.claude/cogcomp-cache/session-<id>/violations.jsonl — written by the PostToolUse hook (Phase 4.1), one JSON-lines record per fire with shape {"timestamp": <iso8601-Z>, "path": <canonical>, "violations": [...]}.

Exit codes

Code	Meaning
0	Always — read-only inspection. Empty / missing ledger is not an error.

Related skills

• configure-budget — writes .cogcomp.yml (preset + overrides). Use it to change what view-budget reports.
• audit-patch — analyse a git rev-range against the same engine the PostToolUse hook uses; reads the same .cogcomp.yml.
• explain-metrics — what CCS / HSI / DR mean and how thresholds map to refactoring decisions.