prompt-review

Prompt Review

Prompts are the product here, and they get worse by growing — a model reading a long file skips instructions in the middle of it. This reviews prompt files against five checks and, by default, fixes what fails.

The goal is a file a model follows end to end and acts on correctly. The checks are proxies for that. When two collide, the one that changes how the file is executed wins — an exact command earns its words. Raise nothing that would not change what a model does.

Wording only. A fix that drops a step, loosens a gate, renames a flag, or changes what a prompt returns is a behavior change: report it and leave the file alone. Invoking the skill is the permission to edit; a second run over a clean file changes nothing.

/prompt-review [--all] [--report-only]

  1. Scope   prompt files changed vs origin/main   (--all = every prompt file)
  2. Review  five checks per file
  3. Fix     what wording can fix                  (--report-only skips this)
  4. Report  one table, one verdict

Phase 1 — Scope

Prompt files are skills/*/SKILL.md, agents/*.md, rules/*.md, and templates/CLAUDE.md.template. Nothing else. Run from the repo root.

cd "$(git rev-parse --show-toplevel)"; SCRATCH=<the session scratch directory>
git rev-parse --verify origin/main >/dev/null || { echo "abort: origin/main missing"; exit 1; }
git diff --name-only --diff-filter=d origin/main...HEAD | grep -E \
  '^(skills/[^/]+/SKILL\.md|agents/[^/]+\.md|rules/[^/]+\.md|templates/CLAUDE\.md\.template)$' \
  > "$SCRATCH/scope.txt" || true            # --all: ls the four patterns instead
xargs -r wc -lw < "$SCRATCH/scope.txt"      # before-counts; over 500 lines is its own finding

--diff-filter=d drops deleted paths; || true keeps an empty match from aborting a strict shell. Empty scope → print the verdict with zeros and stop. Past about five files, fan out one read-only subagent per file, each returning its rows — never pull every file into one context.