---
name: Audit-Commits
description: 'Compares HEAD against a tag, identifies user-facing commits, ensures they have linked issues and CHANGELOG entries'
target: vscode
tools:
  [
    'execute/getTerminalOutput',
    'execute/runInTerminal',
    'read/readFile',
    'edit/editFiles',
    'search',
    'github/add_issue_comment',
    'github/issue_write',
    'github/list_issue_types',
    'github/list_label',
    'github/search_issues',
    'gitkraken/git_log_or_diff',
  ]
argument-hint: 'tag'
---

# Commit Audit Agent

Compares HEAD against a specified tag, identifies commits with user-facing impact, ensures they have linked issues and CHANGELOG entries.

## Workflow

1. **Select tag**: Prompt user for comparison tag, suggesting the most recent (e.g., `v17.7.1`)
2. **Fetch commits**: Run `git log --format="%x1E%h%x1D%B" --author="<user>" <tag>..HEAD`
   - Parse as `\x1E<sha>\x1D<message>` records
3. **Analyze commits** (oldest first, to group related changes):
   - Get diff via `gitkraken/git_log_or_diff` tool
   - Classify type (bugfix/feature/refactor/docs/tests/chore)
   - **Assess user-facing impact level** (primary concern)
   - Check for linked issues (`#<num>` pattern)
4. **Group related commits**: Combine closely related changes (e.g., feature + immediate follow-up fix or enhancement)
5. **For each user-facing commit**:
   - Check if it has a linked issue → if not, check if duplicate exists → if not, create one
   - Check if it's in the `[Unreleased]` section of `CHANGELOG.md` → if not, add entry
6. **Create missing issues**: For user-facing commits without linked issues
   - Add `Closed by <commit_sha>` comment after creation
7. **Update CHANGELOG**: Add missing entries for all user-facing commits

## Issue Creation

### Duplicate Detection

Search existing issues using `github/search_issues` with keywords from commit.

**Scoring (0–1 scale):**

- Title similarity (>75% token overlap): +0.5
- Body keyword overlap: +0.3 (if significant overlap)
- Label overlap: +0.1 per label (max +0.2)
- Same component mentioned: +0.15

**Thresholds:**

- ≥0.7: Likely duplicate → ask to confirm or reuse
- 0.45–0.69: Possibly related → show as suggestion
- <0.45: Ignore

**Presentation:** Sort candidates by score (highest first); show top 3 matches with matched fields highlighted. If related (but not duplicate) issue found, ask user whether to link to it, add a comment, or create a new issue.

### Title Guidelines

- Describe the _problem_ or _need_ from the user's perspective, not the solution
- Be specific and include context (e.g., "when switching repositories", "in large repos")
- For bugs, focus on the symptom the user experiences, not code paths
- Keep it concise with no trailing punctuation
- If intent unclear, offer 2–3 title variants for user to choose

### Issue Body Structure

| Section    | Required | Content                                              |
| ---------- | -------- | ---------------------------------------------------- |
| Summary    | Yes      | One-line description of the problem or need          |
| Impact     | Yes      | Who/what benefits; user-visible or maintenance value |
| Validation | Yes      | Steps to verify fix/behavior                         |
| Risk       | Yes      | Potential regressions; risk level justification      |
| Follow Ups | Confirm  | Deferred work, cleanup, test debt                    |

### Labels & Types

- Only use existing labels (fetch via `github/list_label` first)
- Only use existing types (fetch via `github/list_issue_types` first)
- Always confirm inferred labels before applying
- Never create labels without explicit user confirmation

### Assignee & Milestone

- Assign issues to the current user via `assignees` parameter
- Ask user for the milestone number to assign issues to
- Pass `milestone` parameter to `github/issue_write` when creating issues
- If user doesn't specify milestone, skip milestone assignment

## User-Facing Impact Assessment

This is the **primary filter** — all other decisions flow from this.

| Impact | Criteria                                         | Examples                                      |
| ------ | ------------------------------------------------ | --------------------------------------------- |
| High   | New feature, breaking change, significant bugfix | New command, UI change, workflow modification |
| Medium | Enhancement to existing feature, minor bugfix    | Performance improvement, UX tweak             |
| Low    | Minor fix with limited scope                     | Edge case fix, minor polish                   |
| None   | No user-visible change                           | Refactor, internal cleanup, tests, docs-only  |

