# Audit Gnadd > Read-only GNADD alignment audit: load workflow principles, scrutinize context files for describe-vs-track violations, perform a shallow git/workflow check, and return a severity-grouped report with minimal proposed fixes. Nudges /new-issue-gnadd for remediation slices; never edits files or creates issues. Use when the user asks to audit GNADD alignment, review workflow hygiene, check project context files, or find describe-vs-track violations. - Skill: `alexhagemeister/audit-gnadd` (Agent Skill) - Install (CLI): `npx skillmds@latest add alexhagemeister/audit-gnadd` - Raw SKILL.md: https://api.skillmd.com/api/skills/alexhagemeister/audit-gnadd/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: AlexHagemeister (https://skillmd.com/u/alexhagemeister) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/alexhagemeister/audit-gnadd --- # GNADD Audit Review a repository against GNADD workflow principles and propose a minimal set of alignment fixes. This is read-only: do not create, edit, stage, commit, stash, or delete files; do not auto-create GitHub issues. ## Auto-Invocation Gate If this skill was auto-selected from context rather than explicitly invoked with `/audit-gnadd`, stop before running commands or reading repo context. Briefly explain why a GNADD audit appears useful and ask: "Run `/audit-gnadd` now?" Proceed only after confirmation. ## GNADD Invariants - GitHub is the system of record; tracking state belongs in issues, branches, PRs, and commits — not in markdown files. - Context-file scrutiny is the primary audit dimension; git/workflow checks are secondary alignment signals. - The audit complements `prime-gnadd` (live snapshot) — it does not replace session orientation or duplicate its narrative output. - Proposed fixes are slices for the user to capture via `/new-issue-gnadd`; the agent never files issues autonomously. - For broader workflow rationale, use `help-gnadd`. ## Purpose Answer: **Is this repo aligned with GNADD principles, and what is the smallest fix set to get there?** Build a structured report covering: - Context files that violate or risk violating the describe-vs-track rule - Shallow git/workflow misalignment (orphaned branches, diverged `main`, stashes) - Whether GNADD skills appear installed - Minimal proposed fixes, each mappable to one `/new-issue-gnadd` Do not read source code, schemas, tests, or dependencies. Do not perform deep commit archaeology. ## Workflow ### 1. Load Audit Criteria Before inspecting the repo, load GNADD file-hygiene and workflow principles: 1. Use the describe-vs-track rule from `help-gnadd` if already in context. 2. Fetch Part 1 of the canonical guide from this pinned URL (same pin as `help-gnadd` — do not use `main`): https://raw.githubusercontent.com/AlexHagemeister/gnadd/v0.5.0/GNADD.md (The pin is rewritten by `scripts/release.sh` at release time.) 3. If the repo being audited contains a local `GNADD.md`, reading Part 1 locally is an acceptable fallback or supplement. Extract the operational taxonomy: | Category | Examples | Default severity | |---|---|---| | Tracking files | `tasks.md`, `TODO.md`, progress/session-state files, maintained plans, status checklists | Violation | | Expired phase artifacts | `requirements.md`, standalone PRD/spec/plan not distilled into `VISION.md` + issues | Warning | | Misplaced decisions | `decisions.md`, ADR folders used as live tracking | Warning | | Describe-only (OK) | `VISION.md` (Core, Possibility space, Open tensions, no status or order), README run instructions plus a pointer to `VISION.md`, `AGENTS.md`, agent rules, archived/dated requirements | OK | | README carrying intent | A README that restates vision, invariants, or done-criteria instead of pointing at `VISION.md` (the guide's Part 1: the README is run instructions and a pointer) | Warning | | Missing describe content | No `VISION.md` on a GNADD-shaped project (a README "What done looks like" section is the pre-VISION.md shape and reads as a Warning to migrate) | Warning | Apply the tiebreaker from GNADD Part 1: > Would the agent need to keep this file up to date? If yes → tracking violation. ### 2. Discover Context Files From the repo root, run a shallow filename discovery (depth-capped, skip `.git`, `node_modules`, `vendor`, `dist`, `build`, `.next`, `.venv`, `coverage`, `target`): ```bash find . -maxdepth 4 -type f \( \ -iname 'tasks.md' -o -iname 'task.md' -o -iname 'todo.md' -o -iname 'todo.txt' \ -o -iname 'requirements.md' -o -iname 'prd.md' -o -iname 'spec.md' \ -o -iname 'decisions.md' -o -iname 'progress.md' -o -iname 'status.md' \ -o -iname 'roadmap.md' -o -iname 'changelog-dev.md' \ -o -iname 'session.md' -o -iname 'session-state.md' \ \) -not -path './.git/*' -not -path '*/node_modules/*' -not -path '*/vendor/*' \ -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/.next/*' \ -not -path '*/.venv/*' -not -path '*/coverage/*' -not -path '*/target/*' 2>/dev/null ``` Always read `README.md` and `VISION.md` at the repo root if they exist. For each discovered file (and `README.md`, `VISION.md`): - Read enough to classify — usually the first ~50 lines suffices. - Look for **tracking signals:** `- [ ]` / `- [x]` checkboxes, "Status:", "In Progress", sprint/progress sections, satisfaction tracking, maintained task lists, "current focus" notes the agent would need to update. - Look for **safe signals:** archive headers, "as of DATE", explicit notes that content was distilled into issues/VISION.md, pure vision/convention text with no mutable state. In `VISION.md` specifically, a checkbox, a status, an ordered plan, or a library choice is a tracking signal. Classify each file as **Violation**, **Warning**, or **OK** with a one-line rationale. When filename and content conflict, content wins. ### 3. Check GNADD Skills Presence Determine whether GNADD skills appear available to the agent: ```bash ls .agents/skills/ .claude/skills/ ~/.claude/skills/ 2>/dev/null ``` Look for `help-gnadd`, `prime-gnadd`, `new-issue-gnadd`, or similar GNADD skill names in any of the three (project-local skills CLI, project-local Claude Code, global Claude Code). Optionally try `npx skills list 2>/dev/null` if the skills CLI is available. If undetectable or absent, report as **Info** — not a blocker. Include the minimal install recommendation: ```bash npx skills add AlexHagemeister/gnadd -g -a --copy -y ``` (`-g` installs globally — omit it for a project-local install, and update later in whichever scope was chosen; see help-gnadd's Install & Update.) The file and git audit still runs regardless. ### 4. Shallow Git / Workflow Alignment Verify GitHub CLI when checking workflow alignment: ```bash gh auth status ``` If `gh` is not installed or authenticated, warn the user, skip GitHub cross-checks, and still report local git signals from the commands below. When auth is confirmed (or for local-only checks), run from the repo root: ```bash git fetch --prune origin 2>/dev/null || true git branch --show-current git branch --list git stash list git log --oneline origin/main..main 2>/dev/null git log --oneline main..origin/main 2>/dev/null gh issue list --state open 2>/dev/null gh pr list --state open 2>/dev/null ``` `git fetch --prune` updates remote-tracking refs only — read-only, same as `prime-gnadd`. If no remote is configured, note it and continue with local signals. Interpret for **alignment only** — do not produce a session-orientation narrative: | Signal | Severity | Finding | |---|---|---| | `origin/main..main` shows commits | Violation | Local `main` ahead of origin — direct commits bypassing the loop | | `main..origin/main` shows commits | Info | Local `main` behind origin — sync before adopting the loop | | Non-empty stash list | Warning | Invisible WIP outside issues/branches | | Branch `issue-/*` with no open issue #N | Warning | Orphaned issue branch | | Open issue #N with no branch and no recent merged PR | Info | Issue may be unstarted | | Active WIP branch not matching `issue-/` | Warning | Off-loop branch naming | | Open PR with no issue reference in title/body | Warning | Weak issue linkage | | `phase status` reports more than one open milestone | Warning | The phase rule wants exactly one; the rest need a verdict | | `phase status` reports `phase=none` with open issues | Info | Work is not attached to a phase (fine for a small repo, worth naming on a GNADD-shaped one) | Read the phase layer through prime's copy of the script (this skill does not bundle it): ```bash bash "/gnadd.sh" phase status ``` Do **not** review individual commits, run blame, or lint commit messages. Cross-reference open issues with local branches by issue number extracted from branch names (`issue-/...`). ### 5. Synthesize Minimal Fixes For every Violation and Warning, propose **one concrete minimal fix** — not a broad rewrite plan. Group related fixes into **proposed issue slices** the user can capture separately via `/new-issue-gnadd`. Examples: - `tasks.md` exists → "Migrate open items to GitHub issues, then delete the file." - Stale `requirements.md` → "Delete after distilling what passes the admission test into VISION.md and actionable items into issues." - Standalone PRD with tracking content → "Move intent into VISION.md (Core for invariants, Possibility space for the rest); move actionable specifics to issues." - README with a "What done looks like" section → "Migrate: invariants to VISION.md Core, phase done-criteria to a milestone; leave run instructions and a pointer." - GNADD skills not detected → "Install GNADD skills globally per README." - Diverged local `main` → "Resolve main divergence before starting new issue work — the sanctioned path is `gnadd.sh doctor --rescue-main ` (bundled with the `prime-gnadd` skill), which is lossless and never resets." - No branch ruleset / merge policy on the repo → "Run `gnadd.sh init` once to enforce squash-only merges and PR-required main at the server." Keep the fix set minimal — prefer the smallest change that restores alignment. ### 6. Produce the Report Use the output format below. Lead with violations; do not bury context-file findings below git noise. ## Classification Reference **Violation** — Confirmed tracking file or workflow habit that actively undermines GNADD (task lists, progress files, diverged `main` with local-only commits). **Warning** — Likely misalignment needing human judgment (expired `requirements.md`, fat PRD, orphaned branch, missing `VISION.md`). **OK** — Describe-only content correctly structured (vision docs, `AGENTS.md`, archived phase artifacts clearly marked). **Info** — Informational, not necessarily a problem (skills install unverified, issue with no branch yet, `main` behind origin). ## Output Format ```markdown ## Summary <1-2 sentences: overall alignment verdict — counts of violations, warnings, OK> ## Context Files ### Violations - `` — . **Fix:** ### Warnings - `` — . **Fix:** ### OK - `` — ## Workflow Alignment ## GNADD Skills ## Proposed Fixes 1. 2. ... ## Already Aligned ``` Keep the report scannable. Each proposed fix should be actionable without reading the rest of the audit. ## Closing Guidance Offer a brief next-step nudge only when the audit completed successfully — not when `gh auth` failed mid-run and GitHub checks were skipped. **Skip** when the audit halted early or critical checks could not run — tell the user what's missing first. **Infer one primary suggestion** from findings, plus at least one alternative when ambiguous: 1. **Violations present** → nudge `/new-issue-gnadd` for the highest-severity fix; offer capturing the full proposed-fix list as separate issues. 2. **Warnings only, no violations** → nudge confirming which warnings are intentional before filing issues; offer `/new-issue-gnadd` for any the user wants to act on. 3. **Clean audit** → nudge `/prime-gnadd` for ongoing session work, or `/new-issue-gnadd` if new work is ready to capture. 4. **GNADD skills not detected on a repo being adopted** → nudge installing skills first, then re-running `/audit-gnadd` after remediation issues are filed. Keep it to a sentence or two with invitational options. Do not restate the full GNADD workflow. Never auto-create issues.