# Issues Capture System

_Quick capture system for potential insights, problems, structural changes, bugs, and features_

---

## Purpose

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.

**Key Benefits:**
- ⚡ **Quick capture** - Minimal fields, fast to fill out
- 📝 **Markdown-based** - Easy to edit and version control
- 🔄 **Later compilation** - Can be batch-processed into Gitea issues
- 📊 **Searchable** - All issues in one place, easy to review

---

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

Use format: `YYYY-MM-DD--short-description.md`

Examples:
- `2025-11-11--gitea-runner-setup.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
- **Description** - What the issue/idea is
- **Impact** - Why it matters (optional)
- **Notes** - Additional context (optional)

Keep it simple - you can always add more detail later when creating the Gitea issue.

---

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

---

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

---

## Platform Notes

**Gitea-Specific:**
- Repository: https://git.parkingmeter.info/Mycelium/tendril
- Platform: Gitea (self-hosted)
- Issues: Gitea issues (compatible with GitHub issues format)
- See `docs/GITEA/Gitea-Basics.md` for Gitea-specific guidance

---

**Location**: `docs/issues/`  
**Related**: 
- `docs/GITEA/Gitea-Basics.md` - Gitea platform basics
- `docs/GITEA/Gitea-Workflows.md` - Gitea workflows and best practices