tendril/docs/PROMPTS/LLM-Usage-Guide.md

# LLM Usage Guide for Prompt Documents

**Purpose**: Instructions for AI assistants (LLMs) on how to recognize, interpret, and execute prompt documents in the Tendril project.

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

---

## Overview

This guide provides comprehensive instructions for AI assistants working with prompt documents in the Tendril repository. Prompt documents are reusable, standardized instructions that enable consistent AI-assisted workflows.

**Repository Context**:
- **Project**: Tendril
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Platform**: Gitea (self-hosted)
- **Prompt Location**: `docs/PROMPTS/`

---

## Recognizing Prompt Documents

### Naming Convention

Prompt documents follow a specific naming pattern:
- Format: `NN-Descriptive-Name-Prompt.md`
- `NN` is a zero-padded two-digit number (00, 01, 02, etc.)
- `Descriptive-Name` uses kebab-case
- Always ends with `-Prompt.md`

**Examples**:
- `00-Project-Status-Check-Prompt.md`
- `01-KB-Content-Search-Prompt.md`
- `02-Phase-Documentation-Sync-Prompt.md`

### Document Structure

Prompt documents have a consistent structure:
1. **Title** - Task name with "Prompt" suffix
2. **Purpose** - One sentence describing what the prompt accomplishes
3. **How to Use** - Instructions for using the prompt
4. **CRITICAL: Information Gathering** - Required information section
5. **Step-by-Step Process** - Phased execution instructions
6. **Error Handling** - Common issues and solutions
7. **Validation Checklist** - Completion verification
8. **Important Notes** - Critical instructions for AI assistant

### Location

Prompt documents are located in:
- `docs/PROMPTS/` directory
- All prompts are markdown files (`.md`)

---

## Executing Prompts (Phase-by-Phase Execution)

### Step 1: Recognize the Prompt

When a prompt document is provided:
1. **Identify it as a prompt document** by checking:
   - File name matches `NN-Descriptive-Name-Prompt.md` pattern
   - File is in `docs/PROMPTS/` directory
   - Document has prompt structure (Purpose, How to Use, etc.)

2. **Read the entire prompt document** before starting execution

3. **Understand the purpose** from the Purpose section

### Step 2: Information Gathering

**CRITICAL**: Before executing any steps, gather all required information:

1. **Check the "CRITICAL: Information Gathering" section**
   - Identify all required information items
   - Note format/constraints for each item
   - Understand why each item is needed

2. **Ask the user for missing information**
   - If any required information is missing, **ASK THE USER**
   - Do not make assumptions
   - Do not proceed without required information

3. **Verify information format**
   - Ensure provided information matches required format
   - Ask for clarification if format is unclear

### Step 3: Execute Step-by-Step

Follow the prompt's step-by-step process:

1. **Execute phases in order**
   - Do not skip phases
   - Complete each phase before moving to the next

2. **Follow instructions precisely**
   - Execute commands exactly as specified
   - Use provided code/commands without modification (unless explicitly allowed)

3. **Validate each step**
   - After each step, verify it succeeded
   - Check validation criteria provided in the prompt
   - Report any errors immediately

4. **Provide progress updates**
   - Inform the user of progress
   - Report completion of each phase
   - Note any issues or deviations

### Step 4: Error Handling

When errors occur:

1. **Check the "Error Handling" section**
   - Look for the specific error in "Common Issues"
   - Follow the provided fix instructions
   - Apply prevention measures if applicable

2. **If error not in guide**:
   - Report the error to the user
   - Describe what you tried
   - Ask for guidance

3. **Do not continue with errors unresolved**
   - Fix errors before proceeding
   - Verify fix before continuing

### Step 5: Validation

Before completing:

1. **Review the "Validation Checklist"**
   - Check each item in the checklist
   - Verify all items are complete
   - Report any incomplete items

2. **Verify final state**
   - Confirm all objectives are met
   - Check that outputs match expectations
   - Ensure no errors remain

3. **Provide completion summary**
   - List what was accomplished
   - Note any issues encountered
   - Report validation results

---

## Information Gathering

### Required Information Section

Every prompt document includes a "CRITICAL: Information Gathering" section that lists:
- **Required information items** - What you need from the user
- **Format/constraints** - How the information should be provided
- **Examples** - Sample values or formats
- **Why it's needed** - Purpose of each information item

### Gathering Process

1. **Read the information gathering section first**
2. **Check if user has provided required information**
3. **If missing, ask the user** - Do not proceed without it
4. **Verify format** - Ensure information matches required format
5. **Confirm understanding** - Clarify any ambiguities

### What NOT to Assume

**NEVER assume**:
- File paths or locations
- User preferences or choices
- Current state of files or systems
- Default values unless explicitly stated
- User intent without confirmation

**ALWAYS ask** if:
- Information is missing
- Format is unclear
- Multiple interpretations are possible
- User preference affects the outcome

---

## Error Handling

### Common Error Patterns

1. **File Not Found**
   - Check file path is correct
   - Verify file exists
   - Check current working directory

2. **Permission Denied**
   - Check file permissions
   - Verify user has access
   - Check if file is locked

3. **Invalid Format**
   - Verify format matches requirements
   - Check for typos or syntax errors
   - Review format examples

