enhance-prompts

# enhance-prompts

Analyze prompts for clarity, structure, examples, and output reliability.

## Parse Arguments

```javascript
const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
```

## Differentiation from enhance-agent-prompts

| Skill | Focus | Use When |
|-------|-------|----------|
| `enhance-prompts` | Prompt quality (clarity, structure, examples) | General prompts, system prompts, templates |
| `enhance-agent-prompts` | Agent config (frontmatter, tools, model) | Agent files with YAML frontmatter |

## Workflow

1. **Run Analyzer** - Execute the JavaScript analyzer to get findings:
   ```bash
   node -e "const a = require('./lib/enhance/prompt-analyzer.js'); console.log(JSON.stringify(a.analyzeAllPrompts('.'), null, 2));"
   ```
   For a specific path: `a.analyzeAllPrompts('./plugins/enhance')`
   For a single file: `a.analyzePrompt('./path/to/file.md')`

2. **Parse Results** - The analyzer returns JSON with `summary` and `findings`
3. **Filter** - Apply certainty filtering based on --verbose flag
4. **Report** - Format findings as markdown output
5. **Fix** - If --fix flag, apply auto-fixes from findings

The JavaScript analyzer (`lib/enhance/prompt-analyzer.js`) implements all detection patterns including AST-based code validation. The patterns below are reference documentation.

---

## Prompt Engineering Knowledge Reference

### System Prompt Structure

Effective system prompts include: Role/Identity, Capabilities & Constraints, Instruction Priority, Output Format, Behavioral Directives, Examples, Error Handling.

**Minimal Template:**
```xml
<system>
You are [ROLE]. [PURPOSE].
Key constraints: [CONSTRAINTS]
Output format: [FORMAT]
When uncertain: [HANDLING]
</system>
```

### XML Tags (Claude-Specific)

Claude is fine-tuned for XML tags. Use: `<role>`, `<constraints>`, `<output_format>`, `<examples>`, `<instructions>`, `<context>`

```xml
<constraints>
- Maximum response length: 500 words
- Use only Python 3.10+ syntax
</constraints>
```

### Few-Shot Examples

- 2-5 examples is optimal (research-backed)
- Include edge cases and ensure format consistency
- Start zero-shot, add examples only if needed
- Show both good AND bad examples when relevant

### Chain-of-Thought (CoT)

| Use CoT | Don't Use CoT |
|---------|---------------|
| Complex multi-step reasoning | Simple factual questions |
| Math and logic problems | Classification tasks |
| Code debugging | When model has built-in reasoning |

**Key:** Modern models (Claude 4.x, o1/o3) perform CoT internally. "Think step by step" is redundant.

### Role Prompting

**Helps:** Creative tasks, tone/style, roleplay
**Doesn't help:** Accuracy tasks, factual retrieval, complex reasoning

Better: "Approach systematically, showing work" vs "You are an expert"

### Instruction Hierarchy

Priority: System > Developer > User > Retrieved Content

Include explicit priority in prompts with multiple constraint sources.

### Negative Prompting

Positive alternatives are more effective than negatives:

| Less Effective | More Effective |
|----------------|----------------|
| "Don't use markdown" | "Use prose paragraphs" |
| "Don't be vague" | "Use specific language" |

### Structured Output

- Prompt-based: ~35.9% reliability
- Schema enforcement: 100% reliability
- Always provide schema example and validate output

### Context Window Optimization

**Lost-in-the-Middle:** Models weigh beginning and end more heavily.

Place critical constraints at start, examples in middle, error handling at end.

### Extended Thinking

High-level instructions ("Think deeply") outperform step-by-step guidance. "Think step-by-step" is redundant with modern models.

### Anti-Patterns Quick Reference

| Anti-Pattern | Problem | Fix |
|--------------|---------|-----|
| Vague references | "The above code" loses context | Quote specifically |
| Negative-only | "Don't do X" without alternative | State what TO do |
| Aggressive emphasis | "CRITICAL: MUST" | Use normal language |
| Redundant CoT | Wastes tokens | Let model manage |
| Critical info buried | Lost-in-the-middle | Place at start/end |

---

## Detection Patterns

### 1. Clarity Issues (HIGH Certainty)

**Vague Instructions:** "usually", "sometimes", "try to", "if possible", "might", "could"

**Negative-Only Constraints:** "don't", "never", "avoid" without stating what TO do

**Aggressive Emphasis:** Excessive CAPS (CRITICAL, IMPORTANT), multiple !!

