docs: add issues capture system and KB documentation
Some checks failed
KB Lint / validate (push) Has been cancelled
Some checks failed
KB Lint / validate (push) Has been cancelled
This commit adds the issues capture system from PAIRS project and documents it in the KB system, following all KB system rules for changelog and index updates. ## What Was Added ### 1. Issues Capture System (docs/issues/) **docs/issues/README.md** - System documentation: - Purpose and workflow for quick issue capture - File naming convention (YYYY-MM-DD--short-description.md) - Issue types (bug, feature, insight, structural, improvement, question) - Template fields and best practices - Integration with Gitea platform - Future automation possibilities **docs/issues/template.md** - Issue file template: - Minimal required fields (title, type, date, status) - Optional fields (description, impact, notes, related) - Gitea issue tracking section - Simple, quick-capture format **docs/issues/2025-11-11--gitea-runner-setup-request.md** - Moved from .github/: - Gitea Actions runner configuration request - Updated to match issue template format - Includes type, date, status fields - Ready for compilation to Gitea issue ### 2. KB Documentation Entry **kb/02_systems/2025-11-11--issues-capture-system--note.md** - KB entry: - Documents the issues capture system structure and workflow - Explains quick capture process - Describes compilation to Gitea issues - Includes best practices and integration points - Properly categorized in 02_systems/ (infrastructure/tooling) - Complete frontmatter with all 18 required fields ### 3. KB System Updates **kb/CHANGELOG.md** - Updated: - Added entry for issues capture system documentation - Date: 2025-11-11 - Documents KB file addition **kb/_index.md** - Regenerated: - Index updated via generate-index.sh script - New KB file appears in 02_systems category - Topics indexed: documentation, issue-tracking, workflow, gitea - Tags indexed: issues, capture, documentation, gitea, workflow - Summary updated with file count ## Why This Implementation ### Quick Issue Capture The issues capture system provides a lightweight staging area for capturing issues, insights, bugs, and features as you encounter them. This enables quick capture without the overhead of creating formal Gitea issues immediately. ### Markdown-Based Workflow Issues are captured as markdown files, making them easy to edit, version control, and review. This provides flexibility before committing to formal issue tracking. ### Later Compilation Issues can be batch-processed into Gitea issues when ready, allowing for review, prioritization, and grouping before creating formal issues. ### Documentation in KB The issues capture system is documented in the KB system, making it discoverable and providing reference material for the workflow. ## Technical Details ### File Structure ### Issue File Format - **Naming**: - **Template**: Minimal fields for quick capture - **Status**: captured → reviewed → compiled - **Integration**: Links to Gitea issues when compiled ### KB Entry Details - **Category**: 02_systems (infrastructure, DevOps, tooling) - **Type**: note - **Topics**: documentation, issue-tracking, workflow, gitea - **Tags**: issues, capture, documentation, gitea, workflow - **Routing Confidence**: 0.95 (high confidence) ## Files Added/Modified ### Added - docs/issues/README.md - Issues capture system documentation - docs/issues/template.md - Issue file template - docs/issues/2025-11-11--gitea-runner-setup-request.md - Runner setup request (moved from .github/) - kb/02_systems/2025-11-11--issues-capture-system--note.md - KB documentation entry ### Modified - kb/CHANGELOG.md - Added entry for new KB file - kb/_index.md - Regenerated with new KB file indexed ## KB System Compliance ✅ KB file follows naming convention (YYYY-MM-DD--slug--type.md) ✅ KB file has complete frontmatter (all 18 required fields) ✅ KB file date matches filename date ✅ KB file type matches filename type ✅ KB changelog updated with entry ✅ KB index regenerated via script ✅ All changes committed together ## Related - Source: PAIRS-for-the-Individual project (docs/issues/) - KB System: kb/README.md - KB Changelog: kb/CHANGELOG.md - KB Index: kb/_index.md - Gitea Documentation: docs/GITEA/
This commit is contained in:
Gitea Actions
163
kb/02_systems/2025-11-11--issues-capture-system--note.md
Normal file
163
kb/02_systems/2025-11-11--issues-capture-system--note.md
Normal file
@@ -0,0 +1,163 @@
|
||||
---
|
||||
title: "Issues Capture System Documentation"
|
||||
date: "2025-11-11"
|
||||
captured_at: "2025-11-11"
|
||||
author: ["datawarrior"]
|
||||
source: { kind: chat, ref: "issues-folder-setup" }
|
||||
source_type: chat
|
||||
project: ["tendril"]
|
||||
related_projects: ["tendril"]
|
||||
topics: ["documentation", "issue-tracking", "workflow", "gitea"]
|
||||
tags: ["issues", "capture", "documentation", "gitea", "workflow"]
|
||||
type: note
|
||||
status: draft
|
||||
phase_relevance: []
|
||||
routing_hint: "Documentation about issues capture system folder structure"
|
||||
proposed_path: "kb/02_systems/"
|
||||
routing_confidence: 0.95
|
||||
related: []
|
||||
summary: "Documentation for the issues capture system in docs/issues/ folder. Provides quick capture workflow for issues, insights, bugs, and features before compiling into Gitea issues."
|
||||
key_takeaways: []
|
||||
action_candidates: []
|
||||
---
|
||||
|
||||
# Issues Capture System
|
||||
|
||||
## Overview
|
||||
|
||||
The `docs/issues/` folder is a lightweight staging area for capturing issues, ideas, and problems as you encounter them. These markdown files can be quickly created and filled out, then later compiled into actual Gitea issues for project boards.
|
||||
|
||||
## Purpose
|
||||
|
||||
**Quick capture system** for:
|
||||
- Potential insights
|
||||
- Problems and bugs
|
||||
- Structural changes
|
||||
- Feature ideas
|
||||
- Questions to investigate
|
||||
|
||||
## Location
|
||||
|
||||
**Folder**: `docs/issues/`
|
||||
|
||||
**Files**:
|
||||
- `README.md` - System documentation and workflow
|
||||
- `template.md` - Template for creating new issue files
|
||||
- `YYYY-MM-DD--short-description.md` - Individual issue files
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Quick Capture
|
||||
|
||||
When you encounter an issue, insight, bug, or feature idea:
|
||||
|
||||
1. Copy `template.md` to create a new issue file
|
||||
2. Use filename format: `YYYY-MM-DD--short-description.md`
|
||||
3. Fill out the minimal required fields
|
||||
4. Save and commit
|
||||
|
||||
### 2. Regular Review
|
||||
|
||||
Periodically review issues in this folder:
|
||||
- Group related issues
|
||||
- Prioritize by impact
|
||||
- Identify patterns or themes
|
||||
|
||||
### 3. Compilation to Gitea Issues
|
||||
|
||||
When ready to create actual Gitea issues:
|
||||
- Review all issues in this folder
|
||||
- Create Gitea issues from the markdown files
|
||||
- Link back to the original markdown file
|
||||
- Optionally archive or move processed issues
|
||||
|
||||
## File Naming Convention
|
||||
|
||||
Format: `YYYY-MM-DD--short-description.md`
|
||||
|
||||
**Examples**:
|
||||
- `2025-11-11--gitea-runner-setup-request.md`
|
||||
- `2025-11-11--add-mentions-field.md`
|
||||
- `2025-11-11--kb-routing-improvement.md`
|
||||
|
||||
## Issue Types
|
||||
|
||||
Use the `type` field in the template to categorize:
|
||||
|
||||
- **bug** - Something broken or not working correctly
|
||||
- **feature** - New functionality or enhancement
|
||||
- **insight** - Observation or pattern noticed
|
||||
- **structural** - Changes to project structure or architecture
|
||||
- **improvement** - Enhancement to existing functionality
|
||||
- **question** - Something to investigate or clarify
|
||||
|
||||
## Template Fields
|
||||
|
||||
The template includes minimal required fields:
|
||||
|
||||
- **Title** - Brief, descriptive title
|
||||
- **Type** - Category (bug, feature, insight, etc.)
|
||||
- **Date** - When issue was captured
|
||||
- **Status** - captured|reviewed|compiled
|
||||
- **Description** - What the issue/idea is
|
||||
- **Impact** - Why it matters (optional)
|
||||
- **Notes** - Additional context (optional)
|
||||
- **Related** - Links to related files, issues, or documentation (optional)
|
||||
- **Gitea Issue** - Link to created Gitea issue (when compiled)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Capture quickly** - Don't overthink, just get it down
|
||||
2. **One issue per file** - Makes compilation easier
|
||||
3. **Use descriptive filenames** - Helps with search and review
|
||||
4. **Add context** - Include enough detail to remember later
|
||||
5. **Review regularly** - Don't let issues pile up indefinitely
|
||||
|
||||
## Integration with Gitea
|
||||
|
||||
**Platform**: Gitea (self-hosted)
|
||||
**Repository**: https://git.parkingmeter.info/Mycelium/tendril
|
||||
**Issues**: Gitea issues (compatible with GitHub issues format)
|
||||
|
||||
When compiling to Gitea issues:
|
||||
- Use Gitea issue creation workflow
|
||||
- Link back to original markdown file
|
||||
- Update issue file with Gitea issue URL
|
||||
- Change status to "compiled"
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- `docs/issues/README.md` - Complete system documentation
|
||||
- `docs/issues/template.md` - Issue file template
|
||||
- `docs/GITEA/Gitea-Basics.md` - Gitea platform basics
|
||||
- `docs/GITEA/Gitea-Workflows.md` - Gitea workflows and best practices
|
||||
|
||||
## Future Automation
|
||||
|
||||
Potential enhancements:
|
||||
- Script to batch-create Gitea issues from markdown files
|
||||
- Gitea Actions workflow to auto-create issues on file creation
|
||||
- Integration with project boards
|
||||
- Automated categorization and tagging
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- Lightweight staging area for issue capture
|
||||
- Markdown-based for easy editing and version control
|
||||
- Quick capture workflow with minimal fields
|
||||
- Later compilation into Gitea issues
|
||||
- Searchable and organized in one location
|
||||
|
||||
## Action Candidates
|
||||
|
||||
- Review existing issues in `docs/issues/` folder
|
||||
- Create Gitea issues from captured issues
|
||||
- Set up automation for issue compilation (if desired)
|
||||
- Document issue compilation workflow
|
||||
|
||||
---
|
||||
|
||||
**Location**: `docs/issues/`
|
||||
**Documentation**: `docs/issues/README.md`
|
||||
**Template**: `docs/issues/template.md`
|
||||
|
||||
@@ -2,6 +2,18 @@
|
||||
|
||||
All notable changes to KB files and system.
|
||||
|
||||
## [2025-11-11] Issues Capture System Documentation
|
||||
|
||||
### Added
|
||||
- `kb/02_systems/2025-11-11--issues-capture-system--note.md` - Documentation for issues capture system in docs/issues/ folder
|
||||
|
||||
### Notes
|
||||
- Documents the issues capture system workflow and structure
|
||||
- Provides reference for quick issue capture before compiling to Gitea issues
|
||||
- Includes integration with Gitea platform and best practices
|
||||
|
||||
---
|
||||
|
||||
## [2025-01-27] KB System Setup
|
||||
|
||||
### Added
|
||||
|
||||
66
kb/_index.md
66
kb/_index.md
@@ -8,13 +8,71 @@ This index is automatically generated from KB file metadata. It provides searcha
|
||||
|
||||
## File Listing by Category
|
||||
|
||||
### 01_projects
|
||||
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md) - Test KB Workflow Validation (2025-11-11, note)
|
||||
|
||||
### 02_systems
|
||||
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md) - Issues Capture System Documentation (2025-11-11, note)
|
||||
|
||||
## Topics Index
|
||||
|
||||
### documentation
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### gitea
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### issue-tracking
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### kb-system
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
### testing
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
### workflow
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### workflows
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
## Tags Index
|
||||
|
||||
### capture
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### documentation
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### gitea
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### issues
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
### temporary
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
### test
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
### validation
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
|
||||
### workflow
|
||||
- [`01_projects/tendril/2025-11-11--test-kb-workflow--note.md`](01_projects/tendril/2025-11-11--test-kb-workflow--note.md)
|
||||
- [`02_systems/2025-11-11--issues-capture-system--note.md`](02_systems/2025-11-11--issues-capture-system--note.md)
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
- **Total KB Files**: 0
|
||||
- **Unique Topics**: 0
|
||||
- **Unique Tags**: 0
|
||||
- **Total KB Files**: 2
|
||||
- **Unique Topics**: 7
|
||||
- **Unique Tags**: 8
|
||||
- **Phases Referenced**: 0
|
||||
|
||||
_Index generated on 2025-11-11 11:53:11_
|
||||
_Index generated on 2025-11-11 12:30:43_
|
||||
|
||||
Reference in New Issue
Block a user