Health Audit

Sanity-check the codebase for the drift that accumulates in an AI-maintained repo: docs falling out of sync with commands, skills referencing moved files, copy-paste helpers, guideline violations, test-convention drift. Each area is audited by an independent subagent grounded in its truth source (the code, or a specific guideline doc), so findings are concrete and low-noise.

Read-only against the codebase: the audit never edits source, posts, or opens issues. It only reports. Findings are meant to feed the normal pipelines (/gh-issue → /resolve-issue, or direct doc fixes).

Arguments

/health-audit [area]

• No argument → run all seven areas in parallel, then write a SUMMARY.md.
• One area → run only that area. Valid slugs (also the report filenames): docs, skills, duplication, dead-code, guidelines, correctness, tests.

Areas and truth sources

Slug	Audits	Truth source
docs	manpages vs actual flags/config/commands; root technical-doc drift	cmd/*.go, config keys, version/, ARCHITECTURE.md, CODE_REFERENCE.md
skills	stale refs, overlap, and AI-guidance consistency (.claude/skills/, .github/copilot-instructions.md, CLAUDE.md)	the skill files + root guideline docs
duplication	copy-paste logic, parallel implementations	source + CODING_GUIDELINES.md
dead-code	unused exports/files, unreachable or orphan code	source
guidelines	coding-guideline compliance, layering, config precedence	CODING_GUIDELINES.md, CLAUDE.md "Code Conventions"
correctness	real defects: unhandled errors, wrong exit codes, boundary/state bugs	source
tests	build/test pass, coverage gaps, convention drift	TESTING_GUIDELINES.md, CLAUDE.md testing sections

Instructions

1. Resolve scope and output dir

Get today's date and pick the areas to run:

date +%Y-%m-%d

• If an argument was given, validate it against the five slugs (reject anything else with the valid list) and run only that one.
• Otherwise run all seven.

The output directory is .ai/health-audit-<today>/. Create it. .ai/ is gitignored, so nothing here gets committed. If the dir already exists (a re-run same day), overwrite the area files being regenerated; leave others intact.

2. Run each area as a subagent

Launch one Task/subagent per selected area, in parallel (all in one message when running several). Each subagent gets the matching prompt below, prefixed with this shared preamble:

You are auditing the git-flow-next repo (Go CLI implementing the git-flow branching model) at the repository root. This is an AI-maintained repo; the risk you are hunting is drift, not catastrophic breakage. Respect the project's stated pragmatic, anti-over-engineering philosophy (CLAUDE.md): do NOT flag long functions, many-parameter signatures, or "missing" abstraction layers — those are explicitly acceptable. Only report REAL issues with concrete file:line evidence. When in doubt, lean toward NOT flagging and mark it low severity. Read the relevant guideline doc FIRST so you check against the project's actual rules, not generic opinions.

Write your findings to .ai/health-audit-<today>/<slug>.md (create nothing else). Format: a top # <Area> — <date> heading, then findings as a bullet list where each is **[high|med|low]** + one-line description + file:line references + the concrete mismatch. Group trivially-clean sub-checks into a single "Clean:" bullet. End with a one-sentence Verdict. Return to me only a 3–6 line digest: the count by severity and your highest-severity findings — not the full file.

Then the per-area body:

docs — Check manpages in docs/*.md against the code:

1. Every command in cmd/*.go: do its flags (long AND short) match docs/git-flow-<cmd>.1.md? Find flags in code missing from docs, and documented flags that no longer exist.
2. Config keys: every gitflow.* key read/written in internal/config and cmd/ — documented in docs/gitflow-config.5.md (or a per-command manpage)? Any documented key the code no longer uses?
3. Commands with no manpage at all, or manpages for removed commands, and broken git-flow-*(1) cross-references.
4. Recently-added commands (publish, rename, track, checkout) — verify doc coverage (CLAUDE.md makes doc updates MANDATORY for command changes).
5. version/version.go vs cmd/version.go — do the version constants match? Skip stylistic/wording nitpicks.
6. ROOT TECHNICAL DOCS — ARCHITECTURE.md and CODE_REFERENCE.md describe the codebase structure and drift silently as code moves. Cross-check them against cmd/ and internal/: commands or packages that exist but aren't mentioned, files/paths referenced that have moved or been removed, and structural claims (layering, package responsibilities) that no longer hold. Use git log recency as a hint — a doc far older than the code it describes is a drift candidate — but confirm each mismatch against the actual tree. Skip prose/wording nitpicks; report only factual staleness.

skills — Check .claude/skills/ (and any .claude/commands/):

1. STALE REFERENCES: grep each skill for referenced files, paths, skill names, and doc names; verify each target exists. Report dangling references.
2. OVERLAP: genuinely adjacent skills (e.g. the review family, gh-issue vs any global create-github-issue, scan-repo vs sync-repo-status) — is the boundary documented, or ambiguous? Don't flag skills that legitimately differ.
3. CONSISTENCY: any skill instructing something that contradicts GITHUB_GUIDELINES.md, COMMIT_GUIDELINES.md, ISSUE_GUIDELINES.md, or DEV_WORKFLOW.md.
4. Skills referenced in DEV_WORKFLOW.md/CLAUDE.md that don't exist, and skills that exist but are referenced nowhere (orphans / undocumented relative to peers).
5. AI-GUIDANCE CONSISTENCY: .github/copilot-instructions.md and CLAUDE.md are curated summaries of the same rules the guideline docs encode. Check they haven't drifted from the source of truth: commit format vs COMMIT_GUIDELINES.md (incl. the Co-Authored-By attribution rule), the three-layer config precedence and internal/git wrapper rule vs CODING_GUIDELINES.md/ARCHITECTURE.md, and mandatory test/doc/version-sync requirements. Flag contradictions and rules that changed in a guideline doc but not in these summaries. A high-level omission (a summary intentionally not listing every detail) is not a finding — only contradictions are.

duplication — Read CODING_GUIDELINES.md first, then audit cmd/ and internal/ for logic that has diverged or is about to:

1. TRUE DUPLICATION: near-identical logic blocks in 2+ places that could share a helper (flag parsing, config-precedence resolution, conflict/merge-state handling, validation, hook-context construction). Give every copy's file:line.
2. PARALLEL IMPLEMENTATIONS: two functions doing the same job under different names, or a newer path that superseded an older one but left it in place. Respect the anti-over-engineering philosophy: some repetition is fine. Call it out only when the copies have already diverged, or are likely to, causing real bugs. A near-duplicate that would only save a few lines is NOT a finding.

dead-code — Audit cmd/, internal/, and testutil/ for code nothing reaches:

1. Exported symbols with no non-test caller; unexported symbols with no caller at all; unused files.
2. Unreachable branches and orphan helpers (including dead or duplicated testutil helpers). Before flagging, confirm there is truly no caller across cmd/, internal/, and tests — registration/reflection patterns (e.g. Cobra command registration, init() side effects) can hide callers. When unsure whether a symbol is intentional public API, mark it low severity.

guidelines — Read CODING_GUIDELINES.md + CLAUDE.md "Code Conventions" first; check compliance with the project's stated MUST/ALWAYS/NEVER rules:

1. ERROR HANDLING: custom typed errors from internal/errors used; specific exit codes per condition; typed errors actually satisfy the errors.Error interface. Find bare fmt.Errorf/errors.New where a typed error is expected, and exit codes that diverge from the documented set.
2. GIT INTEGRATION & LAYERING: git through internal/git; find exec.Command("git", ...) calls that bypass the wrapper (note if in cmd/ vs read-only internal/ — the former is worse); graceful conflict handling; uncommitted-changes check before mutating operations.
3. COMMAND IMPLEMENTATION: consistent Cobra structure; the "validate git-flow is initialized" preamble on every command except init; long AND short flags; input validation; examples/usage present.
4. CONFIG PRECEDENCE: three-layer resolution (branch-type def → command config → CLI flags, flags always win) implemented consistently — does any command resolve differently?
5. Any other explicit rule in CODING_GUIDELINES.md, checked against code.

correctness — The one area that steps beyond drift into real defects. Stay disciplined: report a bug ONLY with a concrete failure scenario (specific inputs/state → wrong result or crash). Respect the pragmatic philosophy — do NOT flag style, long functions, or theoretical "could be cleaner" issues. Audit cmd/ and internal/:

1. UNHANDLED ERRORS: returned errors ignored or swallowed; err checked but the wrong branch taken; deferred Close/cleanup errors dropped where the result matters.
2. EXIT CODES / ERROR TYPES: a condition that returns the wrong exit code, or a failure path that returns success (nil error) and lets execution continue.
3. STATE & BOUNDARY: merge-state read/written inconsistently across continue/abort; off-by-one, empty-slice, or nil-map access; branch-name / prefix edge cases; ordering assumptions that don't hold.
4. GIT-OP CORRECTNESS: operations run in the wrong order, against the wrong ref, or without a required precondition (fetch, uncommitted-changes check) such that work could be lost or a branch left in a bad state. Report each as file:line + the trigger + the wrong outcome. Grade severity by blast radius: data loss or branch corruption = high; a bad message = low.

tests — Read TESTING_GUIDELINES.md first, then:

1. Run go build ./... and go test ./... (allow several minutes; test/cmd alone can take ~6 min). Report the exact result — pass, or the failing package + short error. State what you ran.
2. COVERAGE: each cmd/*.go command has a test/cmd/*_test.go? List missing or obviously thin ones (trivial commands like version are acceptable).
3. CONVENTIONS: init repos with git flow init --defaults; use testutil helpers (SetupTestRepo, RunGitFlow) rather than rolling their own; "one test case per function" for integration scenarios (table-driven is allowed only for pure functions); error-checked os.Chdir restore.
4. Flaky/skipped: t.Skip (legit platform guards vs real skips), timing/ network/ordering dependence, TODO stubs.
5. Dead or duplicated testutil helpers.

3. Write SUMMARY.md (full runs only)

When all seven areas ran, after the subagents finish, read the seven area files and write .ai/health-audit-<today>/SUMMARY.md:

# Repo Health Audit — <date>

<2–3 sentences: overall state, is the build/tests green, how much is drift vs real bugs.>

## Top priorities
<The handful of high-severity items across all areas, each one line with file:line and which area file has detail.>

## By area
| Area | high | med | low | Verdict |
|------|------|-----|-----|---------|
| docs | .. | .. | .. | <one line> |
| ... |

## Suggested next actions
<Group into: ship-before-release fixes, quick doc syncs, opportunistic consolidation, housekeeping. Each item → the pipeline that handles it (/gh-issue, direct edit, etc.).>

On a single-area run, skip SUMMARY.md.

4. Report to user

In the conversation: state the output dir, give the severity counts per area (or the one area), and list the top priorities in fix order. Do NOT dump the full reports — point to the files. Close by offering the obvious next step (file the high-severity items as issues, or fix the cheap doc drift directly).