/dld-audit-auto — Autonomous Audit & Fix

You are running an autonomous audit of the decision-code relationship. Unlike the interactive /dld-audit, you detect issues and fix them without asking for human input. Your output is a branch with fixes and a PR for review.

This skill is designed for unattended execution — scheduled runs, CI pipelines, or autonomous agent sessions. Do not ask questions or wait for user input.

Script Paths

Shared scripts:

../dld-common/scripts/common.sh
../dld-common/scripts/regenerate-index.sh
../dld-common/scripts/update-status.sh

Skill-specific scripts:

../dld-audit/scripts/find-annotations.sh
../dld-audit/scripts/update-audit-state.sh

Prerequisites

1. Check that dld.config.yaml exists at the repo root. If not, exit with a clear error message.
2. Verify the working tree is clean (git status --porcelain should be empty). If not, exit — do not mix audit fixes with uncommitted work.

Step 1: Create audit branch

git checkout -b dld/audit-$(date +%Y%m%d-%H%M%S)

Step 2: Run the full audit

Perform all the same checks as /dld-audit:

a) Collect annotations and decision records

bash ../dld-audit/scripts/find-annotations.sh

Read all DL-*.md files in the records subdirectory (decisions/records/). Note each decision's ID, status, and code references.

b) Detect issues

Check for all drift categories:

1. Orphaned annotations — annotations referencing non-existent decision IDs
2. Annotations referencing non-accepted decisions — code tied to deprecated or superseded decisions
3. Stale references in decisions — frontmatter references to files that no longer exist
4. Unreferenced code changes — annotated files modified since last audit (if previous audit state exists)
5. Decisions without annotations — accepted decisions with code references but no corresponding annotations in code

For check (4), if decisions/.dld-state.yaml exists with an audit.commit_hash, first verify reachability:

git cat-file -t <commit_hash> 2>/dev/null

If unreachable (e.g., after rebase or shallow clone), skip check (4) and note it in the PR description. If reachable, use git diff --name-only <commit_hash>..HEAD to find changed files and cross-reference with annotated files.

Step 3: Fix issues

Apply fixes for each issue category. Use judgment on what can be safely fixed automatically vs. what should only be flagged in the PR description.

Auto-fixable (apply these directly):

Orphaned annotations — If the annotation has an obvious typo (e.g., DL-01 where DL-001 exists), fix it. If the referenced ID is completely unknown, remove the annotation and note the removal in the commit message.

Stale references in decisions — Remove file paths from the decision's references field that no longer exist. If the file was renamed/moved (detectable via git log --follow --diff-filter=R), update the path instead of removing.

Annotations referencing superseded decisions — Update the annotation to reference the superseding decision (read the supersedes field of the newer decision to find the chain). For deprecated decisions, remove the annotation.

Decisions without annotations — If an accepted decision has code references but no annotations, and the referenced files exist, add the missing @decision(DL-NNN) annotations to the referenced code locations.

Best-effort fixes (apply, but flag prominently for review):

Unreferenced code changes — Annotated files that were modified since the last audit without a corresponding decision update. These represent changes made outside the DLD process. Try to resolve them:

1. Check commit messages — Read the commits that modified the file (git log --oneline <last_audit_hash>..HEAD -- <file>). Look for context about what changed and why.
2. Look up referenced tickets — If commit messages reference a ticket (e.g., Jira, Linear, GitHub issue), try to look it up using available tools (MCP servers, gh CLI, etc.) to gather additional context about the change.
3. Assess the impact — Read the current code and the associated decision(s). Determine whether:
   • The existing decision is still accurate (the change was compatible — no action needed)
   • The existing decision needs a minor update (refine the decision record)
   • A new decision is needed (the change introduced new behavior not covered by existing decisions)
4. Create or update decisions — Based on the assessment, either update the existing decision record or create a new decision using the standard scripts. Add @decision annotations to the new/changed code. Mark any new decisions as accepted since the code already exists.

Important: These best-effort fixes are inferred, not authoritative. In the PR description, clearly mark each one under a "Inferred Decisions — Review Required" section. Explain what changed, what context was found (commit messages, tickets), and what decision was created or updated. Reviewers should prioritize checking these for accuracy.

Step 4: Regenerate INDEX.md

If any decision records were modified:

bash ../dld-common/scripts/regenerate-index.sh

Step 5: Update audit state

bash ../dld-audit/scripts/update-audit-state.sh

Step 6: Commit, push, and open PR

If there are changes (fixes were applied or audit state was updated):

git add -A

Commit with a descriptive message summarizing the fixes:

git commit -m "fix: resolve DLD audit drift

- [list each fix applied]
- Audit state updated"

Push and open a PR:

git push -u origin HEAD

Create a PR with the following structure:

## DLD Audit — Automated Drift Fixes

**Audit date:** YYYY-MM-DD
**Issues found:** N
**Auto-fixed:** M
**Needs review:** K

### Fixes Applied

- [Description of each fix, grouped by category]

### Inferred Decisions — Review Required

These decisions were created or updated based on code changes made outside the DLD process. The rationale was inferred from commit messages and available ticket context. **Please verify accuracy.**

- **DL-NNN: [Title]** (new/updated) — [What changed in the code, what context was found, what was inferred]

### Audit Summary

| Check | Result |
|-------|--------|
| Orphaned annotations | N found, M fixed |
| Stale references | N found, M fixed |
| Superseded/deprecated refs | N found, M fixed |
| Missing annotations | N found, M added |
| Modified annotated files | N flagged for review |

If no issues were found (only audit state updated), still commit and push the state update but do not open a PR. Instead, exit with a message:

Audit complete. No drift detected. Audit state updated.