5b8bf621305f0bc752c43813fea9d3460b91b373
1 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
| aecc370e1d |
docs(kb): implement Phase 2 KB System Setup
This commit implements the complete Knowledge Base (KB) system for the Tendril
project, establishing a structured, LLM-friendly system for capturing and
organizing external information that informs project development.
## What Was Implemented
### 1. KB System Documentation (kb/README.md)
- Comprehensive documentation explaining the KB system's purpose and structure
- Directory structure explanation with all 8 category directories
- File naming schema: YYYY-MM-DD--slug--type.md with regex validation
- Complete frontmatter schema documentation (18 required fields for Tendril)
- Routing decision tree for categorizing content
- Routing confidence system (0.00-1.00 scale) with policy for low-confidence items
- Usage guidelines for creating and managing KB files
- Integration notes with phase documentation system
- Index generation and changelog update procedures
### 2. KB File Templates (kb/_templates/)
Created three template files with complete frontmatter:
- note.md: General notes template with draft status default
- decision.md: ADR-style decision template with active status default
- howto.md: How-to guide template with active status default
All templates include:
- All 18 required frontmatter fields (base + Tendril-specific)
- Placeholder syntax (${VARIABLE}) for easy customization
- Appropriate default values (routing_confidence, status, etc.)
- Template-specific content sections
- Customized for Tendril project (project: ["tendril"])
### 3. KB Ingestion Prompt (kb/_guides/KB_INGEST_PROMPT.md)
Complete system prompt for LLM-assisted KB ingestion:
- System instructions for content analysis and routing
- Classification and routing rules for all 8 categories
- Routing decision tree with 9-step decision process
- Routing confidence assessment guidelines
- File naming standards with examples and validation
- Complete frontmatter requirements documentation
- JSON output format specification
- Quality and style guidelines
- Safety constraints (NEVER/ALWAYS rules)
- Validation checklist
- Completion summary format with mandatory index/changelog updates
### 4. Index Generation Script (kb/scripts/generate-index.sh)
Bash script for automatic KB index generation:
- Scans all KB files in category directories (01_projects through 08_archive)
- Excludes special directories (_guides, _templates, _inbox, _review_queue)
- Extracts YAML frontmatter from each KB file
- Parses metadata fields (title, date, type, summary, topics, tags, phases)
- Generates kb/_index.md with:
* File listing organized by category
* Topics index (all unique topics with file references)
* Tags index (all unique tags with file references)
* Phase relevance index (files organized by phase)
* Summary statistics
- Compatible with Windows (Git Bash) and Unix systems
- Uses temporary files for cross-platform compatibility
- Handles errors gracefully (missing frontmatter, invalid files)
- Script is executable (chmod +x)
### 5. KB Changelog (kb/CHANGELOG.md)
Change tracking for KB system:
- Initial entry documenting Phase 2 setup
- Date-based format: ## [YYYY-MM-DD] KB System Setup
- Lists all files created during setup
- Notes about customization for Tendril project
### 6. Initial Index (kb/_index.md)
Auto-generated searchable index:
- Generated by running generate-index.sh
- Currently empty (no KB files exist yet)
- Ready to be populated as KB files are added
- Includes proper structure for all index sections
## Why This Implementation
### Structured Knowledge Capture
The KB system provides a lightweight staging area for external information
(Pulse Daily chats, ideas, notes, research) that may inform Tendril project
development. Unlike formal phase documentation, KB entries capture informal
knowledge that complements the structured phase blueprints.
### LLM-Friendly Design
The system is designed for LLM-assisted ingestion and management:
- Clear routing decision tree enables automated classification
- Confidence scoring allows human review of uncertain routing
- Complete frontmatter ensures rich metadata for searchability
- JSON output format enables automated file creation
### Searchability and Discovery
The automatic index generation creates multiple access paths:
- By category (for browsing related content)
- By topic (for finding content on specific subjects)
- By tag (for cross-cutting categorization)
- By phase relevance (for finding content related to specific phases)
### Integration with Phase Documentation
KB decisions complement phase-specific ADRs, KB research informs phase
planning, and KB playbooks provide operational guides. The phase_relevance
field creates explicit links between KB content and project phases.
### Project Customization
All files are customized for Tendril:
- Project name: "tendril" (replaced "pairs" references)
- Default project field: ["tendril"]
- Path references updated for Tendril structure
- Gitea Actions noted (not GitHub Actions) for Phase 3
## Technical Details
### Frontmatter Schema (18 Fields)
Base fields (14): title, date, author, source, project, topics, tags, type,
status, routing_hint, proposed_path, routing_confidence, related, summary
Tendril-specific (4): captured_at, source_type, related_projects,
phase_relevance
Optional (2): key_takeaways, action_candidates
### File Naming Pattern
Regex: ^\d{4}-\d{2}-\d{2}--[a-z0-9-]{3,}--(idea|note|spec|decision|howto|retro|meeting)(--p[0-9]+)?\.md$
Components: Date (YYYY-MM-DD) + Slug (3-8 words, no stop-words) + Type
### Routing Confidence Policy
- >= 0.60: File goes to proposed_path
- < 0.60: File goes to _review_queue/ (with proposed_path in frontmatter)
## Next Steps
Phase 2 complete. Ready for Phase 3: Gitea Actions Workflows configuration.
## Files Added
- kb/README.md (290 lines)
- kb/_templates/note.md
- kb/_templates/decision.md
- kb/_templates/howto.md
- kb/_guides/KB_INGEST_PROMPT.md (~400 lines)
- kb/scripts/generate-index.sh (executable)
- kb/CHANGELOG.md
- kb/_index.md (auto-generated)
|
