gh-workflow-mcp: Documentation and comment quality improvements

Documentation and Comment Quality Improvements

Tracking 12 documentation and comment improvements identified in PR #432 all-hands-review (iteration 3) but deemed out-of-scope for immediate fix.

Items from Comment Analyzer

Issue #2: JSDoc Clarification for pollJobsForFailure

File: monitor-run.ts:123-135

• Current: "Used for fail-fast mode"
• Improvement: Clarify relationship between polling and watch, explain why both are needed
• Suggested: "Polls job status in parallel with watch to detect failures quickly without waiting for watch to complete"

Issue #3: DEFAULT_WATCH_INTERVAL Usage Guidance

File: constants.ts:93-96

• Add comment explaining when to use DEFAULT_WATCH_INTERVAL vs DEFAULT_POLL_INTERVAL
• Clarify version context already documented (gh CLI 2.40.0+)

Issue #4: Hybrid Approach Explanation

File: monitor-pr-checks.ts:30-40

• Document why hybrid approach is used
• Explain fail-fast rationale and tradeoffs

Issue #5: TODO Comment Consolidation

Multiple files: Consolidate references to issue #539

• Lines with "TODO: See issue #539" should have consistent formatting
• Consider adding link to issue for easier navigation

Issue #6: Fail-Fast Rationale Clarification

File: monitor-run.ts:41-46

• Expand fail_fast parameter description
• Explain why default is true
• Document performance vs completeness tradeoff

Issue #7: createAbortableWatch JSDoc Precision

File: gh-watch.ts:43-53

• Be more specific about which execa errors become GitHubCliError
• Document which programming errors would propagate uncaught

Issue #8: getCheckIcon Fallback Documentation

File: gh-watch.ts:174-195

• Document fallback behavior more explicitly
• Explain what "unknown conclusions" means in practice

Issue #9: Remove Unreachable Code

File: monitor-run.ts:268

• Delete unreachable else branch (validation at line 217 prevents reaching this)
• Or add explicit comment explaining why it's defensive

Issue #10: Move TODO Closer to Code

File: gh-cli.ts:81 (wiggum)

• Move TODO about error handling to getCurrentRepo catch block
• Current placement is too far from relevant code

Positive Findings (No Action Needed)

Issue #11: executeWatch JSDoc is Clear

File: monitor-run.ts:73-86

• Comprehensive documentation of fail-fast mechanism
• Good explanation of Promise.race behavior
• Appropriate level of detail

Issue #12: pollJobsForFailure Error Handling Well-Documented

File: monitor-run.ts:159-172

• Clear rationale for continuing on errors
• Good explanation of transient error tolerance

Issue #13: Clear and Actionable Validation Errors

File: monitor-run.ts:217-219, 233-236, 247-250

• Validation errors have good context
• Suggest concrete remediation steps

Priority

Low - These improvements would enhance code maintainability but don't affect functionality.

Related Issues

• #432 - Parent PR for gh watch implementation
• #539 - Runtime validation improvements