dotfiles/pi/.pi/agent/prompts/Doc/prompts.md

Prompts

Slash-style prompts for the interactive pi session. Each file is a p-<verb>.md template with a frontmatter description + argument-hint and a structured body. Invoke with :p-<verb> [arg] or via the :prompts TUI picker.

When to use which

Prompt	Use it when…	Pairs well with
p-plan	You're about to start a non-trivial change and want a structured plan before coding.	p-brainstorm (first), then p-refactor / p-test
p-brainstorm	You have a problem but no chosen approach yet; want 3–5 alternatives with trade-offs.	p-plan (after picking one)
p-explain	You don't understand a piece of code, a concept, or an error message.	p-debug / p-diagnose (if it's a problem)
p-debug	A test, build, or command is failing with a clear error. You have the error in hand.	p-test (add a regression test after the fix)
p-diagnose	Nothing is "failing" but behavior is wrong — wrong values, races, perf drift, "passes locally, broken in prod."	p-debug (if you find a hard failure)
p-review	You want a code review of a diff, file, or staged change. General quality feedback.	p-secaudit (security subset)
p-secaudit	Touching auth, input handling, secrets, network, deserialization, or any trust boundary.	p-review (broader quality), p-test
p-refactor	Restructuring code without changing behavior. Safety-first, mechanical steps.	p-test (first, as the safety net), p-review (after)
p-test	You need to write or expand tests for existing or new code.	p-debug (after a failure), p-refactor (before)
p-doc	Writing or improving README, docstrings, JSDoc, godoc, or ADRs.	p-summarize (skim the code first)
p-commit	About to commit. You want a conventional message and (optionally) a PR description.	p-review (final check before committing)
p-summarize	A file, log, diff, or document is too long to read in full. You need the gist + key details.	p-plan / p-debug (then dive into specifics)

Decision flow

Got an idea or vague problem?
└─ Yes → p-brainstorm  →  pick an approach  →  p-plan  →  implement
                                                          └─ p-test  →  p-commit
Touching existing code that needs to change?
└─ p-refactor (after p-test confirms a safety net)  →  p-review  →  p-commit
Something is broken?
├─ Hard failure (error message, failing test)  →  p-debug
└─ Soft failure (wrong output, race, perf)      →  p-diagnose
                                       →  fix  →  p-test (regression)  →  p-commit
Touching a trust boundary, auth, secrets, or untrusted input?
└─ p-secaudit  (then p-review for general quality)
Need to understand a long file/log/diff quickly?
└─ p-summarize
Need to write or update docs?
└─ p-doc
Don't know what something does or what an error means?
└─ p-explain

Chain recipes

The c-* files are not prompts you run directly in the editor. They are orchestration recipes that run a sequence of p-* prompts through the pi-subagents prompt-workflow adapter. Each p-* step is executed as a forked-context subagent, so later steps can see earlier outputs. Chains run in the foreground by default (stop with Esc/Ctrl+C); add --bg to detach them.

Recipe	Sequence	Use it when…
c-design-build	p-brainstorm → p-plan → p-test → p-commit	You want to design a feature, plan it, add tests, and commit in one go.
c-fix-commit	p-summarize → p-diagnose → p-debug → p-test	You need to understand a bug, diagnose it, fix it, and add regression tests.
c-refactor-commit	p-refactor → p-test → p-review → p-commit	You want a safe refactor with tests, review, and a commit.
c-security-loop	p-secaudit → p-review → p-test	You need a security-first review plus tests before proceeding.

Invoke a chain with /prompt-workflow, not /c-recipe:

/prompt-workflow c-design-build "add a rate-limiter to the API"
/prompt-workflow c-fix-commit "the checkout intermittently times out"
/prompt-workflow c-refactor-commit "src/utils.ts"
/prompt-workflow c-security-loop "auth endpoint"

Add --bg to run detached; then watch with /subagents-fleet, stop with /subagents-stop <id>, or check status with subagent({ action: "status" }). To let the agent pick the chain for you, use /run workflow-router "<task>". If you want to run the same sequence ad-hoc, use /chain-prompts:

/chain-prompts p-brainstorm -> p-plan -> p-test -> p-commit -- "add a rate-limiter"

Conventions

• Every prompt uses $@ for the user-supplied argument. Pass an argument at invocation time; if the request is under-specified, the prompt will ask clarifying questions.
• Output is structured (numbered sections, fixed categories) so the result is diff-friendly and skim-friendly.
• Prompts intentionally do not overlap with subagent workflows (agents/, chains/, skills/) — those are for orchestration; these are for interactive turns.
• Prefer one prompt per turn. Chain them yourself (p-brainstorm → p-plan → p-refactor) rather than asking one prompt to do everything.