Ian-Louw

brew

Use when the user wants a phase driven end-to-end without hand-cranking — "brew the phase", "run the whole loop", "potion brew", or "take this phase to done". Requires the phase's DISCUSSION.md to exist (a human locked the decisions first); without one, run /potion:discuss and stop.

discuss

Use before planning a phase — when the user says "discuss phase", "let's talk through the next phase", or when /potion:plan is requested but no DISCUSSION.md exists for the target phase.

execute

Use when a phase has PLAN files ready to run — when the user says "execute the phase", "potion execute", "run the plans", or after /potion:plan completes. Also use for a quick task or small fix on a Potion project ("quick fix", "small change") via quick mode.

init

Use when starting Potion on a project for the first time — when the user says "potion init", "set up potion", or asks to start a new project with the Potion workflow and no .potion/ directory exists yet.

investigate

Use when a failure's cause is unknown — a bug, a failing test, "why is this broken", "it worked yesterday", a tripped circuit breaker (3 failed fixes), or any moment a fix is about to be attempted without a reproduced root cause.

learn

Use when something non-obvious was discovered the hard way — a pitfall, a project convention, a tool quirk, a user preference — or when the user says "remember this", "log a learning", "what have we learned", "didn't we fix this before?", "same bug again", or "this bit us last time".

pause

Use when stopping mid-phase — when the user says "pause", "checkpoint this", "I need to stop", "switching projects", or a session is ending with uncommitted position. Not needed between phases; STATE.md already covers that.

plan

Use when a phase needs an execution plan — when the user says "plan the phase", "potion plan", or after /potion:discuss completes. Also use with gaps mode when VERIFICATION.md lists unresolved gaps.

resume

Use when returning to a Potion project — when the user says "resume", "where was I", "pick up where we left off", "continue the project", or a session starts in a repo whose .potion/STATE.md shows status paused.

ship

Use when work is ready to leave the branch — when the user says "ship", "potion ship", "create the PR", "get this merged", or "push this up".

verify

Use after executing a phase, or whenever work is about to be declared done — when the user says "verify", "potion verify", "audit the work", "did the agents actually do it", "is the phase actually done", or before shipping anything user-facing.