chore: history cleanup

guides/Working_With_Issues_GUIDE.md

@@ -0,0 +1,71 @@
+# Issue Management Workflow Reminder
+
+## 🎯 CRITICAL REMINDER: Gitea is the Source of Truth
+
+**PRIMARY RULE**: When discussing issues for assessment, feasibility evaluation, prioritization, or implementation planning, ALWAYS fetch the issue directly from Gitea.
+
+## When to Fetch from Gitea
+
+### ✅ Always Fetch from Gitea When:
+- Assessing feasibility of an issue
+- Deciding if we should implement an issue next
+- Refining issue requirements or scope
+- Evaluating whether to drop an issue
+- Discussing implementation strategy
+- Planning issue priority
+- Issue is not currently in the working directory
+- Issue has been implemented before but needs review
+
+### ⚠️ Local Files Are Insufficient For:
+- Issue assessment discussions
+- Implementation planning
+- Priority evaluation
+- Scope refinement
+- Feasibility analysis
+
+## Source of Truth Hierarchy
+
+1. **Gitea Repository** - Primary datastore for all issues
+2. **Working Directory** - Only for issues currently being implemented
+3. **Local Index/Cache** - For quick reference only, not decision-making
+
+## Proper Workflow
+
+```bash
+# When discussing Issue #46 (or any issue number):
+1. Use WebFetch or GitLab/Gitea tools to fetch the live issue
+2. Read the current state, comments, and requirements
+3. Base all decisions on the live Gitea data
+4. Do NOT rely on local files, cached data, or assumptions
+```
+
+## Implementation Commands
+
+```bash
+# ✅ WORKING: Use existing Makefile targets
+make show-issue NUM=46         # Show detailed issue #46
+make list-issues              # List all issues with status
+make list-open-issues         # Show only open issues
+
+# ✅ WORKING: Export for analysis
+make issues-get               # Export compact TSV to ISSUES.index
+make issues-json              # Export all issues as JSON
+make issues-csv               # Export as CSV for spreadsheet analysis
+make issues-high              # Export only high/critical priority
+
+# ❌ NOT AVAILABLE: These require additional tools
+gh issue view 46 --repo your-repo
+WebFetch "https://gitea-instance/repo/issues/46"  # (certificate issues)
+```
+
+## Why This Matters
+
+- **Accuracy**: Issues may have been updated, refined, or closed
+- **Completeness**: Comments and discussions provide crucial context
+- **Current State**: Status, labels, and priority may have changed
+- **Team Collaboration**: Other team members may have added insights
+- **Implementation History**: Previous attempts or decisions are documented
+
+---
+
+**🚨 REMINDER TO CLAUDE**: Before discussing any issue assessment, feasibility, or planning, ALWAYS fetch the issue from Gitea first. Local files are NOT sufficient for decision-making about issues.