Mycelium/tendril
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1423ee1f04b7f386dc70045d13e3374754b89154
tendril/docs/PROMPTS/01-KB-Content-Search-Prompt.md
Gitea Actions 6a4683022f docs(prompts): implement Phase 4 LLM Usage Guides Setup 
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
2025-11-11 12:25:52 -07:00

7.2 KiB
Raw Blame History

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
Reference in New Issue View Git Blame Copy Permalink