vince-cleanup

Files (1)

• SKILL.md

SKILL.md (first lines)

---
name: vince-cleanup
description: Safely clean leaked worktrees, attributable processes, background jobs, and regenerable output after a task. Use for cleanup, locked directories, failed worktree removal, stray processes, or unexplained workspace disk use.
---

# Vince — Cleanup

Before the final user-facing response, apply `reference/brief.md`.

A session that ends without teardown leaves three things behind: **git worktrees** full of
throwaway state, **processes** still holding directories open, and **output** nobody needed. The
worktrees waste disk, the processes waste RAM and make the directories undeletable, and the
output hides real diffs.

`vince-implement` tells a session to sweep up after itself. This skill is for when that did not
happen — the session crashed, was interrupted, or predates the rule.


## Communication and efficiency

Be literal and calm before destructive actions. Load `reference/voice.md` only if a report needs
tone guidance. Load `reference/token-discipline.md` only when inventory output or context becomes
large; otherwise keep commands bounded and never spawn a helper for mechanical discovery.

## Stance: this is the most destructive skill here

Everything else in this toolkit reads, writes documents, or runs tests. This one kills processes
and deletes directories. So it is built to refuse:

- **Inventory before you touch anything.** Nothing is stopped or deleted until the whole picture
  is on screen and attributed.
- **Never act on what you cannot attribute.** A `node` process you did not start might be the
  user's dev server, their editor's language server, or another agent session mid-task. Stopping
  processes by *name* can terminate an unrelated editor or dev server.
- **Unsaved work is never yours to delete.** A dirty worktree or unpushed commits is a STOP and a
  report, not a `--force`.
- **Regenerable or nothing.** Delete build output, caches and scratch. Never delete source,
  logs someone may need, or anything you cannot name the regenerating command for.
- Being slightly too conservative costs disk. Being too aggressive costs somebody a day's work.
  Those are not symmetric, so lean hard one way.

## 1. Inventory

Do all four, and write the results down before acting.

**Worktrees.** For each repo in scope:

```bash
git -C <repo> worktree list
git -C <repo> worktree list --porcelain   # includes branch + bare/detached state
```

For each one that is not the main checkout, gather: path, branch, `git -C <wt> status --porcelain`
(dirty?), and `git -C <wt> log --branches --not --remotes --oneline` (unpushed commits?).

**Processes holding paths in scope.** The specific thing that makes directories undeletable, and
the step most likely to be done wrongly.

> **Do not start by grepping command lines for the directory.** The process that bites you is
> `python -m http.server` started a week ago inside `dist/`: its command line is
> `python -m http.server 4200`, its image is `python.exe`, and **neither contains the path**. The
> association lives in the working directory and open handles, which `Win32_Process` does not
> expose. A command-line filter returns nothing and you conclude the directory is held by
> nothing — the exact dead end this section exists to prevent.

Sweep on three axes instead. Any one of them finds the class; together they are hard to escape.

```powershell
# 1. LISTENING PORTS - a preview or dev server exists to serve, so it is bound to something
Get-NetTCPConnection -State Listen |
  Select-Object LocalPort, OwningProcess,
    @{n='Name';e={(Get-Process -Id $_.OwningProcess -EA SilentlyContinue).Name}},
    @{n='Started';e={(Get-Process -Id $_.OwningProcess -EA SilentlyContinue).StartTime}} |
  Sort-Object LocalPort

# 2. AGE + IMAGE - dev tooling that has been up for days is nobody's active work
Get-Process node,python,python3,dotnet,java,ruby,php,deno,bun -EA SilentlyContinue |
  Where-Object { $_.StartTime -lt (Get-Date).AddHours(-12) } |
  Select-Object Id, Name, StartTime,
    @{n='Cmd';e={(Get-CimInstance Win32_Process -Filter "ProcessId=$($_.Id)").CommandLine}}

# 3. OPEN HANDLES - definitive, needs Sysinternals handle.exe
handle.exe -nobanner -accepteula "<path>"
```

```bash
# macOS / Linux - same three axes
lsof -nP -iTCP -sTCP:LISTEN                 # ports
ps -eo pid,lstart,etime,comm,args --sort=start_time | head -30   # age
lsof +D "<path>" 2>/dev/null | head -40     # handles (also catches cwd)
fuser -v "<path>" 2>&1
```

Then, for each candidate, resolve what it is actually sitting on — the question the command line
cannot answer:

```powershell
handle.exe -nobanner -p <pid>            # every handle, including the directory it holds
```
```bash
lsof -p <pid> | grep -E 'cwd|DIR'        # cwd is the line that matters
readlink /proc/<pid>/cwd                 # Linux, exact
```

**Shapes that hide from a path grep.** Every one of these serves or watches a directory while
naming it nowhere:

| Command | Why it hides |
|---------|--------------|
| `python -m http.server <port>` | module run; serves **cwd**, which appears in no argument |
| project-local `serve`, `http-server`, or `live-server` binary | serves cwd or a short relative path |
| `php -S localhost:8000`, `ruby -run -e httpd .` | same shape |
| `node` from a dev server (Vite, Next, Angular) | image is `node`; the project path may only be in cwd |
| `dotnet watch`, test runners in `--watch` | long-lived, re-spawn children |
| `kubectl port-forward` | holds a port, not a directory, but leaks the same way |
| orphaned `tail`/`sed`/`grep` on Windows/Git-Bash | left by a backgrounded pipeline |

A week-old `python` bound to a dev port is not somebody's careful setup. It is a preview server
somebody started once to look at a build, and it will hold that directory until the machine
reboots.

From elroykanye/vince-gate, MIT.

More from elroykanye/vince-gate