tendril/kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md

Phase 4: LLM Usage Guides Setup - Detailed Plan

Objective: Create LLM Usage Guides and prompt documentation system for AI-assisted workflows

Status: Ready for Review
Date: 2025-01-27

---

Overview

Phase 4 establishes the LLM Usage Guides system, which provides reusable prompt documents for AI assistants to perform specific tasks. These guides enable drag-and-drop workflows in Cursor chat and standardize common operations.

---

Current State

• docs/PROMPTS/ directory exists (created in Phase 0)
• Phase documentation system established (Phase 1)
• KB system established (Phase 2)
• Gitea Actions workflows established (Phase 3)
• Missing: LLM Usage Guide, Prompt Creation Guide, initial prompt documents

---

Tasks Breakdown

Task 1: Create LLM Usage Guide

File: docs/PROMPTS/LLM-Usage-Guide.md

Create comprehensive guide for LLMs on how to recognize, interpret, and execute prompt documents:

Purpose: Instructions for AI assistants on working with prompt documents

Key Sections:

• Recognizing Prompt Documents
• Executing Prompts (Phase-by-Phase Execution)
• Information Gathering
• Error Handling
• Validation Steps
• Providing Feedback
• Best Practices
• Special Instructions
• Troubleshooting

Source: Template from kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md (LLM Usage Guides section, lines 1510-1524)

Content Structure:

• How to identify prompt documents (naming convention, structure)
• Step-by-step execution process
• Information gathering requirements
• Error handling procedures
• Validation checklists
• Feedback mechanisms
• Best practices for prompt execution

Customizations:

• Reference Tendril project structure
• Use Gitea terminology (not GitHub)
• Reference Tendril-specific paths and conventions

---

Task 2: Create Prompt Creation Guide

File: docs/PROMPTS/Prompt-Creation-Guide.md

Create guide for creating effective, reusable prompt documents:

Purpose: Guide for creating effective, reusable prompt documents

Key Sections:

• Naming Convention (NN-Descriptive-Name-Prompt.md)
• Prompt Structure Template
• Best Practices
• Writing Effective Instructions
• Testing Your Prompt
• Common Patterns
• When to Create a New Prompt
• Updating Existing Prompts
• Checklist for New Prompts

Source: Template from kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md (LLM Usage Guides section, lines 1526-1540)

Content Structure:

• Naming convention explanation (zero-padded numbers)
• Complete prompt template structure
• Best practices for clarity and effectiveness
• Writing guidelines for instructions
• Testing procedures
• Common patterns and examples
• Decision criteria for new prompts
• Update procedures
• Validation checklist

Customizations:

• Examples relevant to Tendril project
• Reference Tendril-specific workflows
• Use Gitea terminology

---

Task 3: Create Initial Prompt Documents

Files: Create at least one initial prompt document to demonstrate the system

Naming Convention: NN-Descriptive-Name-Prompt.md where NN is zero-padded two-digit number (00, 01, 02, etc.)

Suggested Initial Prompts:

1. 00-Project-Status-Check-Prompt.md

   • Purpose: Check current project status across all phases
   • Use case: Quick status overview before starting work
   • Steps: Read phase blueprints, check tasks, summarize status

2. 01-KB-Content-Search-Prompt.md

   • Purpose: Search KB system for relevant content
   • Use case: Find existing knowledge before creating new KB entries
   • Steps: Read KB index, search by topic/tag/phase, summarize findings

3. 02-Phase-Documentation-Sync-Prompt.md

   • Purpose: Ensure phase documentation is synchronized
   • Use case: After editing blueprint, verify all related docs are updated
   • Steps: Check blueprint, tasks, decisions, changelog for consistency

Prompt Structure (from template):

• Purpose statement
• How to use instructions
• CRITICAL: Information Gathering section
• Step-by-Step Process
• Error Handling
• Validation Checklist
• Important Notes for AI Assistant

Source: Template from kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md (Prompt Document Template, lines 1429-1508)

---

Customizations for Tendril

Directory Structure

• Use: docs/PROMPTS/ (already exists)
• Reason: Matches project structure

Platform References

• Use: "Gitea" (not "GitHub")
• Reference: Gitea-specific workflows and features
• Note: Gitea Actions compatibility where relevant

Project Context

• Project Name: Tendril
• Repository: https://git.parkingmeter.info/Mycelium/tendril
• Phase Structure: tendril/phases/phase-XX-name/
• KB Structure: kb/ with category directories

Prompt Examples

• Reference Tendril-specific workflows
• Use Tendril project structure in examples
• Include Gitea-specific operations where relevant

---

Files to Create

1. docs/PROMPTS/LLM-Usage-Guide.md - LLM instructions for prompt execution
2. docs/PROMPTS/Prompt-Creation-Guide.md - Guide for creating prompts
3. docs/PROMPTS/00-Project-Status-Check-Prompt.md - Initial prompt (optional but recommended)
4. docs/PROMPTS/01-KB-Content-Search-Prompt.md - Initial prompt (optional but recommended)
5. docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md - Initial prompt (optional but recommended)

Note: At minimum, create the two guide files. Initial prompt documents are recommended but optional.

---

Dependencies

• Phase 0: Directory structure (completed)
• Phase 1: Phase documentation system (completed)
• Phase 2: KB System Setup (completed)
• Phase 3: Gitea Actions Workflows (completed)
• docs/PROMPTS/ directory exists

---

Success Criteria

• LLM Usage Guide created and comprehensive
• Prompt Creation Guide created with complete template
• At least one initial prompt document created (recommended)
• All files customized for Tendril project
• Documentation references Gitea (not GitHub)
• Prompts follow naming convention
• Prompts include all required sections

---

Validation Checklist

Before completing Phase 4, verify:

• docs/PROMPTS/LLM-Usage-Guide.md exists and is complete
• docs/PROMPTS/Prompt-Creation-Guide.md exists and is complete
• At least one initial prompt document created (recommended)
• All prompts follow naming convention: NN-Descriptive-Name-Prompt.md
• All prompts include required sections (Purpose, How to Use, Information Gathering, Steps, Validation)
• All files reference "Tendril" (not "pairs")
• All files use "Gitea" terminology (not "GitHub")
• Examples are relevant to Tendril project structure
• Documentation is clear and actionable

---

Testing Prompts

Test LLM Usage Guide

1. Open a prompt document in Cursor
2. Verify LLM recognizes it as a prompt document
3. Test execution of a simple prompt
4. Verify LLM follows instructions correctly

Test Prompt Creation Guide

1. Create a new prompt using the guide
2. Verify it follows naming convention
3. Verify it includes all required sections
4. Test the prompt with an LLM
5. Verify it accomplishes intended task

---

Next Steps After Phase 4

Once Phase 4 is complete:

• Phase 5: Validation and Testing
• Phase 6: Customization and Final Verification

---

Notes

• LLM Usage Guides enable reusable, standardized workflows
• Prompts should be tested with actual LLM execution
• Prompt documents are designed for drag-and-drop use in Cursor
• Initial prompts serve as examples and useful tools
• All prompts should be customized for Tendril project context
• Consult docs/GITEA/LLM-Gitea-Guidelines.md for Gitea-specific LLM guidance

---

Location: kb/_guides/PROJECT-SETUP-GUIDE/PHASE-4-PLAN.md
Related:

• kb/_guides/PROJECT-SETUP-GUIDE/COMPLETE-SYSTEM-REPLICATION-GUIDE.md
• docs/GITEA/LLM-Gitea-Guidelines.md
• docs/PROMPTS/ directory