Document Changes

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

Accept the following inputs:

• 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 inputs include a scope: Convert to kebab-case (e.g., "auth refactor" -> auth-refactor)
• If no scope 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

Prompt the user:

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": Prompt the user for the full file path.

3.3 Validate Path

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

  mkdir -p {parent_directory}
  

Step 4: Generate and Write Report

Build the markdown report with the following structure, then write it to the chosen path.

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 inputs, 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, or "No staged changes."}

### Unstaged Changes

{List of unstaged modifications, or "No unstaged changes."}

### Untracked Files

{List of untracked files, 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. Write the report file at the chosen path.
3. If the write fails, report the error and prompt the user to offer an alternative path.

Present Summary

After writing the report, present a brief summary of what was generated, then prompt the user:

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
2. "Commit changes" -- Suggest committing outstanding changes
3. "Done" -- End the workflow

Error Handling

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.

Integration Notes

What this component does: Generates a structured markdown report documenting all codebase changes from a working session, including files changed, commit history, git status, and human-readable descriptions.

Capabilities needed:

• File read/write operations
• Shell command execution (git commands, mkdir, date)
• User interaction (prompts for report location)
• Search for files matching patterns (optional, for path validation)

Adaptation guidance:

• This skill is entirely git-based -- it requires a git repository to function
• The report template can be customized by modifying the template in Step 4
• The recommended output path (internal/reports/) is a convention that can be changed
• Works independently with no external skill or agent dependencies

Configurable parameters: None