prctrl 0.9.1

Terminal-native GitHub PR management. Stay on top of code reviews without leaving your terminal.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

# review-velocity

**Analyze how quickly PRs get reviewed — average time-to-review, distribution breakdown, and bottleneck detection.**

See how fast (or slow) your team is at reviewing PRs. `review-velocity` calculates the time from PR creation to when you submitted your review, then breaks it down by time buckets and identifies which repositories or authors create the slowest reviews.

## When to Use

- End of sprint: "Are we reviewing fast enough?"
- Identify bottlenecks: "Which repos/authors take forever to review?"
- Set SLAs: "What a reasonable review time target?"
- Track improvement: "Did our new process help?"

## Synopsis

```bash
prctrl review-velocity [OPTIONS]
```

## Options

| Flag | Description | Default |
|------|-------------|---------|
| `-d, --days <NUM>` | Number of days to look back | `30` |
| `-b, --bottlenecks` | Show bottleneck analysis by author/repo | `false` |
| `-P, --priority` | Show priority vs review time breakdown | `false` |
| `--repo <TEXT>` | Filter by repository name (partial match, case-insensitive) | |
| `--author <TEXT>` | Filter by author username (partial match, case-insensitive) | |
| `-s, --since-days <NUM>` | Only show PRs created since this many days ago | |
| `-p, --pr <NUM>` | Target a specific PR by number | |
| `--json` | Output as JSON for scripting | `false` |

## Examples

```bash
# Standard 30-day velocity analysis
prctrl review-velocity

# Quick 7-day snapshot
prctrl review-velocity --days 7

# With bottleneck analysis (see slowest repos/authors)
prctrl review-velocity --bottlenecks

# With priority breakdown (correlate priority scores with review speed)
prctrl review-velocity --priority

# Combine all analysis options
prctrl review-velocity --bottlenecks --priority

# Filter by specific repository
prctrl review-velocity --repo backend

# Filter by specific author
prctrl review-velocity --author alice

# Combine filters with bottleneck analysis
prctrl review-velocity --repo api --bottlenecks

# Only PRs created in the last 14 days (regardless of when reviewed)
prctrl review-velocity --since-days 14

# Show velocity for a specific PR
prctrl review-velocity --pr 123

# Combine --since-days with other filters
prctrl review-velocity --since-days 7 --repo backend --bottlenecks

# JSON for dashboards
prctrl review-velocity --json | jq '.avg_hours_to_review'
```

## Output Example

```
⚡ Review Velocity — last 30 days
─────────────────────────────────────────────

  📊 Summary (23 PRs reviewed)
     Average time to review:  18.4 hours
     Median time to review:    12.0 hours
     Fastest review:           0.5 hours
     Slowest review:           72.0 hours

  ⏱️  Time Distribution
     < 4h:       4 (17.4%)  ▓▓▓▓░░░░░░░░░░░░░░
     4-24h:      8 (34.8%)  ▓▓▓▓▓▓▓░░░░░░░░░░
     1-3d:       7 (30.4%)  ▓▓▓▓▓▓▓░░░░░░░░░
     > 3d:       4 (17.4%)  ▓▓▓▓░░░░░░░░░░░░░░

  ⭐ Priority vs Review Time
     ⭐⭐⭐⭐⭐  5 PRs  28.3h avg  ████████████
     ⭐⭐⭐⭐    8 PRs  14.2h avg  ████████
     ⭐⭐⭐     10 PRs  8.5h avg   █████
     ⭐⭐        0 PRs   0.0h avg
     ⭐         0 PRs   0.0h avg

  🐢 Bottleneck Analysis — by Author
     (slowest average review time)
     alice     ██████████  36.2h avg  (5 PRs)
     bob       ████████    28.1h avg  (8 PRs)
     carol     ███████      22.4h avg  (4 PRs)

  🐢 Bottleneck Analysis — by Repository
     (slowest average review time)
     backend   ██████████  32.1h avg  (12 PRs)
     frontend  ███████      18.5h avg  (7 PRs)
     shared    ████        8.2h avg   (4 PRs)

  💡 Use `--bottlenecks` to see which repos/authors take longest
  💡 Use `--priority` to correlate priority with review speed
  💡 Use `--json` for machine-readable output
─────────────────────────────────────────────
```

## How It Works

Review velocity reads the processed review files saved in your output directory (default: `./reviews/`). Each file contains both `Created` and `Reviewed on` timestamps, allowing calculation of the review time in hours.

**Filters are applied efficiently:**
- `--since-days` filter is checked **before** expensive parsing (early exit)
- `--days` filter then filters by review date
- `--repo` and `--author` filters are applied last for precise filtering

**Time buckets:**
- **< 4h** — Same day reviews (fast turnaround)
- **4-24h** — Next day reviews (typical)
- **1-3d** — Multi-day reviews (getting slow)
- **> 3d** — Stale reviews (bottleneck indicator)

**Bottleneck analysis** shows which authors or repositories have the highest average review times, helping identify process or knowledge gaps.

**Priority vs Review Time** (with `--priority` flag) shows how long high vs low priority PRs take to review. This helps answer questions like "Are we prioritizing urgent reviews?"

## Tips

- Requires review files from `delegate` command
- Use `--days 7` for weekly view, `--days 90` for quarterly context
- Track your velocity over time to see if process changes help
- Pair with `trends` for complete review analytics
- Use `--priority` to see if critical PRs are getting the attention they deserve