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

249
docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md Normal file
View File

@@ -0,0 +1,249 @@
# Phase Documentation Sync Prompt
**Purpose:** Ensure phase documentation (blueprint.md, tasks.md, decisions.md, changelog.md) is synchronized and consistent across all documents for a specified phase.
**How to Use:** Drag this entire document into a Cursor chat session, then provide the phase name or path. The AI assistant will read all phase documents, identify discrepancies, and update them to ensure consistency.
---
## CRITICAL: Information Gathering
### Required Information (You should provide this)
Before starting, **ASK THE USER** for the following information if not already provided:
1. **Phase name or path** (REQUIRED)
- Format: `phase-XX-name` or full path `tendril/phases/phase-XX-name/`
- Examples:
- `phase-01-foundation`
- `phase-02-kb-system`
- `tendril/phases/phase-03-workflows/`
- Why it's needed: Identifies which phase to synchronize
2. **Sync scope** (OPTIONAL)
- Format: "all" or specific documents (comma-separated)
- Examples: `"all"`, `"tasks,changelog"`, `"decisions"`
- Default: "all" (sync all documents)
- Why it's needed: Allows syncing specific documents if desired
### If Information is Missing
**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about:
- Which phase to sync
- Phase directory location
- Document names or structure
---
## Step-by-Step Process
### Phase 1: Read All Phase Documents
1. **Read blueprint.md:**
- Path: `tendril/phases/phase-XX-name/blueprint.md`
- Extract: Project name, phase status, deliverables, milestones, definition of done
2. **Read tasks.md:**
- Path: `tendril/phases/phase-XX-name/tasks.md`
- Extract: Task list, completion status, phase status line
3. **Read decisions.md:**
- Path: `tendril/phases/phase-XX-name/decisions.md`
- Extract: ADR entries, decision dates, decision summaries
4. **Read changelog.md:**
- Path: `tendril/phases/phase-XX-name/changelog.md`
- Extract: Recent entries, change dates, change descriptions
5. **Validation:**
- All four documents exist
- All documents are readable
- Key information extracted from each
### Phase 2: Compare and Identify Discrepancies
1. **Compare project name:**
- Check project name in blueprint
- Compare with project name in tasks, decisions, changelog
- List any mismatches
2. **Compare phase status:**
- Extract status from blueprint (✅ Complete, 🔄 In Progress, ⏳ Planned)
- Compare with status in tasks.md
- Compare with status indicators in other documents
- List any mismatches
3. **Compare deliverables:**
- Extract deliverables from blueprint "Phase Deliverables" section
- Compare with tasks in tasks.md
- Check if all deliverables have corresponding tasks
- List missing or extra tasks
4. **Compare definition of done:**
- Extract "Definition of Done" items from blueprint
- Compare with task checkboxes in tasks.md
- Verify all DoD items are represented as tasks
- List missing or extra tasks
5. **Check ADR consistency:**
- Review decisions mentioned in blueprint
- Verify corresponding ADRs exist in decisions.md
- List missing ADRs
6. **Check changelog completeness:**
- Verify recent blueprint changes are in changelog
- Check changelog format is correct
- List missing changelog entries
7. **Validation:**
- All comparisons completed
- All discrepancies identified
- Discrepancy list is complete
### Phase 3: Update Documents
1. **Update tasks.md:**
- Sync task list with blueprint deliverables
- Sync task checkboxes with blueprint "Definition of Done"
- Update phase status line to match blueprint
- Ensure project name matches blueprint
2. **Update changelog.md:**
- Add entry for sync operation (if needed)
- Format: `## [YYYY-MM-DD] Documentation Synchronization`
- Note: "Synchronized all phase documents for consistency"
- Use today's date
3. **Update decisions.md:**
- Add missing ADRs mentioned in blueprint (if any)
- Ensure ADR format matches existing entries
- Verify project name matches blueprint
4. **Verify consistency:**
- Re-read all documents after updates
- Verify project name matches across all
- Verify status matches across all
- Verify deliverables/tasks are aligned
5. **Validation:**
- All documents updated
- Consistency verified
- No discrepancies remain
### Phase 4: Report Sync Results
1. **Summarize changes made:**
- List documents updated
- Describe what was synchronized
- Note any issues encountered
2. **Report remaining issues** (if any):
- List any discrepancies that couldn't be resolved
- Explain why they couldn't be fixed
- Suggest manual review if needed
3. **Validation:**
- Report is complete
- All changes documented
- Issues clearly explained
---
## Error Handling
### Common Issues
#### Phase Directory Not Found
- **Error message**: "Directory not found: tendril/phases/phase-XX-name/"
- **Fix**:
1. Verify phase name/path is correct
2. Check if phase directory exists
3. List available phases to help user
- **Prevention**: Validate phase path before reading files
#### Missing Document File
- **Error message**: "File not found: [document].md"
- **Fix**:
1. Check if file exists in phase directory
2. Verify file name is correct (case-sensitive)
3. Create missing file if it's a new phase (use templates)
4. Note missing file in report
- **Prevention**: Check all required files exist before syncing
#### Invalid Document Format
- **Error message**: "Invalid format in [document].md"
- **Fix**:
1. Review document structure
2. Check for missing required sections
3. Fix format issues
4. Re-read document
- **Prevention**: Validate document structure before processing
#### Project Name Mismatch
- **Error message**: "Project name mismatch across documents"
- **Fix**:
1. Use blueprint.md as source of truth
2. Update all other documents to match blueprint
3. Verify consistency after updates
- **Prevention**: Always use blueprint as authoritative source
#### Status Indicator Mismatch
- **Error message**: "Status mismatch between blueprint and tasks"
- **Fix**:
1. Use blueprint status as source of truth
2. Update tasks.md status line
3. Verify status format is correct (✅, 🔄, ⏳)
- **Prevention**: Always sync status from blueprint to tasks
#### Unresolvable Discrepancies
- **Error message**: "Cannot automatically resolve discrepancy"
- **Fix**:
1. Report discrepancy to user
2. Explain why it can't be auto-resolved
3. Suggest manual review
4. Continue with other sync operations
- **Prevention**: Document limitations clearly
---
## Validation Checklist
Before completing, verify:
- [ ] All four phase documents read successfully
- [ ] All discrepancies identified
- [ ] tasks.md synced with blueprint deliverables
- [ ] tasks.md synced with blueprint "Definition of Done"
- [ ] tasks.md status matches blueprint status
- [ ] changelog.md updated with sync entry
- [ ] decisions.md reviewed for missing ADRs
- [ ] Project name consistent across all documents
- [ ] Status consistent across all documents
- [ ] Deliverables/tasks aligned
- [ ] All changes verified
- [ ] Sync report provided
---
## Important Notes for AI Assistant
1. **Blueprint is authoritative**: Always use blueprint.md as the source of truth for syncing
2. **Preserve existing content**: Don't delete existing content unless it conflicts with blueprint
3. **Add, don't replace**: When syncing tasks, add missing items rather than replacing entire lists
4. **Use correct date format**: Use YYYY-MM-DD format for changelog entries
5. **Maintain document structure**: Preserve existing document structure and formatting
6. **Handle missing files**: If a document is missing, note it but continue with available documents
7. **Report all changes**: Document what was changed in the sync report
8. **Use Tendril terminology**: Reference "Tendril" project consistently
9. **Follow Cursor rules**: Adhere to phase documentation synchronization rules in `.cursorrules`
10. **Verify after updates**: Always re-read documents after updates to verify consistency
---
**Location**: `docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md`
**Related**:
- `tendril/phases/phase-XX-name/` - Phase directories
- `.cursorrules` - Phase documentation synchronization rules
- `docs/PROMPTS/LLM-Usage-Guide.md` - LLM execution guidelines
- `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md` - Phase documentation system