# GitHub Actions Log Collection - Workflow Flow

## Overview

This document maps where logs are collected, where they're stored, what triggers collection, and how they trigger actions to fix issues.

## Use Case 1: `/triage-pr` Command (Issue #1066)

### Trigger
- **Manual**: Developer runs `/triage-pr <pr_number>` in Cursor chat
- **When**: PR has failing CI tests
- **Condition**: PR exists, CI runs exist, at least one run failed

### Log Collection Flow
```
Developer runs /triage-pr
  ↓
collectPRLogs() called
  ↓
GitHub API: List workflow runs for PR head SHA
  ↓
Filter to failed/cancelled runs
  ↓
For each failed run:
  ├─ Download workflow run logs → config/reports/logs/run-{id}/
  ├─ Download individual job logs → config/reports/logs/job-{id}/
  └─ Parse errors from logs
  ↓
Return PRLogCollectionResult with all logs + parsed errors
```

### Log Storage
- **Location**: `config/reports/logs/run-{runId}/` and `config/reports/logs/job-{jobId}/`
- **Format**: Extracted ZIP contents (log.txt files)
- **Retention**: Not automatically cleaned (manual cleanup or gitignored)

### Output & Action Flow
```
Parsed logs → Error analysis
  ↓
Displayed in Cursor chat:
  - Findings table (run, status, error snippet)
  - Root causes identified
  - Surgical fixes proposed
  - TODO list generated
  ↓
Developer reviews and approves
  ↓
Fixes implemented in code
  ↓
Changes committed and pushed
  ↓
CI automatically re-runs (GitHub webhook)
  ↓
Success → PR ready
Failure → Repeat triage
```

### Key Points
- **Logs stay local** - stored in `config/reports/logs/` for analysis
- **No automatic actions** - requires developer approval before fixes
- **Analysis-only** - until developer approves fixes

---

## Use Case 2: Auto-Fix-Lint (Issue #1067)

### Trigger
- **Automatic**: GitHub Actions `workflow_run` event
- **When**: CI workflow completes with `conclusion: 'failure'`
- **Condition**: 
  - `lint-and-types` job failed
  - PR is open
  - Auto-fix attempts < 2

### Log Collection Flow
```
CI workflow fails
  ↓
GitHub triggers auto-fix-lint.yml workflow
  ↓
Check: lint-and-types job failed?
  ↓
YES → downloadJobLogs(jobId) for lint job
  ↓
Download to: config/reports/logs/job-{jobId}/
  ↓
parseLogErrors() extracts lint-specific errors
  ↓
Filter to lint-error type only
```

### Log Storage
- **Location**: `config/reports/logs/job-{jobId}/` (temporary, workflow-scoped)
- **Format**: Extracted log files
- **Retention**: Cleaned up after workflow completes (ephemeral)

### Output & Action Flow
```
Parsed lint errors → File/line locations extracted
  ↓
Auto-fix logic enhanced with specific errors
  ↓
npm run lint:fix runs (targeting specific files/lines)
  ↓
Changes detected?
  ↓
YES → Commit with [auto-fix attempt X/2]
  ↓
Push to PR branch
  ↓
Comment posted to PR: "🤖 Auto-fix applied..."
  ↓
CI automatically re-runs (via push webhook)
  ↓
Success → PR continues
Failure → Repeat (max 2 attempts)
```

### Key Points
- **Logs are ephemeral** - stored during workflow, cleaned after
- **Automatic action** - no human approval needed (limited to 2 attempts)
- **Targeted fixes** - uses parsed errors to improve fix accuracy

---

## Use Case 3: Manual CLI Tool (Issue #1065)

### Trigger
- **Manual**: Developer runs `npm run download-logs -- --run-id <id>`
- **When**: Developer wants to inspect failures outside automated workflows
- **Condition**: Valid run/job ID, GitHub authentication

### Log Collection Flow
```
Developer runs CLI command
  ↓
downloadWorkflowLogs() or downloadJobLogs()
  ↓
Download to: config/reports/logs/ (or custom --output-dir)
  ↓
Optional: --parse-errors flag
  ↓
If parsing: parseLogErrors() displays summary
```

### Log Storage
- **Location**: `config/reports/logs/` (or custom directory)
- **Format**: Extracted ZIP or raw ZIP (--no-extract)
- **Retention**: Manual cleanup

