Explain Changes Command

The /explain-changes command is a VS Code-only slash command designed to help you review and understand the code changes made by the AI.

Instead of forcing you to read through raw diffs, this command analyzes the changes, opens VS Code's native diff view, and streams real-time, inline AI comments explaining exactly what changed, why it changed, and any potential side effects.

---

How It Works

sequenceDiagram
    participant User
    participant VSCode as VS Code UI
    participant Git as Git Working Tree
    participant AI as PostQode AI

    User->>VSCode: Run /explain-changes
    VSCode->>Git: Compare folder changes using git diff
    Git-->>VSCode: Return changed files and unified diff
    VSCode->>VSCode: Open Diff View immediately
    VSCode->>AI: Request explanation of diff
    AI-->>VSCode: Stream inline comments in real-time
    VSCode->>User: Display inline comments on diff lines

1. Git Diff Comparison: PostQode evaluates modified files by executing git diff against your working tree, detecting the exact additions, deletions, and refactored sections in the workspace folder.
2. Immediate Diff View: VS Code opens the file diff view immediately so you can see the visual file comparison.
3. Real-time Comment Streaming: As the AI analyzes the diff content against the conversation history, it generates explanations. These explanations are streamed directly into the diff view as inline code comments.
4. Multi-file Flow:
   • If 2 or fewer files were changed, the diff view opens immediately and comments stream in-place.
   • If 3 or more files were changed, PostQode will cycle through the files to show comments as they are written, opening the comprehensive multi-file diff view once complete.

---

How to Run

There are two ways to invoke this capability:

1. Via Chat Command

Type the slash command directly in the chat window:

/explain-changes

2. Via UI Buttons

You can click the Explain changes button in the chat row of a completed execution step to explain changes.

---

Prerequisites & Required Staging (git add .)

Staging Files Required (git add .)

The /explain-changes tool operates by inspecting repository changes via git diff. VS Code cannot construct the diff comparison view for untracked or unstaged files without them being staged first.

Always run git add . in your terminal (or click the "+" Stage All Changes button in the VS Code Source Control panel) before running /explain-changes.

To use /explain-changes, ensure:

• VS Code Environment: This command relies on VS Code's editor APIs and comment controllers.
• Staged Changes: Run git add . so that the underlying git diff engine can compare the workspace state and build the side-by-side diff tabs.
• Active Task: You can run the command within an active task session or after an AI code generation step to inspect modifications.

---

Best Practices

• Review before committing: Always run /explain-changes after a complex AI modification to see a plain-English explanation of the edits directly alongside the code lines.
• Use inline replies: Once comments are added to your editor, you can reply directly to the comments to ask PostQode for further refinements or explanations about that specific block of code.