---
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`