Skip to main content
Promptster captures not just what you built, but why you built it that way. Explaining your decisions is one of the highest-signal parts of the assessment — reviewers read your reasoning alongside the code and the session timeline, and a clear “why” often matters more than the diff itself. There is no automatic mind-reading here. Decisions are captured because you record them, in your own words, with /explain or promptster explain.

​
The fastest way: /explain in Claude Code

When you start your session, Promptster installs an /explain slash command into your workspace. Inside Claude Code, just type it with your reasoning:
Your note is captured to the backend as a decision on your session record. Claude acknowledges it in one line and does not treat it as an instruction — it’s a note for your reviewer, not a new prompt for the model.
The /explain command always triggers a brief model turn (Claude Code has no silent passthrough). If you want a capture path that doesn’t touch your conversation at all, use promptster explain in a separate terminal — see below.

​
From the terminal: promptster explain

Run it from any terminal inside your workspace. With no argument it opens an interactive editor; with an argument it captures inline.
The CLI first shows a summary of your recent activity (files changed, commands run) for context, then captures your reasoning:
Press Ctrl+D to submit or Esc to cancel. Use --last <duration> (default 20m, up to 60m) to widen the activity window if you’ve been heads-down for a while.

​
The nudge

You don’t have to remember to do this constantly — Promptster reminds you. After you’ve changed a meaningful chunk of code (~3+ files) without explaining anything recently, the CLI surfaces a gentle nudge to run /explain. Inside Claude Code it appears as a system message on your next prompt; in Cursor or a terminal it prints to stderr. The nudge is deliberately restrained: it waits for real work to accumulate, won’t fire twice in a row (a ~10-minute cooldown), holds off right after you’ve just explained something, and caps at a few times per session. It’s a prompt, not a gate — ignore it freely.

​
What makes a good decision note

Aim for the reasoning, not a changelog. The diff already shows what changed.

Strong

“Went with optimistic locking instead of a DB transaction lock — the contention here is rare and a transaction would serialize every write. Trade-off: a retry on conflict, which the client already handles.”

Weak

“Updated the webhook handler and added a test.”
Good notes name the options you considered, the one you chose, and the trade-off you accepted. You don’t need to document every line — focus on the choices where you actually weighed alternatives.

​
Before you submit

promptster done checks for decision notes you started but left empty. If any exist, it stops:
Run promptster explain to fill them in, then promptster done again — or promptster done --auto to submit without the check.
Quality over quantity. Three sharp decision notes beat fifteen “added a function” notes. Reviewers are looking for judgment, not volume.