tendril/docs/PROMPTS/Prompt-Creation-Guide.md

# Prompt Creation Guide

**Purpose**: Guide for creating effective, reusable prompt documents for AI-assisted workflows in the Tendril project.

**Last Updated**: 2025-11-11

---

## Overview

This guide provides step-by-step instructions for creating prompt documents that enable consistent, reliable AI-assisted workflows. Prompt documents are reusable instructions that can be dragged into Cursor chat sessions to accomplish specific tasks.

**Key Principles**:
- **Clarity**: Instructions must be unambiguous
- **Completeness**: All required information must be specified
- **Reusability**: Prompts should work for similar tasks
- **Validation**: Include checklists to verify completion

---

## Naming Convention

### Format

Prompt documents must follow this naming pattern:
```
NN-Descriptive-Name-Prompt.md
```

Where:
- **`NN`** is a zero-padded two-digit number (00, 01, 02, etc.)
- **`Descriptive-Name`** uses kebab-case (lowercase with hyphens)
- Always ends with **`-Prompt.md`**

### Examples

- `00-Project-Status-Check-Prompt.md`
- `01-KB-Content-Search-Prompt.md`
- `02-Phase-Documentation-Sync-Prompt.md`
- `10-Create-New-Phase-Prompt.md`
- `20-Update-KB-Entry-Prompt.md`

### Numbering Strategy

- **00-09**: Core system prompts (status checks, searches, syncs)
- **10-19**: Phase management prompts
- **20-29**: KB system prompts
- **30-39**: Workflow and automation prompts
- **40-49**: Documentation prompts
- **50+**: Project-specific prompts

---

## Prompt Structure Template

Every prompt document must include these sections in order:

### 1. Title and Purpose

```markdown
# [Task Name] Prompt

**Purpose:** [One sentence describing what this prompt accomplishes]

**How to Use:** Drag this entire document into a Cursor chat session, then [provide context/information]. The AI assistant will follow these instructions to [accomplish the task].
```

### 2. CRITICAL: Information Gathering

```markdown
## CRITICAL: Information Gathering

### Required Information (You should provide this)

Before starting, **ASK THE USER** for the following information if not already provided:

1. **[Information Item 1]** (REQUIRED)
   - Format/constraints
   - Examples
   - Why it's needed

2. **[Information Item 2]** (REQUIRED)
   - Format/constraints
   - Examples
   - Why it's needed

### If Information is Missing

**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about:
- [List of things not to assume]
```

### 3. Step-by-Step Process

```markdown
## Step-by-Step Process

### Phase 1: [Phase Name]

[Description of what this phase accomplishes]

1. **Step description:**
   ```bash
   # Commands or code
   ```

2. **Validation:**
   - How to verify this step succeeded
   - What to check

### Phase 2: [Phase Name]

[Description of what this phase accomplishes]

1. **Step description:**
   [Instructions]

2. **Validation:**
   - How to verify this step succeeded
   - What to check
```

### 4. Error Handling

```markdown
## Error Handling

### Common Issues

#### [Issue Name]
- **Error message**: What you'll see
- **Fix**: How to resolve it
- **Prevention**: How to avoid it

#### [Another Issue]
- **Error message**: What you'll see
- **Fix**: How to resolve it
- **Prevention**: How to avoid it
```

### 5. Validation Checklist

```markdown
## Validation Checklist

Before completing, verify:

- [ ] [Checklist item 1]
- [ ] [Checklist item 2]
- [ ] [Checklist item 3]
- [ ] ...
```

### 6. Important Notes for AI Assistant

```markdown
## Important Notes for AI Assistant

1. **[Critical instruction 1]**
2. **[Critical instruction 2]**
3. **[Critical instruction 3]**
4. ...
```

---

## Best Practices

### Writing Effective Instructions

1. **Be Specific**
   - Use exact commands and paths
   - Specify file names and locations
   - Include expected outputs

2. **Be Complete**
   - Include all necessary steps
   - Don't assume prior knowledge
   - Provide context for each step

3. **Be Clear**
   - Use simple, direct language
   - Avoid ambiguity
   - Use examples where helpful

4. **Be Structured**
   - Organize steps logically
   - Group related steps into phases
   - Number steps sequentially

5. **Be Validated**
   - Include validation for each step
   - Provide completion checklist
   - Specify success criteria

### Information Gathering

1. **List All Requirements**
   - Don't assume any information
   - Be explicit about what's needed
   - Provide format examples

2. **Explain Why**
   - Help users understand why information is needed
   - Provide context for requirements
   - Show how information will be used

3. **Provide Examples**
   - Give sample values
   - Show format requirements
   - Include valid/invalid examples

### Error Handling

1. **Anticipate Common Errors**
   - Think about what could go wrong
   - Document likely errors
   - Provide clear fixes

