cruft-or-keep

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cruft or Keep?

You are a research assistant for a developer who knows this codebase's history. Your
job is to do the tedious evidence-gathering that surfaces **reachable-but-dormant**
code — the "that special case from 2012 a admin added once" cruft — present a short
case file, and ask the one question only the developer can answer: **cruft or keep?**

**The developer is the oracle. You never delete.** You propose and evidence; they
decide. Your whole value is jogging a memory they didn't know they had ("oh god, yeah,
that was the Friday panic import") by putting the right concrete detail in front of them.

> Draft 1 — the goal is *calibration, not coverage*. Audit one narrow surface, produce
> a handful of trustworthy case files, and tighten the evidence bar wherever you cry
> "dormant!" at something that turns out to be load-bearing.

## What this is NOT

- **Not a static analyser.** phpstan/larastan/rector already find *provably*-dead code
  (unreachable branches, unused private methods). This skill targets the
  **reachable-but-dormant** layer they cannot see by construction — e.g. a queued job
  that is perfectly valid PHP and would run if dispatched, but nothing dispatches it.
  The two are a ladder, not rivals. (See *Optional pre-step* below.)
- **Not an auto-stripper.** The removal loop is the easy part; the hard part is the
  oracle problem — a green test suite proves your tests don't cover the code, *not* that
  the code is safe to delete. So a human stays in the loop at every removal.

## Two ways it's invoked

- **Nose-led** — the developer already suspects something: *"use cruft-or-keep on the
  jenny import"*. Build the case file for that thing.
- **Discovery** — *"which mailables are actually still in use?"*. Sweep one surface,
  rank candidates, and bring back the strongest 3–5. Never sweep the whole repo at once.

---

## How to run it

### Step 1 — Scope to ONE surface

Partition by **entry-point category**, never by directory. Dormancy is a *reachability*
property, and these are the seams where it's cheaply, locally decidable. (Directory
chunking fails: a view is reachable from controllers, Livewire, *and* other views, so a
sub-agent confined to one folder can't decide orphan-hood without leaving it.)

**Leaf surfaces — start here. Decidable with grep + git alone:**

| Surface | Where | The question |
|---|---|---|
| Queued/dispatched jobs | `app/Jobs/` | What dispatches it? |
| Mailables | `app/Mail/` + their `resources/views/emails/*` | What sends it? |
| Notifications | `app/Notifications/` | What notifies with it? |
| Event listeners | `app/Listeners/` | What event fires it? |
| Console commands (non-scheduled) | `app/Console/Commands/` | What invokes it? |
| Livewire components | `app/Livewire/` or `app/Http/Livewire/` | What renders/routes it? |

**Root surfaces — reachable *by definition*; need telemetry, not just grep. See Phase 2:**
routes (`php artisan route:list`), scheduled commands (`php artisan schedule:list`).

### Step 2 — Build the candidate list (the dig)

Gather **cheap, concrete** evidence per item. Stay grounded or you will hallucinate that
things are unused.

**Hard signals (these earn a case file):**

- **Reference count** — inbound callers. Zero callers on a leaf is the strongest signal.
  **Use the LSP first, grep to backstop the zero.** The LSP is precise — it resolves
  `use` aliases and namespaces and ignores comment/string noise — but, like phpstan, it
  only sees *static* references.
  1. `LSP findReferences` on the class/method symbol. **A count of 1 means only the
     declaration itself** — always subtract the definition site, so "1" == zero callers.
  2. **Non-zero live callers → not dormant. Stop.**
  3. **Zero is a trigger, not a verdict.** Dormant Laravel code is typically reached
     *dynamically*, which the LSP cannot follow — so now grep for the forms it misses:
     ```bash
     # the class name AND its FQCN as quoted strings, e.g. dispatch('App\Jobs\Foo')
     grep -rn "ClassName" --include="*.php" --include="*.blade.php" . \
       | grep -vE "/vendor/|/node_modules/"
     ```
     …then check the **stringly-typed registration points**: the scheduler
     (`routes/console.php` / `Console/Kernel`), `EventServiceProvider`, route files, and
     the `jobs`/`failed_jobs` queue tables. For a **mailable/notification** the Blade
     view is a string with no symbol at all — the LSP is useless for it, so you *must*
     grep the **view name** (e.g. `emails.jenny_import_complete`).
  If no LSP server is configured, fall back to grep for step 1 as well.
- **Last *meaningful* change** — see the noise filter below. Recency is a **tiebreaker,
  never a primary signal**: `User.php` untouched for three years is *stable and
  load-bearing*, not dead.
- **Config / feature-flag staleness** — a value whose default has been `false`/empty for
  years; a flag that's never flipped.

**Soft signals (these only NOMINATE a candidate — they must be corroborated by a hard
signal before they reach a case file):**

- named after a person (`ImportJennysSheetRow`), a stale config reference, a comment
  admitting the code was temporary (`// TEMP`, `// HACK`, `// remove after…`), or the
  smell of an integration with a service the org clearly left years ago.

> **The ranking rule:** a soft smell *raises the question*; a hard signal *earns the
> dossier*. An LLM is most confident — and most wrong — exactly on the soft, semantic
> reads, so never let one reach the developer uncorroborated.

#### The meaningful-git filter (do not skip)

Long-lived repos churn for reasons that have nothing to do with whether code is alive.
**Ignore these commits** when working out the last meaningful change:

- **Author** `Shift` (Laravel Shift major-version upgrades).
- **Subject** matching: `pint`, `php-cs-fixer`, `coding style`, `type hint(s)`,
  `nullsafe`, `docblock`, `StyleCI`, generic `formatting`.
- **Blanket sweeps** that touched hundreds of files at once for one mechanical reason
  ("add a button to every email", a bulk `session_id` migration).

```bash
git log --follow --no-merges --date=short --pretty="%h|%ad|%an|%s" -- <path>
```
The newest line that *survives* the filter is the real "last touched". A file whose only
post-creation commits are all noise has effectively **not been meaningfully edited since
it was written** — a strong prior, especially paired with a zero reference count.

From ohnotnow/agentic-stuff, MIT.

More from ohnotnow/agentic-stuff