glimpse-changes

Glimpse Changes

Render a Markdown walkthrough in a native Glimpse window with syntax-highlighted code and rich diff rendering.

Setup

npx [email protected] --help

How to write a useful walkthrough

Use Glimpse to walk another developer through the code in the clearest order, not necessarily the order files appear in the diff.

Aim for a short, reviewable document:

1. Start with a specific title.
2. Add a brief summary of what changed.
3. Choose the walkthrough order that best explains the work.
4. Use prose between focused changes or diff blocks to explain intent, tradeoffs, and review risks.

Prefer a narrative that follows the user or developer flow: what someone sees or does, how the request/state/data moves through the system, then any supporting helpers, tests, docs, or cleanup. If another order is clearer, use that instead.

Write like a developer walking another developer through the change. Be direct and specific. Avoid dumping one large diff with a generic explanation. Prefer smaller, focused sections when they help the reader understand the code.

Good explanation style:

• "To keep the review focused on selected files, pass the filter through the renderer."
• "Add a fallback label so empty reviews still have a useful title."
• "The parser now keeps deleted files in the walkthrough so reviewers can see removals in context."

Template:

# <Title>

## Summary

- <User-visible or developer-visible effect>
- <Main code path changed>
- <Important review note, risk, or edge case>

## <First thing a reviewer should understand>

Explain the intent and what to look for.

```changes
path/to/relevant-file.ts:20-70
```

## <Next part of the flow>

Explain how this connects to the previous step.

```changes
path/to/another-file.ts:80-130
```

## <Supporting detail, test, or edge case>

Explain why this support code matters.

```changes
path/to/test-file.test.ts:50-100
```

Example:

cat <<'EOF' | npx [email protected] -
# Improve review flow messaging

## Summary
- make the default review flow easier for agents to follow
- document when to wait for the user versus using background mode
- keep the walkthrough focused on the interaction reviewers care about

## Open the review and wait for the user

To make review sessions easier to follow, tell agents to open Glimpse, ask the
user to inspect it, and wait until the user says they are done.

```changes
packages/glimpse-changes/skills/glimpse-changes/SKILL.md:120-145
```
EOF