between-runs-audit

Between-Runs Audit

Purpose

A short, read-only checkpoint you run between coding-agent sessions.

Its job is to stop the project from drifting. Every coding agent has a bias toward producing — more code, more docs, more "while I'm in here" abstractions. This skill flips the bias for one turn: audit only, no writing.

It produces a clean verdict at the end:

• What is required right now
• What can wait
• What is dead weight
• The single next action

If you can't name the single next action, the audit didn't work.

When to use

Load it when any of these are true:

• A coding-agent run just finished and the next step isn't obvious
• The project feels too big, too noisy, or has too many half-finished threads
• Files, folders, abstractions, or docs keep appearing without an immediate consumer
• You're about to start a new run and want to avoid scope creep
• Before committing a batch of changes
• Before asking the agent to "continue" or "keep going"

Don't load it when:

• You already know the exact next small fix
• You're mid-refactor on a focused change
• It's a one-file edit or a one-line tweak

Core rule

Audit only. No writing.

The agent in this run must not:

• Create, edit, or delete files
• Run build / test / install commands
• Push branches, open PRs, or commit
• "Quickly fix" something it spots
• Add abstractions, helpers, or scaffolding "while it's looking"

It reads, it thinks, it reports. That's it.

The audit prompt

Copy the block below verbatim. Replace {{PROJECT_ROOT}} with the absolute path of the project you're auditing. Everything else stays.

STOP. Read-only audit. Do not modify any files.

Project root: {{PROJECT_ROOT}}

You are auditing, not building. Your only job is to classify the
current state of the project so the next run is small and clear.

Read in this order:
1. AGENTS.md, README.md, ROADMAP.md (whichever exist)
2. The top-level folder structure
3. Recent git log (`git log --oneline -30`)
4. Git status (`git status` — staged, unstaged, untracked)
5. Any TODO / FIXME / XXX comments in source
6. Any folder or file added in the last N commits that looks unused

Then classify every active item — features, files, docs, abstractions,
folders, configs — into one of three buckets using strict YAGNI:

  KEEP   — required for the next milestone. Removing it breaks progress.
  DELAY  — has value, but not before the next milestone ships.
          Move to /futurefeatures/ with a one-line reason.
  REMOVE — adds complexity without value. Delete it. No archive.

Apply these tests before classifying:

- No future-proofing. No "we'll need this later."
- No premature abstractions. If only one caller exists, inline it.
- No placeholder systems. Skeletons that don't run are lies.
- No docs without a reader. If nobody is going to read it this
  milestone, it doesn't exist yet.
- No features without an immediate user.
- No config without an immediate consumer.

Output exactly this structure, nothing else:

## KEEP NOW
- <item> — <why it's required for the next milestone>

## DELAY → /futurefeatures/
- <item> — <one-line reason for delay>
- ...

## REMOVE
- <item> — <one-line reason>
- ...

## NEXT SINGLE ACTION
One sentence. The highest-leverage thing to do next. Small enough to
finish in one focused run.

## PRIORITY ORDER
1. <action>
2. <action>
3. <action>
4. <action>
5. <action>

End of output. Do not write code. Do not modify files. Do not run
commands that change state. Audit only.