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 Tracker as Checkpoint Tracker
    participant AI as PostQode AI

    User->>VSCode: Run /explain-changes
    VSCode->>Tracker: Fetch diff between checkpoints
    Tracker-->>VSCode: Return list of changed files
    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. Checkpoint Analysis: PostQode retrieves the differences from the underlying Checkpoint Tracker, comparing your codebase state before the task started (or since the last task completion) to the current state.
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 up to that checkpoint.

---

Prerequisites

To use /explain-changes, the following must be true:

• VS Code Environment: This command relies on VS Code's editor APIs and comment controllers.
• Checkpoints Enabled: Checkpoints must be toggled on in your extension settings (enableCheckpoints: true). If they are disabled, the review cannot be performed.
• Active Task: You must run the command within an active task session containing checkpoints.

---

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.