# Modular Review System

The review system uses markdown-driven reviews where the agent writes `.broomy/review.md` with structured headings and GFM task list checkboxes. The UI renders this markdown with auto-collapsing sections and progress tracking.

## Architecture

Source: `src/renderer/components/review/` (entry point: `index.tsx`)

Supporting modules:
- `useReviewActions.ts` — generates review prompts, sends skill commands, manages gitignore
- `useReviewData.ts` — state management for review markdown content
- `useReviewFilePoller.ts` — polls `.broomy/review.md`, resolves include directives

## How It Works

1. User clicks **Generate Review** in the explorer's review filter
2. `useReviewActions` writes `.broomy/context.json` (PR number, base branch, URL) and sends the `/broomy-action-review` skill command to the agent terminal
3. The agent runs `git diff` and writes `.broomy/review.md` incrementally
4. `useReviewFilePoller` polls the file every 1 second, resolves `<!-- include: path -->` directives, and updates the UI
5. The review panel splits the markdown on `## ` headings into collapsible sections

## Markdown Format

The agent writes standard markdown with these conventions:

- **`## Heading`** — major sections (auto-collapsed in the UI)
- **`### Sub-heading`** — individual issues, findings, or change groups within a section
- **`- [ ] Check name`** / **`- [x] Check name`** — GFM task checkboxes for progress tracking
- **`<!-- include: .broomy/review-detail.md -->`** — include directives for sub-analyses in separate files

Sections containing incomplete checkboxes (`- [ ]`) stay expanded automatically, drawing attention to items that still need review.

### Example review structure

```markdown
## Overview
Brief summary of the PR's purpose and approach.

## Change Analysis
- [x] Reviewed file structure
- [x] Identified change patterns

### Theme context and provider
New ThemeContext and ThemeProvider for managing state.
[src/contexts/ThemeContext.tsx:1](https://github.com/...)

### CSS variable updates
Updated custom properties for dark mode.
[src/styles/theme.css:12](https://github.com/...)

## Potential Issues

### Flash of unstyled content on load
- [ ] Resolved

Theme is read from localStorage after React hydration.
Location: [src/contexts/ThemeContext.tsx:15](https://github.com/...)

## Design Decisions

### localStorage over cookies
- [x] Reviewed

Simpler but not available server-side.
```

## Include Directives

The poller resolves `<!-- include: path -->` lines by reading the referenced file relative to the session directory. If the file doesn't exist yet, a `*Pending: path...*` placeholder is shown. The poller re-resolves includes on every tick, so sub-files can appear as the agent writes them.

This lets the agent break large reviews into modular files:

```markdown
## Security Analysis
<!-- include: .broomy/review-security.md -->

## Performance Analysis
<!-- include: .broomy/review-perf.md -->
```

## Link Handling

GitHub URLs in the review markdown (links starting with `https://github.com/`) open in an embedded webview in the file panel via `WebviewViewer` (`src/renderer/components/fileViewers/WebviewViewer.tsx`). Other URLs open in the system browser.

The webview viewer provides navigation controls (back, forward, reload) and an "Open in browser" button for switching to the system browser.

## Customization

Teams customize the review process by editing the review action in `.broomy/commands.json`. The action's prompt controls what checks the agent runs, what sections it writes, and how it formats findings.

The default prompt is generated by `buildMarkdownReviewPrompt()` in `src/renderer/utils/reviewPromptBuilder.ts`. It instructs the agent to:

1. Run `git diff origin/<base>...HEAD` to get the full diff
2. Write `.broomy/review.md` with `##` sections, `###` sub-headings for issues, and task checkboxes
3. Include GitHub links for file locations
4. Write incrementally so the UI can show progress

## Key Files

| File | Purpose |
|------|---------|
| `src/renderer/components/review/index.tsx` | Review panel UI, markdown section rendering |
| `src/renderer/components/review/useReviewActions.ts` | Generate review, open PR URL, gitignore |
| `src/renderer/components/review/useReviewData.ts` | State: reviewMarkdown, waitingForAgent |
| `src/renderer/components/review/useReviewFilePoller.ts` | Poll review.md, resolve includes |
| `src/renderer/utils/reviewPromptBuilder.ts` | Build review prompts for agents |
| `src/renderer/components/fileViewers/WebviewViewer.tsx` | Embedded webview for GitHub URLs |
