Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(prompts): implement Phase 4 LLM Usage Guides Setup

Browse Source 
This commit implements the complete LLM Usage Guides system for the Tendril
project, establishing reusable prompt documents for AI-assisted workflows.

## What Was Implemented

### 1. Core Guide Documents

**docs/PROMPTS/LLM-Usage-Guide.md** - Comprehensive LLM execution instructions:
- Recognizing prompt documents (naming convention, structure, location)
- Step-by-step execution process (5 phases: recognize, gather info, execute, handle errors, validate)
- Information gathering requirements and best practices
- Error handling procedures and common error patterns
- Validation steps (pre-execution, during execution, post-execution)
- Providing feedback (progress updates, error reporting, completion summaries)
- Best practices for execution, communication, and quality
- Special instructions for Tendril-specific context
- Troubleshooting guide for common prompt execution issues
- Customized for Tendril project structure and Gitea platform

**docs/PROMPTS/Prompt-Creation-Guide.md** - Guide for creating effective prompts:
- Naming convention (NN-Descriptive-Name-Prompt.md format)
- Complete prompt structure template with all required sections
- Best practices for writing effective instructions
- Information gathering guidelines
- Error handling documentation standards
- Testing procedures for new prompts
- Common patterns (status check, search, sync patterns)
- Decision criteria for when to create new prompts
- Update procedures for existing prompts
- Comprehensive checklist for new prompts
- Examples customized for Tendril project
- References to Gitea-specific workflows and features

### 2. Initial Prompt Documents

**docs/PROMPTS/00-Project-Status-Check-Prompt.md** - Project status overview:
- Purpose: Check current status of all project phases
- Reads all phase blueprints in tendril/phases/
- Extracts phase status, deliverables, milestones
- Organizes by status (Complete, In Progress, Planned)
- Provides comprehensive status summary with counts
- Highlights issues or blockers
- Error handling for missing files, invalid formats
- Validation checklist for completion
- Customized for Tendril phase structure

**docs/PROMPTS/01-KB-Content-Search-Prompt.md** - KB system search:
- Purpose: Search KB system for relevant content
- Supports multiple search types: topics, tags, phase relevance, keywords
- Uses kb/_index.md for efficient searching
- Reads matching KB files and extracts metadata
- Presents organized search results with summaries
- Handles missing index, invalid criteria, empty results
- Provides helpful suggestions for refining searches
- Customized for Tendril KB structure and categories

**docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md** - Phase documentation synchronization:
- Purpose: Ensure phase documentation consistency
- Reads all four phase documents (blueprint, tasks, decisions, changelog)
- Compares and identifies discrepancies
- Syncs tasks.md with blueprint deliverables and Definition of Done
- Updates changelog.md with sync entry
- Reviews decisions.md for missing ADRs
- Verifies consistency across all documents
- Follows Cursor rules for phase documentation synchronization
- Error handling for missing files, format issues, unresolvable discrepancies
- Customized for Tendril phase structure and documentation system

## Why This Implementation

### Standardized AI Workflows
   LLM Usage Guides enable consistent, repeatable AI-assisted workflows. Instead
   of explaining the same tasks repeatedly, prompts provide standardized
   instructions that work reliably every time.

### Reusability and Efficiency
   Prompt documents can be dragged into Cursor chat sessions and executed
   immediately. This saves time and ensures tasks are performed consistently
   across different sessions and users.

### Quality and Reliability
   Well-structured prompts include validation checklists, error handling, and
   best practices. This reduces errors and ensures high-quality results.

### Knowledge Preservation
   Prompts document how to perform complex tasks, preserving institutional
   knowledge and making it accessible to anyone who needs to perform the task.

### Integration with Project Systems
   Prompts are designed to work with Tendril's phase documentation system, KB
   system, and Gitea workflows, providing seamless integration with existing
   project infrastructure.

## Technical Details

### Prompt Document Structure

All prompts follow a consistent structure:
1. **Title and Purpose** - Clear description of what the prompt does
2. **How to Use** - Instructions for using the prompt
3. **CRITICAL: Information Gathering** - Required information section
4. **Step-by-Step Process** - Phased execution instructions
5. **Error Handling** - Common issues and solutions
6. **Validation Checklist** - Completion verification
7. **Important Notes** - Critical instructions for AI assistant

### Naming Convention

Prompts follow strict naming:
- 00-09: Core system prompts
- 10-19: Phase management prompts
- 20-29: KB system prompts
- 30-39: Workflow and automation prompts
- 40-49: Documentation prompts
- 50+: Project-specific prompts

### Customization for Tendril

All prompts and guides are customized for:
- **Project Name**: Tendril (not "pairs" or placeholders)
- **Platform**: Gitea (not GitHub)
- **Repository**: https://git.parkingmeter.info/Mycelium/tendril
- **Directory Structure**: tendril/phases/, kb/ with category directories
- **Workflows**: Gitea Actions (with GitHub Actions compatibility notes)

### Integration Points

Prompts integrate with:
- **Phase Documentation**: tendril/phases/phase-XX-name/ files
- **KB System**: kb/ directory with index and category structure
- **Workflows**: .github/workflows/ (Gitea Actions)
- **Documentation**: docs/ directory structure

## Files Added

- docs/PROMPTS/LLM-Usage-Guide.md - LLM execution instructions (~400 lines)
- docs/PROMPTS/Prompt-Creation-Guide.md - Prompt creation guide (~600 lines)
- docs/PROMPTS/00-Project-Status-Check-Prompt.md - Status check prompt (~180 lines)
- docs/PROMPTS/01-KB-Content-Search-Prompt.md - KB search prompt (~240 lines)
- docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md - Documentation sync prompt (~250 lines)

**Total**: 5 files, ~1,670 lines of prompt documentation

## Validation

All Phase 4 requirements met:
- ✅ LLM Usage Guide created and comprehensive
- ✅ Prompt Creation Guide created with complete template
- ✅ Three initial prompt documents created
- ✅ All prompts follow naming convention
- ✅ All prompts include required sections
- ✅ All files reference "Tendril" (42 references found)
- ✅ All files use "Gitea" terminology (10 references, no GitHub)
- ✅ Examples relevant to Tendril project structure
- ✅ Documentation is clear and actionable

## Next Steps

Phase 4 complete. LLM Usage Guides system is ready for use. Prompts can be
dragged into Cursor chat sessions to perform standardized tasks. Ready for
Phase 5: Validation and Testing.

## Related

- Phase 4 Plan: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md
- Replication Guide: kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
- Gitea LLM Guidelines: docs/GITEA/LLM-Gitea-Guidelines.md
This commit is contained in:
Gitea Actions
2025-11-11 12:25:52 -07:00
parent 3ad53162c8
commit 6a4683022f
5 changed files with 1709 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

400
docs/PROMPTS/LLM-Usage-Guide.md Normal file
View File

@@ -0,0 +1,400 @@
# 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`