Autonomous audit-to-fix pipeline (/gsd-audit-fix)

[davesienkowski]

Pre-submission checklist

• I have searched existing issues and discussions -- this has not been proposed and declined before
• I have read CONTRIBUTING.md and understand that I must wait for approved-feature before writing any code
• I have read the existing GSD commands and workflows and confirmed this feature does not duplicate existing behavior
• This feature solves a problem for solo developers using AI coding tools, not a personal preference or workflow I happen to like

Feature name

Autonomous audit-to-fix pipeline (/gsd-audit-fix)

Type of addition

New command (slash command or CLI flag)

The solo developer problem

GSD has several audit commands that detect problems: /gsd-audit-uat finds outstanding verification items, /gsd-validate-phase finds Nyquist validation gaps, /gsd-health finds directory corruption, and /gsd-audit-milestone finds milestone completion gaps. Each produces a report of findings.

But after running an audit, a solo developer must manually triage findings, decide which are fixable, fix them one at a time, run tests after each fix, and commit. This is tedious and error-prone -- the developer often fixes the easy ones and leaves the rest. There is no GSD command that chains audit -> triage -> fix -> test -> commit into a single automated pipeline.

The gap is not in detection (GSD detects well) but in remediation (GSD does not act on findings).

What this feature adds

A new /gsd-audit-fix command that orchestrates a complete audit-to-fix pipeline:

Step 1 -- Run audit: Invokes an existing GSD audit command (default: /gsd-audit-uat, overridable via --source) to collect findings.

Step 2 -- Parse findings: Extracts findings from the audit report, categorized by severity (Critical, High, Medium, Low).

Step 3 -- Classify fixability: Each finding is classified as either:

• auto-fixable -- clear mechanical remediation exists (missing fields, broken file paths, stale references, config drift, uncommitted planning doc changes, incorrect test assertions)
• manual-only -- requires human judgment (architectural decisions, ambiguous context, multi-system coordination, performance tradeoffs)

A classification table is displayed showing auto-fixable vs manual-only findings with reasons.

Step 4 -- Execute fixes: For each auto-fixable finding (up to --max), ordered by severity (Critical first):

1. Spawn a gsd-executor agent with the specific finding, evidence, and remediation steps
2. The executor makes the minimal fix, runs npm test
3. If tests pass, commit atomically: fix(scope): description (audit finding ID)
4. If tests FAIL, the pipeline stops immediately -- no further fixes attempted

Step 5 -- Report: Summary of findings processed, fixed, skipped (manual), and any test failure. Lists remaining manual findings with descriptions.

Flags:

Flag	Default	Description
--max N	5	Maximum number of findings to fix
--severity LEVEL	medium	Minimum threshold: high (Critical+High only), medium (+Medium), all (+Low)
--dry-run	false	Show classification table without executing fixes
--source COMMAND	audit-uat	Which GSD audit command to use as finding source

Example usage:

/gsd-audit-fix
> Running audit (source: audit-uat)...
> Found 8 findings at severity >= medium
> Auto-fixable: 5 | Manual-only: 3
>
> [1/5] Fixing H2: Missing verification for auth endpoint
>   Spawning executor... Tests pass. Committed abc1234.
> [2/5] Fixing M1: Stale file reference in UAT doc
>   Spawning executor... Tests pass. Committed def5678.
> [3/5] Fixing M3: Config drift in phase manifest
>   Spawning executor... TESTS FAILED. Pipeline stopped.
>
> Fixed: 2/5 | Test failure: 1 | Remaining manual: 3

/gsd-audit-fix --dry-run --severity all
> Found 12 findings
> Auto-fixable: 7 | Manual-only: 5
> [dry run -- no fixes executed]

Safety constraints:

• All code changes are delegated to spawned executor agents -- the orchestrator never edits files directly
• The pipeline stops on the first test failure (no skipping)
• Findings below the severity threshold are ignored
• Findings classified as manual-only are never attempted
• The --max cap prevents runaway fix attempts

Full scope of changes

Files created:

