Debug Issues from ISSUES.md - Protocol-Enforced Workflow

Purpose: Systematic workflow for debugging and fixing issues from ISSUES.md with mandatory conflict prevention and proper archival.

When This Skill Activates

This skill activates when:

• User asks to fix/debug an issue from ISSUES.md
• User says "work on [issue]" or "fix [issue]"
• User asks "what issues are active" or "check ISSUES.md"
• You're about to start debugging any issue tracked in ISSUES.md

Core Protocol (MANDATORY)

Step 1: ALWAYS Check for Conflicts FIRST

Before starting ANY issue, you MUST run:

grep -A 5 "\[IN PROGRESS\]" ISSUES.md

Decision Tree:

• ✅ No [IN PROGRESS] found → Proceed to Step 2
• ⏸️ [IN PROGRESS] found + timestamp < 2 hours → STOP - Ask user: "Issue '[Title]' is currently being worked on (started X minutes ago). Should I take over or work on a different issue?"
• ❓ [IN PROGRESS] found + timestamp > 2 hours → ASK USER: "Found stale in-progress issue '[Title]' (started X hours ago). Should I take over?"
• 🔄 Different issue in progress → You may work on a different issue

Example Output:

✅ No active issues found - you may proceed

OR

⚠️ Found active work:
### [IN PROGRESS] Play button not working
**Started**: 2025-10-27 14:30 UTC (45 minutes ago)

STOP: Ask user if you should take over

---

Step 2: Mark Issue as [IN PROGRESS]

When you START work, IMMEDIATELY update ISSUES.md:

### [IN PROGRESS] {Issue Title}

**Status**: In Progress
**Started**: {YYYY-MM-DD HH:MM UTC}
**Todo Tracking**: See todo list below

**Original Issue**:
{Copy original issue description here}

**Current Progress**:

