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