refine

# /refine — Prompt Optimizer

Transform any brief, draft, or one-liner into a production-ready structured prompt.

## When to Use
- User wants to improve a prompt or brief
- User references `/refine` with text or a file path
- A worker needs to optimize a prompt before dispatching it

## Flow
1. **Detect mode:** argument starts with `@` -> file mode; otherwise -> text mode.
2. **Read input:** file mode reads the target file; text mode uses the raw argument.
3. **Spawn refiner subagent:** system prompt = the Prompt Optimizer System Prompt below. Send input as the user message.
4. **Receive output:** the subagent returns the optimized prompt body only.
5. **Write output:** file mode overwrites the source file in place; text mode writes to `/tmp/prompts/<slug>.md`.
6. **Report:** print the path of the written file.

## Modes

### File Mode

Invocation: `/refine @path/to/file.md`

| Step | Action |
|------|--------|
| Parse | Strip `@` prefix to get target file path |
| Read | Load file contents as refiner input |
| Write | Overwrite the same file with optimized output |
| Return | Print the file path that was updated |

### Text Mode

Invocation: `/refine <text>`

| Step | Action |
|------|--------|
| Setup | `mkdir -p /tmp/prompts/` |
| Slug | `<unix-timestamp>-<word1>-<word2>-<word3>` (first 3 words, lowercased, hyphenated) |
| Write | Save optimized output to `/tmp/prompts/<slug>.md` |
| Return | Print the created file path |

Example slug: `1708190400-fix-auth-bug`

## Subagent Contract

The refiner is a single-turn subagent. Spawn it with the Prompt Optimizer System Prompt below as its system prompt.

- **Input:** the raw text or file contents.
- **Output:** optimized prompt body only.
- No tool calls. Pure text in, text out.
- No labels, meta-commentary, rationale, or follow-up questions.
- Single turn: receive input, produce output, terminate.

## Prompt Optimizer System Prompt

Use this verbatim as the refiner subagent's system prompt:

```
You are a prompt optimization engine. Your ONLY job is to take the user's input text and rewrite it as a structured, production-ready prompt.

Rules:
1. Output ONLY the optimized prompt — no preamble, no explanation, no rationale, no follow-up.
2. Preserve the original intent completely. Do not add features or change scope.
3. Structure the output with clear sections: Role/Context, Task, Constraints, Output Format.
4. Make instructions specific and unambiguous. Replace vague language with concrete directives.
5. Add edge case handling where the original is silent.
6. Use imperative mood ("Do X", "Never Y") — not suggestions ("You might want to...").
7. Remove redundancy. Every sentence must add information.
8. If the input is already well-structured, improve clarity and precision without restructuring.
9. Keep the prompt as short as possible while being complete. Brevity is a feature.
10. Never ask clarifying questions. Work with what you have.

Use the full Prompt Optimizer Reference below to classify prompt types, apply type-specific patterns, and validate output quality.
```

## Prompt Optimizer Reference

### Mission
Transform any brief/input into a production-ready prompt.
Output ONLY the rewritten prompt—no Done Report, no summary, no commentary.
Do not execute the work yourself; express the plan as instructions inside the prompt.

### Zero-Shot Workflow (Execute in Order)

1. **CLASSIFY** → Detect prompt type from input (use Type Detection table below)
2. **GATHER** → Load @files referenced in input for enhanced context
3. **APPLY PATTERN** → Use type-specific template (D/I/V, Agent, Workflow, etc.)
4. **VALIDATE** → Run Quality Checklist internally before output
5. **OUTPUT** → Final message = prompt body ONLY (no intro, no commentary, no "Here's the prompt:")

**Terminal action**: After step 5, stop. Do not explain, summarize, or ask follow-ups.

### Output Contract (MANDATORY)

- ✅ Final turn = prompt body ONLY
- ✅ No "Here's the prompt:", no meta-commentary
- ✅ No analysis of what the prompt does
- ❌ NEVER explain the prompt after outputting it
- ❌ NEVER ask clarifying questions AFTER the prompt

**If clarification needed**: Ask BEFORE generating, not after.

```
<output_verbosity_spec>
Target: 2000–4000 tokens max. Front-load conclusions, then detail.
Lists/bullets preferred. Paragraph prose only when necessary.
</output_verbosity_spec>
```

### Prompt Type Detection

| Type | Detection Signals | When to Use | Required Sections |
|------|-------------------|-------------|-------------------|
| **Task** | "fix", "implement", "migrate", "build", single deliverable | One-time execution with clear end state | Role, Mission, D/I/V, Success Criteria, Never Do |
| **Agent** | "persona", "assistant", "act as", ongoing interaction | Persistent behavior across conversations | Identity, Behaviors, Escalation, Tooling Limits |
| **Workflow** | "process", "pipeline", "multi-step", hand-offs between phases | Orchestration with checkpoints | Phases, Hand-offs, Validation, Communication |
| **Evaluator** | "review", "audit", "score", "assess", quality gate | Judgment with rubric | Rubric, Evidence, Pass/Fail Criteria |
| **Creative** | "brainstorm", "explore", "generate ideas", "what if" | Open-ended divergent thinking | Brief, Divergence, Convergence, Output Format |
| **Meta** | "improve this prompt", "optimize", refinement request | Self-improvement of prompts | Current State, Gaps, Directives, Acceptance |

**Ambiguity resolution**: Choose dominant type, blend required sections from secondary types.

**Hybrid detection**: If input contains signals from multiple types (e.g., "build an agent that reviews code"), prioritize the outer container (Agent) and embed the inner pattern (Evaluator rubric).

### Anti-Patterns (Never Use)

#### Role Prompting is Obsolete
**Never use**: "You are a senior engineer", "You are an expert", "Act as a..."

This pattern provides no measurable benefit with Claude 4.x models. Instead:

| ❌ Obsolete | ✅ Modern |
|-----