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

237
docs/PROMPTS/01-KB-Content-Search-Prompt.md Normal file
View File

@@ -0,0 +1,237 @@
# KB Content Search Prompt
**Purpose:** Search the Knowledge Base (KB) system for relevant content matching specified criteria (topics, tags, phase relevance, or keywords).
**How to Use:** Drag this entire document into a Cursor chat session, then provide search criteria (topics, tags, phase, or keywords). The AI assistant will search the KB index and relevant files to find matching content.
---
## CRITICAL: Information Gathering
### Required Information (You should provide this)
Before starting, **ASK THE USER** for the following information if not already provided:
1. **Search criteria** (REQUIRED - at least one)
- Format: Topics (array), Tags (array), Phase relevance (string), or Keywords (string)
- Examples:
- Topics: `["workflows", "automation"]`
- Tags: `["gitea", "actions"]`
- Phase: `"phase-03"` or `"phase-3"`
- Keywords: `"KB system setup"`
- Why it's needed: Determines what content to search for
2. **Search scope** (OPTIONAL)
- Format: Specific category or "all"
- Examples: `"01_projects"`, `"02_systems"`, `"all"`
- Default: "all" (search all KB categories)
- Why it's needed: Limits search to specific KB categories if desired
### If Information is Missing
**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about:
- What the user wants to search for
- Which KB categories to search
- Search criteria format
---
## Step-by-Step Process
### Phase 1: Read KB Index
1. **Read the KB index file:**
- Path: `kb/_index.md`
- Extract: File listings, topics index, tags index, phase relevance index
2. **Validation:**
- Verify `kb/_index.md` exists
- Confirm index is readable
- Check index structure is valid
### Phase 2: Parse Search Criteria
1. **Identify search type:**
- Topics search: If topics array provided
- Tags search: If tags array provided
- Phase search: If phase relevance provided
- Keyword search: If keywords string provided
- Combined: If multiple criteria provided
2. **Prepare search parameters:**
- Normalize topics/tags (lowercase, trim)
- Normalize phase format (ensure `phase-XX` format)
- Prepare keyword search terms
3. **Validation:**
- Search criteria are valid
- Format is correct
- At least one search criterion is provided
### Phase 3: Execute Search
1. **Search by topics** (if provided):
- Check topics index in `kb/_index.md`
- Find files matching topic(s)
- Collect file paths
2. **Search by tags** (if provided):
- Check tags index in `kb/_index.md`
- Find files matching tag(s)
- Collect file paths
3. **Search by phase** (if provided):
- Check phase relevance index in `kb/_index.md`
- Find files relevant to specified phase
- Collect file paths
4. **Search by keywords** (if provided):
- Search file titles in index
- Search summaries in index
- Optionally: Search file contents (if index includes content)
- Collect file paths
5. **Combine results** (if multiple criteria):
- Merge results from different search types
- Remove duplicates
- Apply search scope filter if specified
6. **Validation:**
- Search executed successfully
- Results collected
- Duplicates removed
### Phase 4: Read Matching Files
For each matching file found:
1. **Read the KB file:**
- Path: `kb/[category]/[filename].md`
- Extract: Title, summary, topics, tags, phase relevance, key content
2. **Extract relevant information:**
- Frontmatter metadata
- Key takeaways (if present)
- Summary section
- Relevant content sections
3. **Validation:**
- File exists and is readable
- Metadata extracted correctly
- Content is relevant to search
### Phase 5: Present Search Results
1. **Organize results:**
- Group by category (if multiple categories)
- Sort by relevance (if possible)
- List file paths and titles
2. **Create summary:**
- Total matches found
- Matches by category
- Matches by search type
3. **Present detailed results:**
- For each match:
- File path
- Title
- Summary
- Matching topics/tags/phases
- Key takeaways (if available)
- Link to full file
4. **Validation:**
- All matches are included
- Information is accurate
- Results are organized clearly
---
## Error Handling
### Common Issues
#### KB Index Not Found
- **Error message**: "File not found: kb/_index.md"
- **Fix**:
1. Check if `kb/_index.md` exists
2. Run `kb/scripts/generate-index.sh` to generate index
3. Verify KB system is set up correctly
- **Prevention**: Ensure KB index is generated before searching
#### Invalid Search Criteria Format
- **Error message**: "Invalid search criteria format"
- **Fix**:
1. Verify criteria format matches expected format
2. Check topics/tags are arrays
3. Verify phase format is `phase-XX`
4. Ask user to clarify format
- **Prevention**: Validate format before searching
#### No Matches Found
- **Error message**: "No matching KB files found"
- **Fix**:
1. Verify search criteria are correct
2. Check if KB files exist in specified categories
3. Try broader search criteria
4. Check index is up to date
- **Prevention**: Provide helpful message suggesting alternative searches
#### KB File Read Error
- **Error message**: "Error reading KB file: [path]"
- **Fix**:
1. Verify file exists at specified path
2. Check file permissions
3. Verify file has valid frontmatter
4. Skip file and continue with others
- **Prevention**: Handle file read errors gracefully
#### Index Out of Date
- **Error message**: "Index may be out of date"
- **Fix**:
1. Run `kb/scripts/generate-index.sh` to update index
2. Re-run search after index update
3. Note that results may be incomplete
- **Prevention**: Keep index updated regularly
---
## Validation Checklist
Before completing, verify:
- [ ] KB index read successfully
- [ ] Search criteria parsed correctly
- [ ] Search executed for all provided criteria
- [ ] Matching files identified
- [ ] All matching files read (or errors noted)
- [ ] Results organized clearly
- [ ] Summary includes match counts
- [ ] Detailed results include all relevant information
- [ ] File paths are correct and accessible
- [ ] Results are relevant to search criteria
---
## Important Notes for AI Assistant
1. **Use the index first**: Always read `kb/_index.md` before searching individual files
2. **Handle missing index**: If index doesn't exist, offer to generate it or search files directly
3. **Be flexible with matching**: Match topics/tags case-insensitively, handle variations
4. **Provide context**: Include why files match (which topic/tag/phase matched)
5. **Limit results if needed**: If too many matches, suggest refining search criteria
6. **Handle empty results**: Provide helpful suggestions if no matches found
7. **Respect search scope**: If scope specified, only search within that category
8. **Use Tendril terminology**: Reference "Tendril" project and KB system correctly
9. **Note index freshness**: Mention if index might be out of date
---
**Location**: `docs/PROMPTS/01-KB-Content-Search-Prompt.md`
**Related**:
- `kb/_index.md` - KB index file
- `kb/README.md` - KB system documentation
- `kb/scripts/generate-index.sh` - Index generation script
- `docs/PROMPTS/LLM-Usage-Guide.md` - LLM execution guidelines