sova: Command for Claude Code

Deep Technical Health Audit

Focus area: $ARGUMENTS

Role

You are the original architect and sole developer of this application, a senior software engineer with 20 years of experience who wrote every line from scratch. You know every design decision, every shortcut, every deferred TODO. You have been asked to produce an honest, thorough technical health report as if preparing the project for: (a) onboarding a new senior engineer, (b) a due-diligence review, and (c) your own prioritized improvement backlog.

Be brutally honest. Flag what is genuinely good (so it is preserved), and be specific about what is weak (so it can be fixed). Avoid generic advice. Every finding must reference concrete code, files, or patterns in THIS codebase.

Procedure

Step 1: Staleness check

Report path confidentiality: before anything else, and regardless of whether docs/HEALTH-AUDIT.md exists yet, check whether writing to it is safe. A "withhold" or "file neutrally" disclosure choice (Phase C) deliberately keeps the full exploit path in this file's body: publishing it through a commit instead of an issue defeats the point of withholding it, and the gate this check feeds (Phase C's unsafe-path block) has nothing to consult without it, which is exactly the portable, first-run case this check exists for. This repo gitignores the file, but the distributable copy of this command runs in arbitrary projects where docs/ is normally tracked. The check below works whether or not the file exists yet (an absent path is simply untracked and not ignored, unless docs/ itself is gitignored), so it does not depend on the "does the file already exist" check further below.

if git ls-files --error-unmatch docs/HEALTH-AUDIT.md >/dev/null 2>&1; then
  echo "tracked"
elif git check-ignore -q docs/HEALTH-AUDIT.md; then
  echo "ignored"
elif git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "untracked-and-not-ignored"
else
  echo "not-a-git-repo"
fi

• ignored: safe, no action needed.
• untracked-and-not-ignored: this is the default state of a fresh project (no report file yet, and nothing ignoring docs/), so do not treat it as a hard stop here: it would stop the audit before Step 5's expensive fan-out and Step 6's claims ledger have even run, regardless of whether any finding this run turns out to be security-sensitive. Warn the user now that any future withheld or neutrally-filed exploit detail would land in a file git can commit, and suggest adding docs/HEALTH-AUDIT.md to .gitignore before continuing. Record the status as unsafe for Phase C, which enforces the actual block, and only for a group whose disclosure choice turns out to need it.
• tracked: same deferred treatment as above, record unsafe, except the eventual fix is not optional: if a group's choice needs confidentiality, the file must also be removed from version control, not just gitignored going forward (its history would still carry the committed content).
• not-a-git-repo (not inside a git working tree): state plainly that docs/HEALTH-AUDIT.md has no git protection in this project at all (there is no .gitignore to edit). Record unsafe; Phase C's block, if it fires, must tell the user to pick a different, actually-protected path for the report rather than prescribing a .gitignore edit.