explain-changes-mental-model

Mental Model Builder

Analyze code changes and present them as a coherent mental model - breaking large diffs into logical chunks ordered by dependency so they can be understood incrementally.

What This Command Does

1. Gather changes from the specified source (commit, branch, range, or custom input)
2. Analyze and categorize changes into logical groups by theme/purpose
3. Identify dependencies between change groups
4. Present ordered explanation so changes can be reviewed in a sensible sequence

Usage

# Current working changes (staged + unstaged)
/mental-model

# Specific commit
/mental-model abc1234
/mental-model HEAD~3

# Branch comparison (vs main)
/mental-model feature/my-branch

# Explicit range
/mental-model main..HEAD
/mental-model origin/main...HEAD

# Custom - user will provide diff/changes in next message
/mental-model custom

Implementation Steps

When this command is invoked:

1. Determine Change Source

Parse the argument to determine what changes to analyze:

No argument provided:

• Run git diff HEAD to get all uncommitted changes (staged + unstaged)
• If no changes found, report "No uncommitted changes to analyze"

Argument looks like a commit hash (7-40 hex chars):

• Run git show <hash> --stat first to verify it exists
• Run git show <hash> to get the full diff

Argument looks like a branch name (contains letters, no ..):

• Detect main branch: check if main or master exists
• Run git diff <main-branch>...<argument> to compare

Argument contains .. (explicit range):

• Use as-is: git diff <argument>

Argument is "custom":

• Tell the user: "Please paste or describe the changes you want me to analyze in your next message."
• Wait for user input before proceeding

2. Extract the Diff

Run the appropriate git command and capture the output:

# Example for commit
git show <hash> --no-color

# Example for range
git diff <range> --no-color

If the diff is very large (>5000 lines), use --stat first to get an overview, then selectively read the most important files.