diff --git a/ISSUE_WORKFLOW_REMINDER.md b/ISSUE_WORKFLOW_REMINDER.md new file mode 100644 index 00000000..64e1d02c --- /dev/null +++ b/ISSUE_WORKFLOW_REMINDER.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. \ No newline at end of file diff --git a/RelevantClaudeIssues.md b/RelevantClaudeIssues.md index 24d41167..6191a0d5 100644 --- a/RelevantClaudeIssues.md +++ b/RelevantClaudeIssues.md @@ -16,6 +16,9 @@ This document tracks Claude Code issues that directly impact our development wor - Remove resolved issues after confirming fixes work in our environment - Maintained by the claude-expert subagent as part of issue tracking responsibilities +**🎯 CRITICAL WORKFLOW REMINDER:** +When discussing project issues (not Claude Code issues), ALWAYS fetch from Gitea first. Gitea is the source of truth for all issue assessment, feasibility evaluation, and implementation planning. Local files are insufficient for decision-making about issues. See ISSUE_WORKFLOW_REMINDER.md for complete workflow. + --- ## Resolved Issues