Internal codebase health audit — checks docs, skills, duplication, dead code, coding-guidelines, correctness, and tests for drift and real defects. Runs all areas by default, or one named area. Writes per-area reports to .ai/health-audit-<date>/.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Health Audit?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/gittower-health-audit)
---
name: health-audit
description: Internal codebase health audit — checks docs, skills, duplication, dead code, coding-guidelines, correctness, and tests for drift and real defects. Runs all areas by default, or one named area. Writes per-area reports to .ai/health-audit-<date>/.
argument-hint: "[area: docs | skills | duplication | dead-code | guidelines | correctness | tests] (omit for all)"
allowed-tools: Bash, Read, Write, Glob, Grep, Task
---
# 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:
```bash
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`:
```markdown
# 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).