2. **Include Prevention**
   - Explain how to avoid errors
   - Provide best practices
   - Note common pitfalls

3. **Provide Clear Fixes**
   - Step-by-step error resolution
   - Explain what each fix does
   - Verify fix effectiveness

---

## Writing Effective Instructions

### Command Instructions

When providing commands:

```markdown
1. **Run the command:**
   ```bash
   git status
   ```

2. **Verify output:**
   - Should show list of modified files
   - Should indicate current branch
   - Should show no uncommitted changes (if clean)
```

### File Operations

When working with files:

```markdown
1. **Read the file:**
   - Path: `tendril/phases/phase-01-name/blueprint.md`
   - Extract: Project name, status, deliverables

2. **Update the file:**
   - Modify: Status field
   - Add: New deliverable entry
   - Verify: Format is correct
```

### Multi-Step Processes

When breaking down complex tasks:

```markdown
### Phase 1: Preparation

1. **Gather information:**
   - [What to gather]
   - [Where to find it]
   - [How to verify it]

2. **Validate prerequisites:**
   - [Check 1]
   - [Check 2]
   - [Check 3]

### Phase 2: Execution

1. **Perform action:**
   - [Step 1]
   - [Step 2]
   - [Step 3]

2. **Verify results:**
   - [Verification 1]
   - [Verification 2]
```

---

## Testing Your Prompt

### Test Process

1. **Create the prompt document**
   - Follow the structure template
   - Include all required sections
   - Customize for your task

2. **Test with a simple case**
   - Use minimal, clear inputs
   - Verify all steps work
   - Check validation checklist

3. **Test with edge cases**
   - Missing information
   - Invalid inputs
   - Error conditions

4. **Refine based on results**
   - Add missing steps
   - Clarify ambiguous instructions
   - Improve error handling

### Testing Checklist

- [ ] Prompt executes successfully with valid inputs
- [ ] Prompt handles missing information correctly
- [ ] Prompt provides clear error messages
- [ ] Validation checklist is complete
- [ ] All steps are clear and unambiguous
- [ ] Examples are helpful and accurate

---

## Common Patterns

### Status Check Pattern

```markdown
# [System] Status Check Prompt

**Purpose:** Check current status of [system/component]

## Step-by-Step Process

### Phase 1: Gather Current State
1. Read [status file]
2. Extract [status indicators]
3. List [current items]

### Phase 2: Analyze Status
1. Compare with [baseline/expected]
2. Identify [issues/discrepancies]
3. Summarize findings

### Phase 3: Report
1. Present status summary
2. Highlight issues
3. Suggest next steps
```

### Search Pattern

```markdown
# Search [Content Type] Prompt

**Purpose:** Search [system] for [content type] matching [criteria]

## CRITICAL: Information Gathering

1. **Search criteria** (REQUIRED)
   - Format: [format]
   - Examples: [examples]

## Step-by-Step Process

### Phase 1: Prepare Search
1. Read [index/reference]
2. Identify [search targets]
3. Prepare [search parameters]

### Phase 2: Execute Search
1. Search by [method 1]
2. Search by [method 2]
3. Combine results

### Phase 3: Present Results
1. List matches
2. Summarize findings
3. Provide references
```

### Sync Pattern

```markdown
# Synchronize [Documents] Prompt

**Purpose:** Ensure [documents] are synchronized and consistent

## Step-by-Step Process

### Phase 1: Read All Documents
1. Read [document 1]
2. Read [document 2]
3. Read [document 3]

### Phase 2: Compare and Identify Discrepancies
1. Compare [field 1] across documents
2. Compare [field 2] across documents
3. List all discrepancies

### Phase 3: Update Documents
1. Update [document 1] with [changes]
2. Update [document 2] with [changes]
3. Verify consistency
```

---

## When to Create a New Prompt

### Create a Prompt When:

1. **Task is Repetitive**
   - You find yourself doing the same task multiple times
   - Task has clear, repeatable steps
   - Task would benefit from standardization

2. **Task is Complex**
   - Task involves multiple phases
   - Task requires specific information gathering
   - Task has validation requirements

3. **Task Needs Consistency**
   - Different people perform the task
   - Task must follow specific rules
   - Task has quality requirements

4. **Task Has Common Errors**
   - Task frequently encounters errors
   - Errors have known solutions
   - Error handling would be helpful

### Don't Create a Prompt When:

1. **Task is One-Time**
   - Task will only be done once
   - Task is highly specific
   - Task doesn't need standardization

2. **Task is Too Simple**
   - Task is a single command
   - Task requires no validation
   - Task has no error handling needs

3. **Task is Too Variable**
   - Task changes significantly each time
   - Task has no clear pattern
   - Task can't be standardized

---

## Updating Existing Prompts

### When to Update

