markitect-main/guides/Working_With_Issues_GUIDE.md

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