# 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`:

```text
/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`:

```text
/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.