Change Walkthrough

Generate a detailed, well-formatted markdown walkthrough of code changes with automatic HTML conversion and browser preview.

Workflow

1. Understand What Changes to Review

Ask or determine what changes the user wants documented:

• Uncommitted changes (default): All changes in working directory
• Staged changes: Only changes added to staging area
• Recent commits: Last N commits
• Commit range: Specific range (e.g., "abc123..def456")
• Branch comparison: Diff between branches
• Specific files: Only certain files or directories

If not specified, default to uncommitted changes.

2. Gather Change Information

Based on the scope, run appropriate git commands:

# Uncommitted changes
git diff --stat && git diff

# Staged changes
git diff --staged --stat && git diff --staged

# Last N commits
git log --oneline -n N && git diff HEAD~N..HEAD

# Branch comparison
git diff main..HEAD --stat && git diff main..HEAD

Also gather context by reading changed files to understand the full picture.

3. Generate the Walkthrough Document

Create a comprehensive markdown document:

# Change Walkthrough: {Descriptive Title}

**Date:** YYYY-MM-DD
**Scope:** {uncommitted/staged/commits/etc}
**Total Files:** N files changed (+additions/-deletions)

## Summary

{2-3 sentence overview explaining what changed and why}

## Files Changed

| File | Changes | Description |
|------|---------|-------------|
| `path/to/file.ts` | +15/-3 | Brief description |

## Detailed Walkthrough

### {Feature or Component Name}

#### `path/to/file.ts:10-25`

**What changed:** {Explanation}

\`\`\`typescript
// Code snippet with syntax highlighting
\`\`\`

**Why:** {Reasoning behind this change}

## Testing Notes

- {What should be tested}
- {Potential edge cases}

---
*Generated by change-walkthrough skill*

4. Generate Filename

Create a descriptive filename based on the changes:

1. Extract key terms from files changed or commit messages
2. Format as kebab-case: {action}-{subject}-{YYYY-MM-DD}.md

Examples:

• add-user-authentication-2025-12-22.md
• fix-login-validation-2025-12-22.md
• refactor-database-queries-2025-12-22.md

5. Write the Markdown File

Write the walkthrough to the skill's tmp directory. All generated files should be stored within the skill folder, not in the user's project directory.

The skill's base directory is shown at the top when the skill loads as "Base directory for this skill: ...". Use this path to construct the output location:

{SKILL_BASE_DIR}/tmp/{filename}.md

Write the generated markdown using the absolute path to the skill's tmp directory.

6. Install Dependencies and Convert to HTML

The conversion script requires npm dependencies. Run all commands from the skill's base directory (shown at the top when the skill loads as "Base directory for this skill: ...").

# Change to skill directory and install dependencies (only needed once per cache)
cd {SKILL_BASE_DIR} && npm install

# Convert markdown to HTML (use ABSOLUTE paths for input/output)
node scripts/md-to-html.js {SKILL_BASE_DIR}/tmp/{filename}.md

# Open in default browser
open {SKILL_BASE_DIR}/tmp/{filename}.html

Replace {SKILL_BASE_DIR} with the skill's base directory path. The script accepts absolute paths for the input file and automatically creates the .html file alongside it in the skill's tmp directory.

Report to the user the paths to both files and confirm the browser opened.

Notes

• Use syntax highlighting with language specification in code blocks
• Include file:line references for specific code locations
• Group related changes together in the walkthrough
• For extensive changes, organize by feature rather than by file