- ⏳ {First task you're working on}

Critical:

• Add this marker IMMEDIATELY when starting, not later
• Use UTC timestamp (get with date -u +"%Y-%m-%d %H:%M UTC")
• Create TodoWrite list and reference it

Example:

### [IN PROGRESS] Video export fails for large files

**Status**: In Progress
**Started**: 2025-10-27 15:30 UTC
**Todo Tracking**: 5 tasks

**Original Issue**:
Users report video export fails when file size exceeds 500MB.
Error message: "Export timeout after 60 seconds"

**Current Progress**:

- ⏳ Investigating export API endpoint and timeout settings
- [ ] Check memory limits in Vercel
- [ ] Test with large sample file
- [ ] Implement streaming export
- [ ] Validate fix in production

---

Step 3: Work on Issue with Updates

CRITICAL: Check Axiom/Sentry First (MANDATORY)

Before investigating code, ALWAYS check production logs:

# 1. Query Axiom for recent errors related to the issue
# Use Axiom MCP tool: mcp__axiom__queryApl()
# Example: ['logs'] | where ['_time'] > ago(1h) | where ['severity'] == "error"

# 2. Check Sentry for stack traces
npx sentry-cli issues list --status unresolved --limit 20

Why: Production logs reveal the actual errors users are experiencing, saving investigation time and preventing fixing symptoms instead of root causes.

While working, update the Current Progress section:

**Current Progress**:

- ✅ Investigated export API - found 60s timeout hardcoded
- ✅ Tested with 1GB file - confirmed timeout issue
- ⏳ Implementing chunked streaming export
- [ ] Validate fix in production
- [ ] Update documentation

Status Markers:

• ✅ = Completed
• ⏳ = Currently working on
• = Not started yet
• ❌ = Blocked/failed

Update TodoWrite in parallel to keep both in sync.

---

Step 4: Complete and Archive (MANDATORY)

When issue is RESOLVED, you MUST:

1. Remove entire issue section from ISSUES.md
2. Archive to /docs/reports/ISSUES_RESOLVED.md

Archive Format:

## {Issue Title} - RESOLVED

**Resolved**: {YYYY-MM-DD HH:MM UTC}
**Root Cause**: {Clear explanation of what caused the issue}
**Solution**: {What was implemented to fix it}

**Files Modified**:

- {path/to/file1.ts} - {what changed}
- {path/to/file2.tsx} - {what changed}

**Testing**: {How you verified the fix works}

**Commits**: {commit-hash1, commit-hash2}

**Reference**: [Detailed investigation if needed]

---

Example Archive Entry:

## Video export fails for large files - RESOLVED

**Resolved**: 2025-10-27 16:45 UTC
**Root Cause**: Export API had hardcoded 60-second timeout, insufficient for files >500MB.

**Solution**:

- Implemented chunked streaming export with progress tracking
- Increased timeout to 300 seconds
- Added retry logic for failed chunks

**Files Modified**:

- `app/api/export/route.ts` - Added streaming export logic
- `lib/export/videoExporter.ts` - Implemented chunk processing
- `components/export/ExportProgress.tsx` - Added chunk progress UI

**Testing**:

- Tested with 1GB file - export succeeded in 2 minutes
- Verified progress tracking shows chunk status
- Confirmed no memory issues in Vercel logs

**Commits**: 57c140c4, a5ac17b3

---

CRITICAL:

• Issue MUST be removed from ISSUES.md (entire section)
• Archive MUST be appended to ISSUES_RESOLVED.md (at the top, newest first)
• Include ALL context: root cause, solution, files, testing, commits

---

Step 5: If Issue Paused/Blocked

If you must stop work before completion:

### {Issue Title}

**Status**: Paused - {Reason}
**Last Updated**: {YYYY-MM-DD HH:MM UTC}
**Previous Session**: {when work started}

**Original Issue**:
{Issue description}

**Investigation So Far**:

- ✅ {What was completed}
- ⏳ {What was in progress when paused}
- ❌ {What blocked progress}

**Next Steps**:

- {What should be done when resuming}

Key: Remove [IN PROGRESS] marker but keep issue in ISSUES.md

---

Complete Workflow Example

Scenario: User says "Fix the timeline export bug"

Phase 1: Check Conflicts

# Run this FIRST
grep -A 5 "\[IN PROGRESS\]" ISSUES.md

# Output: ✅ No active issues found

Phase 2: Read ISSUES.md and Identify Issue

cat ISSUES.md | grep -A 10 "timeline export"

Phase 3: Mark In Progress

Edit ISSUES.md:

### [IN PROGRESS] Timeline export generating corrupted files

**Status**: In Progress
**Started**: 2025-10-27 15:30 UTC
**Todo Tracking**: 4 tasks

**Original Issue**:
Timeline export generates MP4 files that won't play in VLC.
File size looks correct but video players report "corrupted file"

**Current Progress**:

- ⏳ Checking Axiom/Sentry logs for export errors

Phase 4: Check Axiom/Sentry (MANDATORY)

# Query Axiom for export-related errors
mcp__axiom__queryApl({
  query: "['logs'] | where ['_time'] > ago(24h) | where ['message'] contains 'export' and ['severity'] == 'error'"
})

# Check Sentry for stack traces
npx sentry-cli issues list --status unresolved | grep -i export

Found: FFmpeg errors showing missing keyframe interval parameter

Phase 5: Create Todo List

TodoWrite:

- [ ] Analyze Axiom/Sentry findings
- [ ] Check export codec configuration
- [ ] Review FFmpeg settings
- [ ] Test with various timeline lengths
- [ ] Implement fix and validate

Phase 6: Investigate and Fix

Update ISSUES.md as work progresses:

**Current Progress**:

- ✅ Analyzed logs - found missing keyframe interval in FFmpeg
- ✅ Checked codec settings - using H.264 correctly
- ✅ Found issue: Missing keyframe interval parameter
- ⏳ Implementing fix with proper keyframe settings
- [ ] Validate fix with test exports

Phase 7: Test and Verify

**Current Progress**:

- ✅ Implemented keyframe interval fix
- ✅ Tested exports - files play correctly in VLC
- ✅ Verified in production environment
- ✅ Updated export documentation

Phase 8: Archive and Clean Up

1. Remove entire issue section from ISSUES.md

2. Add to docs/reports/ISSUES_RESOLVED.md:

## Timeline export generating corrupted files - RESOLVED

**Resolved**: 2025-10-27 16:45 UTC
**Root Cause**: FFmpeg export missing keyframe interval parameter, causing unplayable MP4 files.

**Solution**:

- Added `-g 30` flag to FFmpeg command (keyframe every 30 frames)
- Updated export settings to include proper codec parameters
- Added validation step to check exported file integrity

**Files Modified**:

- `lib/export/ffmpegExporter.ts` - Added keyframe interval
- `app/api/export/route.ts` - Updated export validation
- `docs/EXPORT_GUIDE.md` - Documented codec settings

**Testing**:

- Exported 5 test timelines of varying lengths (10s to 5min)
- All files play correctly in VLC, QuickTime, and browser
- File sizes appropriate for content

**Commits**: 7a22f558

---

---

Common Mistakes to Avoid

❌ Don't Do This	✅ Do This Instead
Start work without checking conflicts	Always run grep "\[IN PROGRESS\]" ISSUES.md first
Forget to add [IN PROGRESS] marker	Add marker IMMEDIATELY when starting
Leave resolved issue in ISSUES.md	ALWAYS remove and archive to ISSUES_RESOLVED.md
Incomplete archive entry	Include root cause, solution, files, testing, commits
Leave [IN PROGRESS] when pausing	Remove marker, update status to "Paused"
Work on issue someone else started	Ask user if you should take over

---

Quick Reference Commands

# 1. Check for conflicts (ALWAYS DO THIS FIRST)
grep -A 5 "\[IN PROGRESS\]" ISSUES.md

# 2. View all issues
cat ISSUES.md

# 3. Search for specific issue
grep -i "keyword" ISSUES.md

# 4. View recently resolved issues
head -100 docs/reports/ISSUES_RESOLVED.md

# 5. Get UTC timestamp for marking start
date -u +"%Y-%m-%d %H:%M UTC"

# 6. Check git status before committing fix
git status

---

Error Handling

Conflict Detected

ERROR: Issue already in progress

Found: [IN PROGRESS] Timeline export bug
Started: 2025-10-27 14:30 UTC (45 minutes ago)

Action: Ask user if you should:
1. Take over (remove old marker, add yours)
2. Work on different issue
3. Wait until current work completes

Stale Issue (>2 hours)

WARNING: Stale in-progress issue detected

Found: [IN PROGRESS] Video export bug
Started: 2025-10-27 10:00 UTC (5 hours ago)

Action: Ask user:
"Found stale issue from 5 hours ago. Should I take over?"

Missing Issue in ISSUES.md

ERROR: Issue not found in ISSUES.md

Searched for: "nonexistent bug"
Available issues: {list current issues}

Action: Ask user to clarify which issue to work on

---

Integration with Other Tools

TodoWrite Integration

• Create TodoWrite list when starting issue
• Reference in ISSUES.md: **Todo Tracking**: 5 tasks
• Update both TodoWrite and ISSUES.md progress in parallel
• When all todos ✅ → Archive issue

Git Integration

• Commit fixes with descriptive messages
• Include commit hashes in archive entry
• Link to PR if applicable

Axiom/Logging Integration

• Reference relevant Axiom queries in investigation
• Include log analysis in archive if helpful

---

Best Practices

1. Always check first: Never start without checking [IN PROGRESS]
2. Mark immediately: Add marker as soon as you decide to work on issue
3. Update frequently: Keep Current Progress section current
4. Document thoroughly: Archive should tell the complete story
5. Clean up completely: Remove resolved issues, don't leave duplicates
6. Test before archiving: Verify fix actually works
7. Commit before archiving: Ensure code changes are saved

---

Success Criteria

An issue is considered properly handled when:

• ✅ No conflicts detected before starting
• ✅ [IN PROGRESS] marker added with timestamp
• ✅ TodoWrite list created and maintained
• ✅ Current Progress section kept updated
• ✅ Fix implemented and tested
• ✅ Changes committed to git
• ✅ Issue completely removed from ISSUES.md
• ✅ Full archive entry added to ISSUES_RESOLVED.md
• ✅ No [IN PROGRESS] marker left behind

---

Future Enhancements

Potential improvements:

• Automatic stale issue detection (>24 hours)
• Integration with PR workflow
• Automated testing requirements checklist
• Link validation for archived issues