# ADR-005: GitHub Integration for PR Analysis

**Date:** 2026-02-07
**Status:** Accepted

## Context

Developers reviewing PRs lack visibility into the impact of code changes on the broader codebase. Understanding dependencies and callers requires manual exploration, which is time-consuming and error-prone.

Clew Engine already provides this information through the `explore_module` tool. The goal is to surface this context automatically during code review.

## Decision

Create a GitHub Action that:

1. **Triggers on PR open/sync**: Runs whenever a PR is opened or updated
2. **Analyzes changed files**: Uses `clew_bot.py --pr` to diff against `origin/main`
3. **Posts Mermaid graphs**: Comments on the PR with dependency diagrams
4. **Updates existing comment**: Avoids spam by finding and editing previous Clew comment

### Implementation Details

```yaml
# .github/workflows/clew-pr-analysis.yml
on:
  pull_request:
    types: [opened, synchronize]
```

The script outputs GitHub-flavored markdown with:
- Mermaid code blocks (rendered by GitHub)
- Collapsible `<details>` sections for dependencies
- Impact warnings for files with many callers

## Consequences

### Positive
- Instant context during code review
- Visual dependency graphs rendered by GitHub
- No manual steps required from developers

### Negative
- Requires running Clew API (external dependency)
- Initial setup requires configuring secrets

### Activation Required
```bash
# Repository variables
CLEW_API_URL=https://api.clewengine.dev

# Repository secrets  
CLEW_API_KEY=<api-key>
```

## Alternatives Considered

1. **Embedded analysis (no API)**: Run tree-sitter locally in the Action. Rejected - loses graph context.
2. **GitHub App**: Full GitHub App integration. Deferred - overkill for v1.
3. **PR labels instead of comments**: Mark impact level with labels. Rejected - less informative.

## Files Changed

- `.github/workflows/clew-pr-analysis.yml`: New workflow
- `examples/clew_bot.py`: Added `--pr` and `--output markdown` flags