### 2. Structure Issues (HIGH/MEDIUM Certainty)

**Missing XML Structure:** Complex prompts (>800 tokens) without XML tags

**Inconsistent Sections:** Mixed heading styles, skipped levels (H1→H3)

**Critical Info Buried:** Important instructions in middle 40%, constraints after examples

### 3. Example Issues (HIGH/MEDIUM Certainty)

**Missing Examples:** Complex tasks without few-shot, format requests without example

**Suboptimal Count:** Only 1 example (optimal: 2-5), more than 7 (bloat)

**Missing Contrast:** No good/bad labeling, no edge cases

### 4. Context Issues (MEDIUM Certainty)

**Missing WHY:** Rules without explanation

**Missing Priority:** Multiple constraint sections without conflict resolution

### 5. Output Format Issues (HIGH/MEDIUM Certainty)

**Missing Format:** Substantial prompts without format specification

**JSON Without Schema:** Requests JSON but no example structure

### 6. Anti-Patterns (HIGH/MEDIUM/LOW Certainty)

**Redundant CoT (HIGH):** "Think step by step" with modern models

**Overly Prescriptive (MEDIUM):** 10+ numbered steps, micro-managing reasoning

**Prompt Bloat (LOW):** Over 2500 tokens, redundant instructions

**Vague References (HIGH):** "The above code", "as mentioned"

---

## Auto-Fix Implementations

### 1. Aggressive Emphasis
Replace CRITICAL→critical, !!→!, remove excessive caps

### 2. Negative-Only to Positive
Suggest positive alternatives for "don't" statements

---

## Output Format

```markdown
## Prompt Analysis: {prompt-name}

**File**: {path}
**Type**: {system|agent|skill|template}
**Token Count**: ~{tokens}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Clarity Issues ({n})
| Issue | Location | Fix | Certainty |

### Structure Issues ({n})
| Issue | Location | Fix | Certainty |

### Example Issues ({n})
| Issue | Location | Fix | Certainty |
```

---

## Pattern Statistics

| Category | Patterns | Auto-Fixable |
|----------|----------|--------------|
| Clarity | 4 | 1 |
| Structure | 4 | 0 |
| Examples | 4 | 0 |
| Context | 2 | 0 |
| Output Format | 3 | 0 |
| Anti-Pattern | 4 | 0 |
| **Total** | **21** | **1** |

---

<examples>
### Example: Vague Instructions

<bad_example>
```markdown
You should usually follow best practices when possible.
```
**Why it's bad**: Vague qualifiers reduce determinism.
</bad_example>

<good_example>
```markdown
Follow these practices:
1. Validate input before processing
2. Handle null/undefined explicitly
```
**Why it's good**: Specific, actionable instructions.
</good_example>

### Example: Negative-Only Constraints

<bad_example>
```markdown
- Don't use vague language
- Never skip validation
```
**Why it's bad**: Only states what NOT to do.
</bad_example>

<good_example>
```markdown
- Use specific, deterministic language
- Always validate input; return structured errors
```
**Why it's good**: Each constraint includes positive action.
</good_example>

### Example: Redundant Chain-of-Thought

<bad_example>
```markdown
Think through this step by step:
1. First, analyze the input
2. Then, identify the key elements
```
**Why it's bad**: Modern models do this internally. Wastes tokens.
</bad_example>

<good_example>
```markdown
Analyze the input carefully before responding.
```
**Why it's good**: High-level guidance without micro-managing.
</good_example>

### Example: Missing Output Format

<bad_example>
```markdown
Respond with a JSON object containing the analysis results.
```
**Why it's bad**: No schema or example.
</bad_example>

<good_example>
```markdown
## Output Format
{"status": "success|error", "findings": [{"severity": "HIGH"}]}
```
**Why it's good**: Concrete schema shows exact structure.
</good_example>

### Example: Critical Info Buried

<bad_example>
```markdown
# Task
[task]
## Background
[500 words...]
## Important Constraints  <- buried at end
```
**Why it's bad**: Lost-in-the-middle effect.
</bad_example>

<good_example>
```markdown
# Task
## Critical Constraints  <- at start
[constraints]
## Background
```
**Why it's good**: Critical info at start where attention is highest.
</good_example>
</examples>

---

## Constraints

- Only apply auto-fixes for HIGH certainty issues
- Preserve original structure and formatting
- Validate against embedded knowledge reference above