### Output & Action Flow
```
Logs downloaded
  ↓
Optional: Error summary displayed in terminal
  ↓
Developer reviews logs manually
  ↓
Developer takes action (fix code, create issue, etc.)
```

### Key Points
- **Fully manual** - no automatic actions
- **Flexible** - can download any run/job, any time
- **Analysis tool** - for investigation, not automation

---

## Use Case 4: Future - Automated Failure Tracking

### Potential Trigger
- **Automatic**: GitHub Actions workflow on `workflow_run.failure`
- **When**: Any workflow fails (not just CI)
- **Condition**: Failure detected, logs available

### Potential Log Collection Flow
```
Workflow fails
  ↓
Failure tracking workflow triggered
  ↓
collectPRLogs() or downloadWorkflowLogs()
  ↓
Download logs → config/reports/logs/
  ↓
parseLogErrors() analyzes failures
  ↓
Check: Recurring failure pattern?
  ↓
YES → Create GitHub issue with:
  - Error summary
  - Log excerpts
  - Recommended fixes
  - Related PR/workflow links
```

### Potential Output & Action Flow
```
Issue created → Developer notified
  ↓
Developer reviews issue
  ↓
Developer implements fix
  ↓
PR created → CI runs → Success
```

### Key Points
- **Not yet implemented** - potential future enhancement
- **Issue creation** - logs feed into GitHub issues for tracking
- **Proactive** - catches recurring failures automatically

---

## Data Flow Summary

### Log Collection → Storage → Analysis → Action

```
GitHub Actions Logs API
  ↓
downloadWorkflowLogs() / downloadJobLogs()
  ↓
config/reports/logs/ (local filesystem)
  ↓
readLogFiles() → parseLogErrors()
  ↓
Structured error data (ParsedLogError[])
  ↓
Used by:
  ├─ /triage-pr → Display analysis → Developer approval → Fixes
  ├─ auto-fix-lint → Enhance auto-fix → Auto-commit → CI re-run
  ├─ CLI tool → Manual review → Developer action
  └─ Future: Issue creation → Developer notification → Fixes
```

## Key Integration Points

### 1. `/triage-pr` Command (Issue #1066)
- **Input**: PR number
- **Collection**: `collectPRLogs(prNumber)` → downloads all failed runs
- **Output**: Analysis in Cursor chat, TODO list
- **Action**: Developer-driven (approval required)

### 2. Auto-Fix-Lint Workflow (Issue #1067)
- **Input**: Failed workflow run event
- **Collection**: `downloadJobLogs(jobId)` for lint job only
- **Output**: Enhanced auto-fix targeting
- **Action**: Automatic (commits and pushes)

### 3. CLI Tool (Issue #1065)
- **Input**: Run/job ID from command line
- **Collection**: `downloadWorkflowLogs(runId)` or `downloadJobLogs(jobId)`
- **Output**: Terminal display, saved files
- **Action**: Manual (developer reviews and acts)

## Storage Locations

| Use Case | Location | Retention | Format |
|----------|----------|-----------|--------|
| `/triage-pr` | `config/reports/logs/run-{id}/` | Manual cleanup | Extracted logs |
| Auto-fix-lint | `config/reports/logs/job-{id}/` | Ephemeral (workflow-scoped) | Extracted logs |
| CLI tool | `config/reports/logs/` or custom | Manual cleanup | ZIP or extracted |
| Future tracking | `config/reports/logs/` + GitHub issues | Long-term (issues) | Logs + issue body |

## Action Triggers

| Use Case | Trigger Type | Action Type | Approval Required |
|----------|--------------|-------------|-------------------|
| `/triage-pr` | Manual command | Code fixes | ✅ Yes (developer) |
| Auto-fix-lint | Workflow event | Auto-commit | ❌ No (limited attempts) |
| CLI tool | Manual command | None (analysis only) | N/A |
| Future tracking | Workflow event | Issue creation | N/A (issue only) |

## Notes

1. **Logs are NOT automatically cleaned** - Consider adding cleanup or gitignore rules
2. **No centralized log storage** - Each use case manages its own logs
3. **Actions are mostly manual** - Only auto-fix-lint has automatic actions
4. **Future enhancement opportunity** - Automated failure tracking could create issues automatically