# Prompts Directory

This directory contains reusable prompt templates used by diffray agents.

## Overview

Prompts are markdown files that define specialized instructions for code review agents. They can be:
- **Automatically included** (like `output-format.md` which is added to all agents)
- **Referenced by agents** (agents can include prompts in their system prompts)
- **Used as templates** (for creating new agents)

## Available Prompts

### Core Prompts

#### `output-format.md`
**Status**: Automatically included in all agents  
**Purpose**: Defines the JSON format for agent output

This prompt is automatically loaded and appended to every agent's system prompt via `loadOutputFormat()` in `executors/utils.ts`. It ensures all agents return issues in a consistent format:

```json
{
  "file": "path/to/file.ts",
  "lineStart": 10,
  "lineEnd": 15,
  "severity": "critical|high|medium|low",
  "category": "security|performance|bug|quality|style|docs",
  "shortDescription": "Brief description",
  "fullDescription": "Detailed description",
  "suggestion": "How to fix (optional)"
}
```

#### `validation.md`
**Status**: Used by validation agent  
**Purpose**: Instructions for filtering false positives

Used by the `validation` stage agent to validate issues found by other agents. Focuses on:
- Verifying issues against actual source code
- Filtering false positives and noise
- Recognizing intentional trade-offs

### Specialized Prompts

These prompts provide detailed instructions for specific code review domains:

#### `i18n.md`
Internationalization review:
- Hardcoded strings
- Missing translation keys
- Locale format issues
- RTL (right-to-left) support

#### `database.md`
Database and ORM review:
- N+1 query problems
- Missing indexes
- Migration safety
- Query performance
- Deadlock risks

#### `api-design.md`
API design review:
- HTTP method usage
- Naming conventions
- Error response formats
- Pagination
- Versioning

#### `observability.md`
Observability review:
- Missing logging
- Unstructured logging
- Missing metrics
- Error tracking
- Distributed tracing

#### `data-privacy.md`
Data privacy and compliance review:
- PII exposure
- Missing consent checks
- Data retention
- Encryption and storage
- GDPR/CCPA compliance

## How Prompts Are Used

### Automatic Inclusion

The `output-format.md` prompt is automatically added to all agents:

```typescript
// In executors/utils.ts
const format = await loadOutputFormat();
const fullPrompt = buildPrompt(systemPrompt, input, format);
```

### Manual Inclusion

Agents can reference prompts in their markdown files. For example, an agent could include:

```markdown
---
name: my-agent
description: My custom agent
---

You are a code reviewer.

<!-- Include specialized prompt -->
See ../prompts/database.md for database review guidelines.

Focus on:
- Database queries
- Index usage
...
```

### Creating New Prompts

1. **Create the prompt file** in `src/defaults/prompts/`:
   ```bash
   touch src/defaults/prompts/my-prompt.md
   ```

2. **Write the prompt content**:
   ```markdown
   # My Specialized Prompt
   
   You are reviewing code for...
   
   ## Focus Areas
   - Area 1
   - Area 2
   
   ## Instructions
   - Be specific
   - Provide examples
   ```

3. **Reference in agents** (optional):
   ```markdown
   ---
   name: my-agent
   ---
   
   See ../prompts/my-prompt.md for guidelines.
   ```

## Prompt Structure

A good prompt should include:

1. **Mission Statement**: What the agent should focus on
2. **Focus Areas**: Specific areas to review
3. **Quality Standards**: What to flag and what to skip
4. **Instructions**: How to report issues
5. **Examples**: Concrete examples of issues to report

## Best Practices

- **Be specific**: Vague instructions lead to inconsistent results
- **Provide examples**: Show what to flag and what to skip
- **Focus on impact**: Only flag issues with real consequences
- **Keep it concise**: Long prompts can confuse the model
- **Update regularly**: Refine prompts based on real-world usage

## Related Files

- **Agents**: `src/defaults/agents/` - Agents that use these prompts
- **Executors**: `src/executors/utils.ts` - Code that loads prompts
- **Documentation**: `docs/AGENTS.md` - Agent configuration guide