Unstale

Governing principle: deterministic where you can, LLM where you must — adapt to the repo, never dictate its structure.

Live state

```! git status --short 2>/dev/null || echo "(not a git repo)"

## Mode overview

| Invocation | Target | Edits? |
|---|---|---|
| `/unstale` | Auto-detected .py library scope | Report only |
| `/unstale --auto` | Same | Apply HIGH fixes |
| `/unstale --artifact ` | Notebook as deliverable | Report only |
| `/unstale --artifact  --auto` | Same | Apply HIGH fixes |
| `/unstale --exploratory ` | Working notebook | Report only (always) |

`--artifact` and `--exploratory` are **notebook-only**. If a path ends in `.py`, warn and skip it.

---

## Default mode — scope auto-detection

| Signal | Scope |
|---|---|
| `pyproject.toml` / `setup.py` / `src/` / importable package dir | Library → run both lanes |
| Top-level `.py` with no package structure | Ambiguous → skip Lane A (dead-code) |
| Only `.ipynb` files | No .py scope → nudge to `--artifact` / `--exploratory` |

Check for a CLAUDE.md override line: `unstale library scope: ; treat  as exploratory`. Use it if present.

Always state the detected scope in the report. If notebooks exist but weren't scanned, emit:
> "N notebooks present — run `/unstale --artifact ` (clean as deliverable) or `--exploratory ` (tidy) to check them."

---

## Default mode — two lanes

### Lane A — Deterministic

Run on detected library scope. Tag findings `DETERMINISTIC-LINT` or `DETERMINISTIC-DEADCODE`.

```bash
ruff check --select F401        # unused imports
vulture  --min-confidence 80    # dead code

Lane B — LLM judgment

Do not re-detect dead code or unused imports — Lane A owns them. Scan for:

• Comments describing logic that has since changed
• Contradictory or outdated docstrings
• Resolved TODOs (is the work actually done?)
• Stale filepaths / README instructions (verify against repo tree)
• Outdated .ai/HANDOFF.md blockers

Tag findings LLM-JUDGED.

---

Tool availability

Before running Lane A, check which ruff && which vulture (add nbqa for --artifact).

• If absent: install into the project venv (uv pip install if uv present, else pip install); add to pyproject.toml dev deps if one exists.
• If a tool can't be installed: skip its lane, run the remaining lanes, and state what was skipped and why.

---

Whitelist

Maintain .vulture_whitelist.py at the repo root (committed — not in .ai/). Apply to all vulture invocations (default mode and --artifact). Report whitelist hits as "suppressed" — never silently dropped.

---

Confidence tiers and --auto gating

| Source | Confidence | Tier | --auto eligible | |---|---|---|---| | ruff F401 | — | HIGH | yes | | vulture 100% | unreachable / unused | HIGH | yes | | vulture 80–99% | probable dead code | MED | flag only | | LLM-judged | all | flag only | never |

Chesterton's Fence: --auto never touches anything below 100% vulture confidence under any flag. Code that might be dead is code you don't fully understand yet. The 80% floor widens what the report shows; never what --auto applies.

---

--artifact mode (notebook as deliverable)

--artifact asserts the notebook is a deliverable, not exploratory scratch. That assertion licenses dead-code detection (the opposite of default mode).

Deterministic structural (parse .ipynb JSON):

• Execution-order integrity: flag non-monotonic / missing execution_count
• Hardcoded path literals: regex code cells for /home/, /mnt/, s3://, etc.

Tag: DETERMINISTIC-STRUCTURAL.

Deterministic dead-code + lint:

• ruff check --select F401 → HIGH
• nbqa vulture --min-confidence 80 (or jupytext → .py → vulture if nbqa unavailable)

LLM semantic:

• Markdown↔code drift: a markdown cell describes behavior the code lacks
• Stale outputs: stored output inconsistent with current code (judge from code + stored output; do NOT re-execute)

Under --auto: apply HIGH findings (ruff F401 + vulture 100%). Structural and semantic findings remain flag-only.

---

--exploratory mode (working notebook)

Same as --artifact minus the destructive parts:

• Run: structural checks + LLM semantic
• Skip entirely: dead-code lane (vulture / nbqa) — exploratory "unused" code is expected, not stale
• Unused imports (ruff F401): flag only — never removed (may be staged for a not-yet-written cell)
• --auto performs NO removals — all findings flag-only, always

---

Report format (always emitted before any edit)

State mode and detected scope at the top. Then one row per finding:

| Item | Location | Category | Tier | Source | Action | |---|---|---|---|---|---| | import foo unused | utils.py:3 | dead import | HIGH | ruff F401 | remove | | MyClass._cache | store.py:88 | dead attr (92%) | MED | vulture 92% | flag only | | # uses requests not httpx | api.py:14 | stale comment | — | LLM-JUDGED | flag only |

Apply log (--auto only)

Append to .ai/unstale-.md:

Applied fixes:
- utils.py:3 — removed unused import `foo`

---

Anti-Rationalization

| Excuse | Reality | |---|---| | "This comment looks fine" | Does it still match the code path it describes, or just the code that used to be there? | | "This TODO looks resolved" | Is the work actually merged into this file, or just started somewhere? | | "vulture flagged this but it's probably used" | That's what .vulture_whitelist.py is for — whitelist it, don't suppress the finding |

Does not

• Flag style, quality, or verbosity — that is /overbaked's domain.
• Re-detect dead code or unused imports in the LLM pass (Lane A owns them).
• Touch .ipynb files in default mode.
• Remove anything in --exploratory mode, even with --auto.
• Mandate any repo directory layout.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dgilford
• Source: dgilford/ai-science-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.