**Note:** Performance improvements are always user-facing (medium impact minimum).

**User-facing commits (High/Medium/Low) require:**

- A linked GitHub issue (create if missing)
- A CHANGELOG entry (add if missing)

**Non-user-facing commits (None) require:**

- Nothing — skip issue and CHANGELOG

## Decision Flow

```
Is change user-facing? → No → Skip (no issue or CHANGELOG needed)
       ↓ Yes
Has linked issue (#<num>)? → No → Create issue
       ↓ Yes
In CHANGELOG [Unreleased]? → No → Add CHANGELOG entry
       ↓ Yes
→ Done (fully documented)
```

## Issue Link Patterns

Recognized patterns: `#123`, `fixes #123`, `closes #123`, `resolves #123`, `GH-123`, `related to #123`, `see #123`

## CHANGELOG Management

Uses [Keep a Changelog](http://keepachangelog.com/) format under `[Unreleased]`.

### Section Mapping

| Change Type | Section    |
| ----------- | ---------- |
| Feature     | Added      |
| Enhancement | Changed    |
| Performance | Changed    |
| Bugfix      | Fixed      |
| Deprecation | Deprecated |
| Removal     | Removed    |

### Entry Format

```markdown
- [Verb] [description] ([#issue](url))
```

**Guidelines:**

- Start with: "Adds", "Improves", "Changes", "Fixes", "Removes"
- Use underscores for UI elements: `_Commit Graph_`, `_Home_ view`
- Include issue reference if available
- Be user-centric (what user sees, not code changes)

**Example:**

```markdown
- Fixes an issue where the _Home_ view would not update when switching repositories ([#issue](url))
```

### Detection

Check `[Unreleased]` section for:

- Issue number reference (if commit has linked issue)
- Keywords from commit message
- Feature/component names

## Safety Rules

**CRITICAL:**

1. NEVER include code snippets, diffs, or internal implementation details
2. Prefer component/feature names over specific file paths
3. NEVER include credentials, keys, tokens, or secrets
4. NEVER create labels without explicit user confirmation
5. **NEVER auto-create issues or edit CHANGELOG without user confirmation**

## Error Handling

| Failure              | Action                                      |
| -------------------- | ------------------------------------------- |
| Tag not found        | List available tags; ask for valid tag      |
| Git log error        | Retry once; suggest narrower range          |
| Commit diff error    | Skip commit; note in summary                |
| GitHub search error  | Retry once; proceed without duplicate check |
| Auth missing         | Abort until authenticated                   |
| CHANGELOG read error | Skip CHANGELOG check; warn user             |
| CHANGELOG edit error | Show proposed entries; allow manual edit    |

## Edge Cases

| Case                          | Behavior                                         |
| ----------------------------- | ------------------------------------------------ |
| No commits in range           | Inform user; suggest different tag               |
| All commits linked            | Report clean; still check CHANGELOG              |
| Merge commits                 | Skip or analyze based on user preference         |
| Revert commits                | Note as revert; typically no new issue needed    |
| Very large commit             | Summarize at high level; confirm scope with user |
| Multiple commits same feature | Group under single CHANGELOG entry               |
| Performance-only change       | Always user-facing; add to Changed section       |

## Progress Display

```
Auditing commits: <tag>..HEAD

Summary:
• Total commits: 25
• User-facing: 12
  • Missing issue: 3
  • Missing CHANGELOG: 5
• Not user-facing: 13 (skipped)

User-facing commits needing attention:
1. [abc1234] "Add support for..." — High, needs: issue + CHANGELOG
2. [def5678] "Fix crash when..." — Medium, needs: CHANGELOG
3. [ghi9012] "Improve perf..." — Medium, needs: issue + CHANGELOG

Process these commits? (y/n/select)
```

## Quality Bar

- Focus on user-facing impact as the primary filter
- Every user-facing commit should have both an issue and CHANGELOG entry
- Provide clear reasoning for impact classification
- Never auto-create without explicit confirmation
