From 6a4683022f84229e666c36bd349afb0223ee8058 Mon Sep 17 00:00:00 2001 From: Gitea Actions Date: Tue, 11 Nov 2025 12:25:52 -0700 Subject: [PATCH] docs(prompts): implement Phase 4 LLM Usage Guides Setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../PROMPTS/00-Project-Status-Check-Prompt.md | 177 +++++ docs/PROMPTS/01-KB-Content-Search-Prompt.md | 237 +++++++ .../02-Phase-Documentation-Sync-Prompt.md | 249 +++++++ docs/PROMPTS/LLM-Usage-Guide.md | 400 +++++++++++ docs/PROMPTS/Prompt-Creation-Guide.md | 646 ++++++++++++++++++ 5 files changed, 1709 insertions(+) create mode 100644 docs/PROMPTS/00-Project-Status-Check-Prompt.md create mode 100644 docs/PROMPTS/01-KB-Content-Search-Prompt.md create mode 100644 docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md create mode 100644 docs/PROMPTS/LLM-Usage-Guide.md create mode 100644 docs/PROMPTS/Prompt-Creation-Guide.md diff --git a/docs/PROMPTS/00-Project-Status-Check-Prompt.md b/docs/PROMPTS/00-Project-Status-Check-Prompt.md new file mode 100644 index 0000000..c33b58e --- /dev/null +++ b/docs/PROMPTS/00-Project-Status-Check-Prompt.md @@ -0,0 +1,177 @@ +# Project Status Check Prompt + +**Purpose:** Check current status of all project phases in the Tendril repository and provide a comprehensive status summary. + +**How to Use:** Drag this entire document into a Cursor chat session. The AI assistant will read all phase blueprints and provide a status overview including phase completion, deliverables, and any issues. + +--- + +## CRITICAL: Information Gathering + +### Required Information (You should provide this) + +No additional information required. The AI will automatically: +- Find all phase directories in `tendril/phases/` +- Read phase blueprint files +- Extract status information + +### If Information is Missing + +**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about: +- Phase directory structure +- Blueprint file locations +- Status indicator formats + +--- + +## Step-by-Step Process + +### Phase 1: Discover Phase Directories + +1. **Find all phase directories:** + ```bash + find tendril/phases -type d -name "phase-*" | sort + ``` + - Should list all phase directories + - Format: `tendril/phases/phase-XX-name/` + +2. **Validation:** + - Verify phase directories are found + - Check naming follows `phase-XX-name` pattern + - Confirm directories exist + +### Phase 2: Read Phase Blueprints + +For each phase directory found: + +1. **Read the blueprint file:** + - Path: `tendril/phases/phase-XX-name/blueprint.md` + - Extract: Phase name, status, key deliverables, milestones + +2. **Read the tasks file:** + - Path: `tendril/phases/phase-XX-name/tasks.md` + - Extract: Task completion status, open tasks + +3. **Validation:** + - Verify blueprint file exists + - Confirm status indicators are readable + - Check deliverables are listed + +### Phase 3: Compile Status Summary + +1. **Organize by status:** + - ✅ Complete phases + - 🔄 In Progress phases + - ⏳ Planned phases + +2. **Count phases:** + - Total phases + - Complete count + - In Progress count + - Planned count + +3. **Extract key information:** + - Phase names and numbers + - Current status for each + - Key deliverables per phase + - Any blockers or issues mentioned + +4. **Validation:** + - All phases are accounted for + - Status counts are accurate + - No phases are missing + +### Phase 4: Present Status Report + +1. **Create summary table:** + - Phase | Status | Key Deliverables | Notes + +2. **Provide overview:** + - Total phases: X + - Complete: X + - In Progress: X + - Planned: X + +3. **Highlight issues:** + - Any phases with blockers + - Phases behind schedule + - Missing or incomplete deliverables + +4. **Validation:** + - Summary is complete + - All phases are included + - Status is accurate + +--- + +## Error Handling + +### Common Issues + +#### Phase Directory Not Found +- **Error message**: "No phase directories found" or "Directory does not exist" +- **Fix**: + 1. Verify you're in the repository root + 2. Check `tendril/phases/` directory exists + 3. Confirm phase naming follows `phase-XX-name` pattern +- **Prevention**: Always check directory structure before reading files + +#### Blueprint File Missing +- **Error message**: "File not found: blueprint.md" +- **Fix**: + 1. Check if blueprint.md exists in phase directory + 2. Verify file name is exactly `blueprint.md` (case-sensitive) + 3. Check file permissions +- **Prevention**: Verify file exists before attempting to read + +#### Invalid Status Format +- **Error message**: "Status indicator not recognized" +- **Fix**: + 1. Check status format in blueprint + 2. Look for: ✅ Complete, 🔄 In Progress, ⏳ Planned + 3. Handle variations or typos gracefully +- **Prevention**: Document expected status formats + +#### No Phases Found +- **Error message**: "No phase directories found" +- **Fix**: + 1. Verify repository structure + 2. Check if phases directory exists + 3. Confirm you're in correct repository +- **Prevention**: Validate repository structure before starting + +--- + +## Validation Checklist + +Before completing, verify: + +- [ ] All phase directories discovered +- [ ] All blueprint files read successfully +- [ ] Status extracted for each phase +- [ ] Phase counts are accurate (total = complete + in progress + planned) +- [ ] Summary table includes all phases +- [ ] Key deliverables listed for each phase +- [ ] Issues or blockers identified (if any) +- [ ] Report is clear and actionable + +--- + +## Important Notes for AI Assistant + +1. **Read all phases**: Don't skip any phase directories, even if they seem incomplete +2. **Preserve status indicators**: Use exact status indicators (✅, 🔄, ⏳) from blueprints +3. **Handle missing data gracefully**: If a blueprint is missing information, note it but continue +4. **Provide context**: Include phase numbers and names in the summary +5. **Be thorough**: Check both blueprint.md and tasks.md for complete status +6. **Use Tendril terminology**: Reference "Tendril" project, not "pairs" or placeholders +7. **Gitea context**: Note that this is a Gitea repository (not GitHub) + +--- + +**Location**: `docs/PROMPTS/00-Project-Status-Check-Prompt.md` +**Related**: +- `tendril/phases/` - Phase directories +- `docs/PROMPTS/LLM-Usage-Guide.md` - LLM execution guidelines +- `docs/PROMPTS/Prompt-Creation-Guide.md` - Prompt creation guide + diff --git a/docs/PROMPTS/01-KB-Content-Search-Prompt.md b/docs/PROMPTS/01-KB-Content-Search-Prompt.md new file mode 100644 index 0000000..21b403a --- /dev/null +++ b/docs/PROMPTS/01-KB-Content-Search-Prompt.md @@ -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 + diff --git a/docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md b/docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md new file mode 100644 index 0000000..72781cd --- /dev/null +++ b/docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md @@ -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 + diff --git a/docs/PROMPTS/LLM-Usage-Guide.md b/docs/PROMPTS/LLM-Usage-Guide.md new file mode 100644 index 0000000..55deffe --- /dev/null +++ b/docs/PROMPTS/LLM-Usage-Guide.md @@ -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` + diff --git a/docs/PROMPTS/Prompt-Creation-Guide.md b/docs/PROMPTS/Prompt-Creation-Guide.md new file mode 100644 index 0000000..dadd48a --- /dev/null +++ b/docs/PROMPTS/Prompt-Creation-Guide.md @@ -0,0 +1,646 @@ +# Prompt Creation Guide + +**Purpose**: Guide for creating effective, reusable prompt documents for AI-assisted workflows in the Tendril project. + +**Last Updated**: 2025-11-11 + +--- + +## Overview + +This guide provides step-by-step instructions for creating prompt documents that enable consistent, reliable AI-assisted workflows. Prompt documents are reusable instructions that can be dragged into Cursor chat sessions to accomplish specific tasks. + +**Key Principles**: +- **Clarity**: Instructions must be unambiguous +- **Completeness**: All required information must be specified +- **Reusability**: Prompts should work for similar tasks +- **Validation**: Include checklists to verify completion + +--- + +## Naming Convention + +### Format + +Prompt documents must follow this naming pattern: +``` +NN-Descriptive-Name-Prompt.md +``` + +Where: +- **`NN`** is a zero-padded two-digit number (00, 01, 02, etc.) +- **`Descriptive-Name`** uses kebab-case (lowercase with hyphens) +- Always ends with **`-Prompt.md`** + +### Examples + +- `00-Project-Status-Check-Prompt.md` +- `01-KB-Content-Search-Prompt.md` +- `02-Phase-Documentation-Sync-Prompt.md` +- `10-Create-New-Phase-Prompt.md` +- `20-Update-KB-Entry-Prompt.md` + +### Numbering Strategy + +- **00-09**: Core system prompts (status checks, searches, syncs) +- **10-19**: Phase management prompts +- **20-29**: KB system prompts +- **30-39**: Workflow and automation prompts +- **40-49**: Documentation prompts +- **50+**: Project-specific prompts + +--- + +## Prompt Structure Template + +Every prompt document must include these sections in order: + +### 1. Title and Purpose + +```markdown +# [Task Name] Prompt + +**Purpose:** [One sentence describing what this prompt accomplishes] + +**How to Use:** Drag this entire document into a Cursor chat session, then [provide context/information]. The AI assistant will follow these instructions to [accomplish the task]. +``` + +### 2. CRITICAL: Information Gathering + +```markdown +## CRITICAL: Information Gathering + +### Required Information (You should provide this) + +Before starting, **ASK THE USER** for the following information if not already provided: + +1. **[Information Item 1]** (REQUIRED) + - Format/constraints + - Examples + - Why it's needed + +2. **[Information Item 2]** (REQUIRED) + - Format/constraints + - Examples + - Why it's needed + +### If Information is Missing + +**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about: +- [List of things not to assume] +``` + +### 3. Step-by-Step Process + +```markdown +## Step-by-Step Process + +### Phase 1: [Phase Name] + +[Description of what this phase accomplishes] + +1. **Step description:** + ```bash + # Commands or code + ``` + +2. **Validation:** + - How to verify this step succeeded + - What to check + +### Phase 2: [Phase Name] + +[Description of what this phase accomplishes] + +1. **Step description:** + [Instructions] + +2. **Validation:** + - How to verify this step succeeded + - What to check +``` + +### 4. Error Handling + +```markdown +## Error Handling + +### Common Issues + +#### [Issue Name] +- **Error message**: What you'll see +- **Fix**: How to resolve it +- **Prevention**: How to avoid it + +#### [Another Issue] +- **Error message**: What you'll see +- **Fix**: How to resolve it +- **Prevention**: How to avoid it +``` + +### 5. Validation Checklist + +```markdown +## Validation Checklist + +Before completing, verify: + +- [ ] [Checklist item 1] +- [ ] [Checklist item 2] +- [ ] [Checklist item 3] +- [ ] ... +``` + +### 6. Important Notes for AI Assistant + +```markdown +## Important Notes for AI Assistant + +1. **[Critical instruction 1]** +2. **[Critical instruction 2]** +3. **[Critical instruction 3]** +4. ... +``` + +--- + +## Best Practices + +### Writing Effective Instructions + +1. **Be Specific** + - Use exact commands and paths + - Specify file names and locations + - Include expected outputs + +2. **Be Complete** + - Include all necessary steps + - Don't assume prior knowledge + - Provide context for each step + +3. **Be Clear** + - Use simple, direct language + - Avoid ambiguity + - Use examples where helpful + +4. **Be Structured** + - Organize steps logically + - Group related steps into phases + - Number steps sequentially + +5. **Be Validated** + - Include validation for each step + - Provide completion checklist + - Specify success criteria + +### Information Gathering + +1. **List All Requirements** + - Don't assume any information + - Be explicit about what's needed + - Provide format examples + +2. **Explain Why** + - Help users understand why information is needed + - Provide context for requirements + - Show how information will be used + +3. **Provide Examples** + - Give sample values + - Show format requirements + - Include valid/invalid examples + +### Error Handling + +1. **Anticipate Common Errors** + - Think about what could go wrong + - Document likely errors + - Provide clear fixes + +2. **Include Prevention** + - Explain how to avoid errors + - Provide best practices + - Note common pitfalls + +3. **Provide Clear Fixes** + - Step-by-step error resolution + - Explain what each fix does + - Verify fix effectiveness + +--- + +## Writing Effective Instructions + +### Command Instructions + +When providing commands: + +```markdown +1. **Run the command:** + ```bash + git status + ``` + +2. **Verify output:** + - Should show list of modified files + - Should indicate current branch + - Should show no uncommitted changes (if clean) +``` + +### File Operations + +When working with files: + +```markdown +1. **Read the file:** + - Path: `tendril/phases/phase-01-name/blueprint.md` + - Extract: Project name, status, deliverables + +2. **Update the file:** + - Modify: Status field + - Add: New deliverable entry + - Verify: Format is correct +``` + +### Multi-Step Processes + +When breaking down complex tasks: + +```markdown +### Phase 1: Preparation + +1. **Gather information:** + - [What to gather] + - [Where to find it] + - [How to verify it] + +2. **Validate prerequisites:** + - [Check 1] + - [Check 2] + - [Check 3] + +### Phase 2: Execution + +1. **Perform action:** + - [Step 1] + - [Step 2] + - [Step 3] + +2. **Verify results:** + - [Verification 1] + - [Verification 2] +``` + +--- + +## Testing Your Prompt + +### Test Process + +1. **Create the prompt document** + - Follow the structure template + - Include all required sections + - Customize for your task + +2. **Test with a simple case** + - Use minimal, clear inputs + - Verify all steps work + - Check validation checklist + +3. **Test with edge cases** + - Missing information + - Invalid inputs + - Error conditions + +4. **Refine based on results** + - Add missing steps + - Clarify ambiguous instructions + - Improve error handling + +### Testing Checklist + +- [ ] Prompt executes successfully with valid inputs +- [ ] Prompt handles missing information correctly +- [ ] Prompt provides clear error messages +- [ ] Validation checklist is complete +- [ ] All steps are clear and unambiguous +- [ ] Examples are helpful and accurate + +--- + +## Common Patterns + +### Status Check Pattern + +```markdown +# [System] Status Check Prompt + +**Purpose:** Check current status of [system/component] + +## Step-by-Step Process + +### Phase 1: Gather Current State +1. Read [status file] +2. Extract [status indicators] +3. List [current items] + +### Phase 2: Analyze Status +1. Compare with [baseline/expected] +2. Identify [issues/discrepancies] +3. Summarize findings + +### Phase 3: Report +1. Present status summary +2. Highlight issues +3. Suggest next steps +``` + +### Search Pattern + +```markdown +# Search [Content Type] Prompt + +**Purpose:** Search [system] for [content type] matching [criteria] + +## CRITICAL: Information Gathering + +1. **Search criteria** (REQUIRED) + - Format: [format] + - Examples: [examples] + +## Step-by-Step Process + +### Phase 1: Prepare Search +1. Read [index/reference] +2. Identify [search targets] +3. Prepare [search parameters] + +### Phase 2: Execute Search +1. Search by [method 1] +2. Search by [method 2] +3. Combine results + +### Phase 3: Present Results +1. List matches +2. Summarize findings +3. Provide references +``` + +### Sync Pattern + +```markdown +# Synchronize [Documents] Prompt + +**Purpose:** Ensure [documents] are synchronized and consistent + +## Step-by-Step Process + +### Phase 1: Read All Documents +1. Read [document 1] +2. Read [document 2] +3. Read [document 3] + +### Phase 2: Compare and Identify Discrepancies +1. Compare [field 1] across documents +2. Compare [field 2] across documents +3. List all discrepancies + +### Phase 3: Update Documents +1. Update [document 1] with [changes] +2. Update [document 2] with [changes] +3. Verify consistency +``` + +--- + +## When to Create a New Prompt + +### Create a Prompt When: + +1. **Task is Repetitive** + - You find yourself doing the same task multiple times + - Task has clear, repeatable steps + - Task would benefit from standardization + +2. **Task is Complex** + - Task involves multiple phases + - Task requires specific information gathering + - Task has validation requirements + +3. **Task Needs Consistency** + - Different people perform the task + - Task must follow specific rules + - Task has quality requirements + +4. **Task Has Common Errors** + - Task frequently encounters errors + - Errors have known solutions + - Error handling would be helpful + +### Don't Create a Prompt When: + +1. **Task is One-Time** + - Task will only be done once + - Task is highly specific + - Task doesn't need standardization + +2. **Task is Too Simple** + - Task is a single command + - Task requires no validation + - Task has no error handling needs + +3. **Task is Too Variable** + - Task changes significantly each time + - Task has no clear pattern + - Task can't be standardized + +--- + +## Updating Existing Prompts + +### When to Update + +1. **Process Changes** + - Workflow has changed + - New steps are required + - Steps are no longer needed + +2. **Error Discovery** + - New common errors found + - Existing fixes don't work + - Prevention methods needed + +3. **Clarity Improvements** + - Instructions are ambiguous + - Examples are unclear + - Validation is incomplete + +### Update Process + +1. **Test Current Prompt** + - Verify it still works + - Identify issues + - Note improvements needed + +2. **Make Updates** + - Update affected sections + - Maintain structure + - Preserve working parts + +3. **Test Updated Prompt** + - Verify updates work + - Check all sections + - Validate completeness + +4. **Document Changes** + - Note what changed + - Explain why + - Update version/date if applicable + +--- + +## Checklist for New Prompts + +Before considering a prompt complete, verify: + +### Structure +- [ ] Title follows naming convention +- [ ] Purpose is clear and concise +- [ ] "How to Use" section is present +- [ ] Information gathering section is complete +- [ ] Step-by-step process is detailed +- [ ] Error handling section exists +- [ ] Validation checklist is present +- [ ] Important notes section included + +### Content +- [ ] All required information is listed +- [ ] Information formats are specified +- [ ] Examples are provided +- [ ] Steps are clear and unambiguous +- [ ] Validation criteria are specified +- [ ] Common errors are documented +- [ ] Error fixes are provided + +### Quality +- [ ] Instructions are testable +- [ ] Prompt has been tested +- [ ] Examples are accurate +- [ ] Validation checklist is complete +- [ ] Error handling is comprehensive +- [ ] Customized for Tendril project +- [ ] Uses Gitea terminology (not GitHub) + +### Tendril-Specific +- [ ] References "Tendril" (not "pairs") +- [ ] Uses Gitea terminology +- [ ] References correct repository URL +- [ ] Uses Tendril directory structure +- [ ] References Tendril-specific paths + +--- + +## Examples + +### Example 1: Simple Status Check + +```markdown +# Project Status Check Prompt + +**Purpose:** Check current status of all project phases + +**How to Use:** Drag this document into Cursor chat. The AI will read all phase blueprints and provide a status summary. + +## CRITICAL: Information Gathering + +No additional information required. The AI will read phase blueprints automatically. + +## Step-by-Step Process + +### Phase 1: Read Phase Blueprints +1. Find all `blueprint.md` files in `tendril/phases/` +2. Read each blueprint +3. Extract: phase name, status, key deliverables + +### Phase 2: Summarize Status +1. List all phases with status +2. Count: Complete, In Progress, Planned +3. Identify any issues or blockers + +## Validation Checklist +- [ ] All phase blueprints read +- [ ] Status summary provided +- [ ] Phase counts are accurate +``` + +### Example 2: Complex Sync Task + +```markdown +# Phase Documentation Sync Prompt + +**Purpose:** Ensure phase documentation (blueprint, tasks, decisions, changelog) is synchronized + +## CRITICAL: Information Gathering + +1. **Phase name or path** (REQUIRED) + - Format: `phase-XX-name` or full path + - Example: `phase-01-foundation` or `tendril/phases/phase-01-foundation/` + - Why: Need to know which phase to sync + +## Step-by-Step Process + +### Phase 1: Read All Documents +1. Read `blueprint.md` +2. Read `tasks.md` +3. Read `decisions.md` +4. Read `changelog.md` + +### Phase 2: Compare and Identify Discrepancies +1. Compare project name across all documents +2. Compare status indicators +3. Compare deliverables/tasks +4. List all discrepancies + +### Phase 3: Update Documents +1. Update `tasks.md` to match blueprint +2. Update `changelog.md` with sync entry +3. Review `decisions.md` for missing ADRs +4. Verify all documents are consistent + +## Error Handling + +### Phase Directory Not Found +- **Error**: Directory doesn't exist +- **Fix**: Verify phase name/path is correct +- **Prevention**: Use exact phase name from phases directory + +## Validation Checklist +- [ ] All four documents read +- [ ] Discrepancies identified +- [ ] Documents updated +- [ ] Consistency verified +``` + +--- + +## Summary + +Creating effective prompt documents requires: + +1. **Follow the structure template** - Include all required sections +2. **Be specific and complete** - Don't leave room for interpretation +3. **Include validation** - Verify completion at each step +4. **Handle errors** - Anticipate and document common issues +5. **Test thoroughly** - Verify prompt works before using +6. **Customize for Tendril** - Use project-specific context + +**Remember**: Good prompts are reusable, reliable, and reduce errors. Invest time in creating quality prompts to save time in the long run. + +--- + +**Location**: `docs/PROMPTS/Prompt-Creation-Guide.md` +**Related**: +- `docs/PROMPTS/LLM-Usage-Guide.md` +- `docs/GITEA/LLM-Gitea-Guidelines.md` +- `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md` +