4. **Missing Dependencies**
   - Check if required tools are installed
   - Verify environment setup
   - Review dependencies section

### Error Response Process

1. **Identify the error** - What went wrong?
2. **Check error handling section** - Is this error documented?
3. **Apply fix** - Follow provided fix instructions
4. **Verify fix** - Confirm error is resolved
5. **Continue or report** - Proceed or ask for help

---

## Validation Steps

### Pre-Execution Validation

Before starting execution:
- [ ] Prompt document is complete (all sections present)
- [ ] Purpose is clear and understood
- [ ] All required information is gathered
- [ ] Information format is correct
- [ ] User has confirmed understanding

### During Execution Validation

After each phase:
- [ ] Phase completed successfully
- [ ] Validation criteria met
- [ ] No errors encountered
- [ ] Progress reported to user

### Post-Execution Validation

Before completion:
- [ ] All phases completed
- [ ] Validation checklist reviewed
- [ ] All checklist items verified
- [ ] Final state confirmed
- [ ] Completion summary provided

---

## Providing Feedback

### Progress Updates

Provide regular updates:
- **Start**: Announce when beginning execution
- **Progress**: Report completion of each phase
- **Issues**: Report any problems immediately
- **Completion**: Summarize what was accomplished

### Error Reporting

When errors occur:
- **Describe the error** clearly
- **Explain what you tried** to fix it
- **Reference error handling section** if applicable
- **Ask for help** if error is not documented

### Completion Summary

At the end:
- **List accomplishments** - What was completed
- **Note issues** - Any problems encountered
- **Report validation** - Checklist results
- **Suggest next steps** - If applicable

---

## Best Practices

### Execution Best Practices

1. **Read the entire prompt first** - Don't start until you understand everything
2. **Gather all information** - Don't proceed with missing required information
3. **Follow steps in order** - Don't skip phases or steps
4. **Validate frequently** - Check progress after each phase
5. **Report regularly** - Keep user informed of progress
6. **Handle errors promptly** - Don't ignore errors or warnings

### Communication Best Practices

1. **Be clear and specific** - Use precise language
2. **Ask when uncertain** - Don't guess or assume
3. **Explain your actions** - Help user understand what you're doing
4. **Provide context** - Explain why you're doing something
5. **Confirm understanding** - Verify user understands your questions

### Quality Best Practices

1. **Verify outputs** - Check that results match expectations
2. **Test assumptions** - Verify before proceeding
3. **Document deviations** - Note any changes from the prompt
4. **Review validation checklist** - Ensure nothing is missed
5. **Provide complete summaries** - Include all relevant information

---

## Special Instructions

### Tendril-Specific Context

When working with Tendril project prompts:

- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Platform**: Gitea (not GitHub)
- **Phase Structure**: `tendril/phases/phase-XX-name/`
- **KB Structure**: `kb/` with category directories
- **Workflows**: Gitea Actions (compatible with GitHub Actions format)

### Project-Specific Rules

- Use "Tendril" (not "pairs" or placeholders)
- Reference Gitea features and terminology
- Follow Tendril directory structure
- Use Tendril-specific paths and conventions

### Integration Points

Prompts may interact with:
- **Phase Documentation**: `tendril/phases/phase-XX-name/blueprint.md`, `tasks.md`, `decisions.md`, `changelog.md`
- **KB System**: `kb/` directory with category subdirectories
- **Workflows**: `.github/workflows/` (Gitea Actions)
- **Documentation**: `docs/` directory

---

## Troubleshooting

### Prompt Not Recognized

**Symptoms**: AI assistant doesn't recognize document as a prompt

**Solutions**:
1. Verify file name matches `NN-Descriptive-Name-Prompt.md` pattern
2. Check file is in `docs/PROMPTS/` directory
3. Verify document has prompt structure (Purpose, How to Use, etc.)
4. Explicitly tell the AI: "This is a prompt document, please follow its instructions"

### Instructions Not Followed

**Symptoms**: AI assistant doesn't follow prompt instructions

**Solutions**:
1. Verify prompt document is complete (all sections present)
2. Check "CRITICAL" and "MANDATORY" sections are clearly marked
3. Ensure information gathering section requests all required data
4. Review this LLM-Usage-Guide.md for execution guidelines
5. Test prompt with a simple task first

### Missing Information

**Symptoms**: Prompt requires information that wasn't provided

**Solutions**:
1. Check "CRITICAL: Information Gathering" section
2. Ask user for missing required information
3. Do not make assumptions or use defaults
4. Verify information format before proceeding

### Execution Errors

**Symptoms**: Errors occur during prompt execution

**Solutions**:
1. Check "Error Handling" section in the prompt
2. Review error message and apply provided fixes
3. Verify file paths and permissions
4. Check dependencies and environment
5. Report error to user if not documented

---

## Summary

This guide provides comprehensive instructions for AI assistants working with prompt documents in the Tendril project. Key points:

1. **Recognize prompts** by naming convention and structure
2. **Gather information** before starting execution
3. **Execute step-by-step** following the prompt's phases
4. **Handle errors** using provided error handling guidance
5. **Validate completion** using the validation checklist
6. **Provide feedback** throughout the process

**Remember**: Prompt documents are designed to be reusable and standardized. Follow them precisely to ensure consistent, reliable results.

---

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