Prompt Quality

# Prompt quality guide

This document describes what the pi-prompt-gen enhancer produces, what it
never does, how its two modes differ, how browse-context data is handled, and
how to maintain the system prompt fixtures and tests.

The audience is anyone contributing to pi-prompt-gen or diagnosing prompt
quality issues from repo-local information.

---

## What the enhancer does

The enhancer (`src/enhancer-prompt.ts`) produces a system prompt + one user
message for an LLM call. That LLM call generates a **polished prompt for
another agent to execute**. Every system prompt includes guardrails that keep
the model in prompt-shaping mode:

| Guardrail       | Purpose                                                      |
|-----------------|--------------------------------------------------------------|
| SCOPE LOCK      | Preserve original intent — do not broaden, narrow, or shift  |
| CHANGE BUDGET   | Keep output as concise as the input allows                   |
| Role framing    | Your only job is to produce a prompt — not implement         |
| ANTI_DEBUG      | Never debug, investigate root causes, or solve the task      |
| ANTI_ESSAY      | Strip preamble, meta-commentary, explanations                |
| OUTPUT_CONTRACT | Return a single self-contained prompt, ≤~20 lines            |
| Verification    | Include lightweight acceptance checks for impl-like prompts  |
| TASK SHAPE      | Compact Goal/Context/Constraints/Verification sections are   |
|                 | allowed when they add clarity, never required                |

## What the enhancer never does

- **Implements** code, runs commands, or writes files.
- **Debugs** the underlying issue or investigates root causes.
- **Writes essays** or meta-commentary about how the prompt was produced.
- **Solves** the task described in the input. The output is always a prompt for
  another agent, not a solution.
- **Broadens scope** — it preserves the original ask exactly. If the input is
  vague, the output sharpens without expanding.
- **Embeds raw user input into the system prompt** — the system prompt is a
  role/constraints document; raw input stays in the user message.

## Modes

### Rewrite

Improve a prompt that already expresses a coherent ask but needs clarification,
structure, or polish. The core intent stays identical.

### Generate

Turn a rough idea, vague bug report, or open-ended request into a well-shaped
prompt. The mode builds a prompt from near-scratch while preserving the
original intent.

### Good/bad examples

#### Rewrite — good