• commands/gsd/audit-fix.md -- slash command definition with --max, --severity, --dry-run, --source flags
• get-shit-done/workflows/audit-fix.md -- pipeline orchestration: audit -> parse -> classify -> fix -> test -> commit -> report

Files modified:

• None required. The command and workflow are self-contained. They consume existing GSD audit command output and spawn existing gsd-executor agents.

User stories

1. As a solo developer who just ran an audit and sees 8 findings, I want to run /gsd-audit-fix to automatically fix the mechanical ones (broken paths, missing fields, stale references) so I only have to manually address the findings that genuinely need my judgment.
2. As a solo developer before submitting a PR, I want to run /gsd-audit-fix --dry-run to see which audit findings are auto-fixable and which need manual attention, so I can prioritize my remaining cleanup work.
3. As a solo developer who wants maximum automation, I want to run /gsd-audit-fix --max 10 --severity all to fix as many findings as possible in one pass, with the pipeline stopping safely if any fix breaks tests.

Acceptance criteria

• /gsd-audit-fix invokes /gsd-audit-uat by default and parses its findings
• --source validate-phase switches the audit source to /gsd-validate-phase findings
• Findings are classified as auto-fixable or manual-only with reasons displayed
• --dry-run shows the classification table without executing any fixes
• Auto-fixable findings are fixed by spawned gsd-executor agents, not by the orchestrator
• Each fix is followed by npm test; on pass, an atomic commit is created
• The pipeline stops immediately on the first test failure
• --max N limits the number of fix attempts
• --severity high processes only Critical and High findings
• A final report shows: findings processed, fixed, failed, and remaining manual items
• The command is discoverable via /gsd-help

Which area does this primarily affect?

Core workflow (init, plan, build, verify)

Applicable runtimes

• Claude Code
• All runtimes (runtime-agnostic)

The command is a markdown workflow that spawns executor agents and invokes existing GSD audit commands, making it runtime-agnostic.

Breaking changes assessment

None. This is an entirely new command. No existing audit commands are modified -- they are consumed as-is.

Maintenance burden

Medium. The finding parser must handle the output format of each supported audit source command. If audit report formats change, the parser needs updating. The fixability classifier is heuristic-based -- new finding types may need classification rules added. The executor delegation pattern reuses existing gsd-executor agents, so executor improvements automatically benefit this pipeline.

Alternatives considered

1. Manual triage after audit (status quo) -- Solo developer must read the report, decide what to fix, fix each one manually, test, and commit. This is the gap the feature addresses.
2. Fix all findings without classification -- Rejected because some findings require human judgment. Attempting to auto-fix an architectural decision would produce wrong code.
3. Integrate fixing into each audit command -- Rejected because it would complicate every audit command. A standalone pipeline is composable and keeps audit commands focused on detection.
4. Single-finding fix only (no pipeline) -- Rejected because the value is in batch processing. Fixing findings one at a time via /gsd-quick already works but does not scale.

Prior art and references

• PBR fork audit-fix skill (plan-build-run/plugins/pbr/skills/audit-fix/SKILL.md) -- the pattern this is adapted from
• GSD existing audit commands (/gsd-audit-uat, /gsd-validate-phase, /gsd-health, /gsd-audit-milestone) -- the finding sources this consumes
• CI/CD auto-fix patterns (ESLint --fix, Prettier --write) -- conceptual model for classify-then-fix

[trek-e]

✅ Approved as feature.

Most thorough spec in the batch. The safety design is solid — stop on first test failure, executor delegation, max cap, severity filter, dry-run mode, and auto-fixable vs manual-only classification.

Implementation notes:

• Start with audit-uat as the only supported --source — add parsers for other audit formats incrementally, not all at once
• The fixability classifier should err on the side of "manual-only" when uncertain — a false negative (skipping an auto-fixable item) is far less costly than a false positive (botching a judgment call)
• Commit messages should include the finding ID for traceability back to the audit report
• The --dry-run classification table is valuable on its own — make sure it's useful even if the user never runs without --dry-run

@davesienkowski — labeled approved-feature. You're clear to implement.