document-changes skill

Document Changes

Generate a structured markdown report documenting codebase changes from the current working session. The report captures files changed, commit history, and a human-readable summary suitable for team reviews, handoff documentation, or personal records.

Arguments

• $ARGUMENTS — Optional scope or description for the report (e.g., "auth refactor", "add OAuth2 support"). Used to name the output file and populate the report's scope field. If not provided, scope is inferred from commit messages or changed file paths.

Workflow

Execute these 4 steps in order. Stop early if Step 1 or Step 2 determines there is nothing to report.

---

Step 1: Validate Git Repository

Verify the current directory is inside a git repository:

git rev-parse --is-inside-work-tree

• If the command fails or returns false, stop and report: "Not inside a git repository. This skill requires git to gather change data."
• If successful, continue to Step 2.

---

Step 2: Gather Changes and Metadata

Collect all change data by running these git commands. If any individual command fails, continue with the data that is available.

2.1 Repository Metadata

git branch --show-current

git config user.name

git remote get-url origin 2>/dev/null

date "+%Y-%m-%d %H:%M %Z"

2.2 Uncommitted Changes

git status --porcelain

git diff --stat

git diff --name-status

2.3 Staged Changes

git diff --cached --stat

git diff --cached --name-status

2.4 Recent Commits (up to 20)

git log --oneline -20

git log --format="%H|%s|%an|%ai" -20

2.5 Session Commit Diffs

If there are recent commits (N > 0 from Step 2.4):

git diff --stat HEAD~N..HEAD

git diff --name-status HEAD~N..HEAD

Replace N with the number of recent commits found (capped at 20). If the repo has fewer than N commits, use git diff --stat $(git rev-list --max-parents=0 HEAD)..HEAD instead.

2.6 Combine and Deduplicate

Build a unified list of all affected files from Steps 2.2–2.5, deduplicating entries. For each file, track:

• Status: Added (A), Modified (M), Deleted (D), Renamed (R)
• Source: Whether the change is committed, staged, unstaged, or untracked

Stop condition: If there are no uncommitted changes (Step 2.2 is empty), no staged changes (Step 2.3 is empty), and no recent commits (Step 2.4 is empty), stop and report: "No changes found in the current repository. Nothing to document."

---

Step 3: Determine Report Location

3.1 Generate Filename Description

Create a short kebab-case description (2-4 words) for the filename:

• If $ARGUMENTS is provided: Convert to kebab-case (e.g., "auth refactor" → auth-refactor)
• If $ARGUMENTS is not provided: Infer from the most common theme in commit messages or changed file paths (e.g., api-bug-fixes, add-oauth2-support, ui-component-updates)

Build the recommended path: internal/reports/<description>-YYYY-MM-DD.md using today's date.

3.2 Ask User for Report Location

Use AskUserQuestion:

Where should the change report be saved?

Recommended: internal/reports/<description>-YYYY-MM-DD.md

Options:

1. "Use recommended path (Recommended)" — Save to internal/reports/<description>-YYYY-MM-DD.md
2. "Custom path" — User provides their own file path

If user selects "Custom path": Use a follow-up AskUserQuestion asking for the full file path.

3.3 Validate Path

• The path must end with .md
• If the parent directory does not exist, create it with mkdir -p

---

Step 4: Generate and Write Report

Build the markdown report with the following structure, then write it using the Write tool.

Report Template

# Codebase Changes Report

## Metadata

| Field | Value |
|-------|-------|
| **Date** | YYYY-MM-DD |
| **Time** | HH:MM TZ |
| **Branch** | {current branch} |
| **Author** | {git user.name} |
| **Base Commit** | {earliest commit hash before session changes, or N/A} |
| **Latest Commit** | {most recent commit hash, or "uncommitted"} |
| **Repository** | {remote URL, or "local only"} |

**Scope**: {from $ARGUMENTS, or inferred from changes}

**Summary**: {1-2 sentence executive summary of what was done}

## Overview

{High-level stats paragraph}

- **Files affected**: N
- **Lines added**: +N
- **Lines removed**: -N
- **Commits**: N

## Files Changed

| File | Status | Lines | Description |
|------|--------|-------|-------------|
| `path/to/file.ts` | Modified | +12 / -3 | Brief description of changes |
| `path/to/new.ts` | Added | +45 | Brief description |
| `path/to/old.ts` | Deleted | -20 | Brief description |

## Change Details

### Added

- **`path/to/new.ts`** — Description of the new file and its purpose.

### Modified

- **`path/to/file.ts`** — What was changed and why (based on diff context).

### Deleted

- **`path/to/old.ts`** — Why it was removed or what replaced it.

## Git Status

### Staged Changes

{List of staged files from `git diff --cached --name-status`, or "No staged changes."}

### Unstaged Changes

{List of unstaged modifications from `git diff --name-status`, or "No unstaged changes."}

### Untracked Files

{List of untracked files from `git status --porcelain` (lines starting with `??`), or "No untracked files."}

## Session Commits

| Hash | Message | Author | Date |
|------|---------|--------|------|
| `abc1234` | feat: add login flow | Author Name | 2026-02-21 |

{Or "No commits in this session." if no recent commits}

Writing the Report

1. If the parent directory does not exist, create it:

   mkdir -p {parent_directory}
   

2. Use the Write tool to create the report file at the chosen path.
3. If the write fails, report the error and use AskUserQuestion to offer an alternative path.

Present Summary

After writing the report, present a brief summary of what was generated, then use AskUserQuestion:

Report written to {path}.

Summary: {1-2 sentence overview}
Files documented: N | Commits: N | Lines: +N / -N

What would you like to do next?

Options:

1. "Review report" — Read the report back to the user using Read
2. "Commit changes" — Suggest using /git-commit to commit outstanding changes
3. "Done" — End the workflow

---

Error Handling

Scenario	Action
Not a git repo	Stop with clear message (Step 1)
No changes found	Stop with clear message (Step 2)
Individual git command fails	Continue with available data
Write fails	Offer alternative path via AskUserQuestion
Cannot determine scope	Use "session-changes" as the fallback description

Section Guidelines

• Omit empty sections: If a section has no data (e.g., no deleted files, no untracked files), omit that section or subsection entirely rather than showing "None."
• File descriptions: Generate brief descriptions from diff context and file names. Keep each to one sentence.
• Commit hashes: Use short hashes (7 characters) in the report for readability.
• Line counts: Use --stat output to extract per-file line additions/deletions. If unavailable, omit the Lines column.