1. **Process Changes**
   - Workflow has changed
   - New steps are required
   - Steps are no longer needed

2. **Error Discovery**
   - New common errors found
   - Existing fixes don't work
   - Prevention methods needed

3. **Clarity Improvements**
   - Instructions are ambiguous
   - Examples are unclear
   - Validation is incomplete

### Update Process

1. **Test Current Prompt**
   - Verify it still works
   - Identify issues
   - Note improvements needed

2. **Make Updates**
   - Update affected sections
   - Maintain structure
   - Preserve working parts

3. **Test Updated Prompt**
   - Verify updates work
   - Check all sections
   - Validate completeness

4. **Document Changes**
   - Note what changed
   - Explain why
   - Update version/date if applicable

---

## Checklist for New Prompts

Before considering a prompt complete, verify:

### Structure
- [ ] Title follows naming convention
- [ ] Purpose is clear and concise
- [ ] "How to Use" section is present
- [ ] Information gathering section is complete
- [ ] Step-by-step process is detailed
- [ ] Error handling section exists
- [ ] Validation checklist is present
- [ ] Important notes section included

### Content
- [ ] All required information is listed
- [ ] Information formats are specified
- [ ] Examples are provided
- [ ] Steps are clear and unambiguous
- [ ] Validation criteria are specified
- [ ] Common errors are documented
- [ ] Error fixes are provided

### Quality
- [ ] Instructions are testable
- [ ] Prompt has been tested
- [ ] Examples are accurate
- [ ] Validation checklist is complete
- [ ] Error handling is comprehensive
- [ ] Customized for Tendril project
- [ ] Uses Gitea terminology (not GitHub)

### Tendril-Specific
- [ ] References "Tendril" (not "pairs")
- [ ] Uses Gitea terminology
- [ ] References correct repository URL
- [ ] Uses Tendril directory structure
- [ ] References Tendril-specific paths

---

## Examples

### Example 1: Simple Status Check

```markdown
# Project Status Check Prompt

**Purpose:** Check current status of all project phases

**How to Use:** Drag this document into Cursor chat. The AI will read all phase blueprints and provide a status summary.

## CRITICAL: Information Gathering

No additional information required. The AI will read phase blueprints automatically.

## Step-by-Step Process

### Phase 1: Read Phase Blueprints
1. Find all `blueprint.md` files in `tendril/phases/`
2. Read each blueprint
3. Extract: phase name, status, key deliverables

### Phase 2: Summarize Status
1. List all phases with status
2. Count: Complete, In Progress, Planned
3. Identify any issues or blockers

## Validation Checklist
- [ ] All phase blueprints read
- [ ] Status summary provided
- [ ] Phase counts are accurate
```

### Example 2: Complex Sync Task

```markdown
# Phase Documentation Sync Prompt

**Purpose:** Ensure phase documentation (blueprint, tasks, decisions, changelog) is synchronized

## CRITICAL: Information Gathering

1. **Phase name or path** (REQUIRED)
   - Format: `phase-XX-name` or full path
   - Example: `phase-01-foundation` or `tendril/phases/phase-01-foundation/`
   - Why: Need to know which phase to sync

## Step-by-Step Process

### Phase 1: Read All Documents
1. Read `blueprint.md`
2. Read `tasks.md`
3. Read `decisions.md`
4. Read `changelog.md`

### Phase 2: Compare and Identify Discrepancies
1. Compare project name across all documents
2. Compare status indicators
3. Compare deliverables/tasks
4. List all discrepancies

### Phase 3: Update Documents
1. Update `tasks.md` to match blueprint
2. Update `changelog.md` with sync entry
3. Review `decisions.md` for missing ADRs
4. Verify all documents are consistent

## Error Handling

### Phase Directory Not Found
- **Error**: Directory doesn't exist
- **Fix**: Verify phase name/path is correct
- **Prevention**: Use exact phase name from phases directory

## Validation Checklist
- [ ] All four documents read
- [ ] Discrepancies identified
- [ ] Documents updated
- [ ] Consistency verified
```

---

## Summary

Creating effective prompt documents requires:

1. **Follow the structure template** - Include all required sections
2. **Be specific and complete** - Don't leave room for interpretation
3. **Include validation** - Verify completion at each step
4. **Handle errors** - Anticipate and document common issues
5. **Test thoroughly** - Verify prompt works before using
6. **Customize for Tendril** - Use project-specific context

**Remember**: Good prompts are reusable, reliable, and reduce errors. Invest time in creating quality prompts to save time in the long run.

---

**Location**: `docs/PROMPTS/Prompt-Creation-Guide.md`  
**Related**: 
- `docs/PROMPTS/LLM-Usage-Guide.md`
- `docs/GITEA/LLM-Gitea-Guidelines.md`
- `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md`