76 lines
6.4 KiB
Markdown
76 lines
6.4 KiB
Markdown
# 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.
|