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

# [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

## 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

## 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

## Validation Checklist

Before completing, verify:

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

6. Important Notes for AI Assistant

## 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:

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:

### 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

# [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

# 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

# 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

# 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

# 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