name: changelog-audit
description: |
Audit existing changelog/release infrastructure.
Finds issues, misconfigurations, and drift.

Changelog Audit

Deep analysis of existing release infrastructure.

Objective

Find everything that's wrong, suboptimal, or missing. Produce actionable findings.

Process

1. Configuration Audit

semantic-release config:

# Config exists and is valid?
node -e "require('./.releaserc.js')" 2>&1 || echo "INVALID CONFIG"

# Required plugins present?
grep -q "@semantic-release/changelog" .releaserc.js || echo "MISSING: changelog plugin"
grep -q "@semantic-release/git" .releaserc.js || echo "MISSING: git plugin"
grep -q "@semantic-release/github" .releaserc.js || echo "MISSING: github plugin"

# Branch configuration correct?
grep -q "main\|master" .releaserc.js || echo "WARNING: branch config may be wrong"

commitlint config:

# Config exists?
ls commitlint.config.* 2>/dev/null || echo "MISSING: commitlint config"

# Extends conventional config?
grep -q "config-conventional" commitlint.config.* 2>/dev/null || echo "WARNING: not using conventional config"

Lefthook integration:

# commit-msg hook exists?
grep -q "commit-msg" lefthook.yml 2>/dev/null || echo "MISSING: commit-msg hook in Lefthook"

# Hook runs commitlint?
grep -A5 "commit-msg" lefthook.yml 2>/dev/null | grep -q "commitlint" || echo "WARNING: commit-msg doesn't run commitlint"

2. GitHub Actions Audit

Workflow exists and is correct:

# Workflow file exists?
ls .github/workflows/release.yml 2>/dev/null || echo "MISSING: release workflow"

# Has required permissions?
grep -q "contents: write" .github/workflows/release.yml || echo "MISSING: contents write permission"

# Runs semantic-release?
grep -q "semantic-release" .github/workflows/release.yml || echo "WARNING: workflow doesn't run semantic-release"

# Has fetch-depth: 0?
grep -q "fetch-depth: 0" .github/workflows/release.yml || echo "WARNING: missing fetch-depth: 0 (needed for changelog)"

LLM synthesis workflow:

# Synthesis job exists?
grep -q "synthesize" .github/workflows/release.yml || echo "MISSING: synthesis job"

# References Gemini API key?
grep -q "GEMINI_API_KEY" .github/workflows/release.yml || echo "MISSING: GEMINI_API_KEY reference"

# Synthesis script exists?
ls scripts/synthesize-release-notes.mjs 2>/dev/null || echo "MISSING: synthesis script"

3. Secrets Audit

# Check if secrets are configured (can't read values, just check existence)
gh secret list | grep -q "GEMINI_API_KEY" || echo "MISSING: GEMINI_API_KEY secret"

# NPM_TOKEN only needed if publishing
grep -q "@semantic-release/npm" .releaserc.js && {
  gh secret list | grep -q "NPM_TOKEN" || echo "MISSING: NPM_TOKEN secret (needed for npm publish)"
}

4. Public Page Audit

# Page exists?
ls app/changelog/page.tsx src/app/changelog/page.tsx 2>/dev/null || echo "MISSING: changelog page"

# RSS feed exists?
ls app/changelog.xml/route.ts app/changelog/rss/route.ts public/changelog.xml 2>/dev/null || echo "MISSING: RSS feed"

# Page is public (no auth wrapper)?
grep -q "auth\|protect\|middleware" app/changelog/page.tsx 2>/dev/null && echo "WARNING: changelog page may have auth"

5. Release Health Check

# Recent releases exist?
RELEASES=$(gh release list --limit 5 --json tagName,publishedAt 2>/dev/null)
echo "Recent releases: $RELEASES"

# Releases have bodies (LLM notes)?
gh release view --json body | jq -r '.body' | head -5

# CHANGELOG.md in sync with releases?
head -50 CHANGELOG.md

# Any failed workflow runs?
gh run list --workflow=release.yml --status=failure --limit 5

6. Commit History Audit

# Recent commits follow conventional format?
git log --oneline -20 | while read line; do
  echo "$line" | grep -qE "^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: " || echo "NON-CONVENTIONAL: $line"
done

# Any commits that should have triggered releases but didn't?
git log --oneline main --since="1 week ago" | grep -E "^[a-f0-9]+ (feat|fix|perf):" | head -10

Output

Structured findings report:

CHANGELOG AUDIT REPORT
======================

CONFIGURATION
├── semantic-release: [OK | ISSUE: description]
├── commitlint: [OK | ISSUE: description]
└── Lefthook hook: [OK | ISSUE: description]

GITHUB ACTIONS
├── Release workflow: [OK | ISSUE: description]
├── Permissions: [OK | ISSUE: description]
├── Synthesis job: [OK | ISSUE: description]
└── Synthesis script: [OK | ISSUE: description]

SECRETS
├── GEMINI_API_KEY: [CONFIGURED | MISSING]
└── NPM_TOKEN: [CONFIGURED | MISSING | NOT NEEDED]

PUBLIC PAGE
├── Changelog route: [OK | MISSING]
├── RSS feed: [OK | MISSING]
└── Auth status: [PUBLIC | WARNING: may have auth]

RELEASE HEALTH
├── Recent releases: [N releases | NONE]
├── Release notes: [POPULATED | EMPTY]
├── CHANGELOG.md: [IN SYNC | OUT OF SYNC]
└── Failed runs: [NONE | N failures]

COMMIT HEALTH
├── Conventional format: [N/20 compliant]
└── Missed releases: [NONE | N commits should have released]

---
SUMMARY: X pass, Y warn, Z fail

CRITICAL:
- [List critical issues]

HIGH:
- [List high priority issues]

MEDIUM:
- [List medium priority issues]

Issue Categories

CRITICAL (blocks releases):
- Missing or invalid semantic-release config
- Missing GitHub Actions workflow
- Missing required permissions

HIGH (degrades quality):
- Missing commitlint enforcement
- Missing LLM synthesis
- Empty release notes

MEDIUM (nice to have):
- Missing RSS feed
- Non-conventional commits in history
- Missing public page