Convert documented bugs and technical debt into GitHub issues

[WesleyMFrederick]

Problem

The codebase contains bugs and technical debt documented inline in various files (architecture docs, user stories, code comments) that should be tracked as proper GitHub issues for visibility and prioritization.

Known Locations to Search

1. ARCHITECTURE.md: "Known Risks and Technical Debt" section
2. Design docs: Look for sections labeled:
   • "Technical Debt"
   • "Known Issues"
   • "Limitations"
   • "Future Work"
   • "TODOs"
3. User story files: Check for inline bug reports or debt mentions
4. Code comments: Search for TODO:, FIXME:, HACK:, BUG: markers
5. Test files: Look for skipped tests (test.skip) with explanations

Examples Already Documented

From ARCHITECTURE.md:

• Line 583-595: CLI Subprocess Testing Buffer Limits (Technical Debt)

  • Issue: 64KB stdio pipe buffer limit on macOS causes test failures
  • Mitigation: Refactor tests to import CLI functions directly
  • Reference: Bug 3 resolution doc

• Line 597-660: CLI Testing stdout/stderr Separation Pattern (Architectural Decision)

  • May contain related technical debt

From citation-manager:

• DI Technical Debt: Lack of Dependency Injection mentioned in architecture
• Test Coverage: 0.3:1 to 0.5:1 ratio may have gaps

Search Commands

# Search for technical debt markers in docs
grep -r "Technical Debt" design-docs/ tools/*/design-docs/

# Search for known issues
grep -r "Known Issues" design-docs/ tools/*/design-docs/
grep -r "Known Risks" design-docs/ tools/*/design-docs/

# Search for TODO markers in code
grep -r "TODO:" src/ tools/*/src/
grep -r "FIXME:" src/ tools/*/src/
grep -r "HACK:" src/ tools/*/src/

# Search for skipped tests
grep -r "test.skip\|it.skip\|describe.skip" test/ tools/*/test/

Task Breakdown

• Search ARCHITECTURE.md "Known Risks and Technical Debt" section
• Search all design-docs for "Technical Debt", "Known Issues", "Limitations" sections
• Search user story files for inline bug reports
• Search source code for TODO/FIXME/HACK/BUG comments
• Search test files for skipped tests with debt explanations
• For each item found:
  • Create GitHub issue with proper context
  • Link to source location (file + line number)
  • Add appropriate labels (bug, enhancement, tech-debt)
  • Set priority based on impact
• Update source locations to reference the GitHub issue number
• Create summary comment listing all created issues

Issue Template for Converted Items

## Original Documentation Location

[File path and line number]

## Problem Description

[Copy from original documentation]

## Impact

**Priority:** [High/Medium/Low based on analysis]
**Effort:** [Estimate]
**Affects:** [Components/features affected]

## Proposed Solution

[If mentioned in original docs]

## Related

- Original location: [Link to file and line]
- Related issues: [If applicable]

Acceptance Criteria

• All "Known Risks and Technical Debt" items from ARCHITECTURE.md converted to issues
• All design-docs sections with debt/issues converted
• Code comments with TODO/FIXME/HACK converted (if substantial)
• Skipped tests with debt explanations converted
• Each created issue linked back to source location
• Source locations updated with issue references (e.g., "See Issue #X")
• Summary comment on this issue listing all created issues

Impact

Priority: Medium
Effort: 2-4 hours (depends on volume found)
Improves:

• Technical debt visibility
• Prioritization capability
• Prevents debt from being forgotten in docs

Related Issues

• Part of workspace hygiene and documentation cleanup
• Complements Clean up broken citation links in ARCHITECTURE.md #6 (citation link cleanup)