@groupby/ai-dev 0.5.18 → 0.5.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@groupby/ai-dev",
3
- "version": "0.5.18",
3
+ "version": "0.5.20",
4
4
  "description": "Interactive installer for Rezolve Ai development content",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,37 @@
1
+ # OOF Release Impact Analysis
2
+
3
+ Generates a structured, human-reviewed **Release Impact Analysis** for a critical OOF
4
+ release by correlating the git diff with the surrounding code, linked Jira tickets, and
5
+ live operational signal (GCP Cloud Logging / BigQuery), then optionally publishes it to
6
+ Confluence. Output is AI-generated decision-support and requires human sign-off.
7
+
8
+ ## What it does
9
+ - Resolves the release range (last prod tag → release candidate, or a supplied `base..head`)
10
+ and gathers signal: diff + changed code and its call sites, linked Jira keys (revert-aware),
11
+ and — for critical releases — live cloud/outage status, GCP Cloud Logging, and BigQuery.
12
+ - Classifies the blast radius (API/contract, DB/migrations, auth/security, infra/terraform,
13
+ per-region config, dependencies, cross-service, client compatibility, observability).
14
+ - Produces a consistent, readable report: Found issues → Overview → Cross-service blast
15
+ radius → Risk assessment + Top risks → Suggested QA focus (non-technical) → Validation
16
+ performed → Unknowns; with optional Operational context, Pre-launch checklist, and an
17
+ Engineer detail appendix (`detail=engineer`).
18
+ - Optionally publishes the report to Confluence.
19
+
20
+ ## Prerequisites
21
+ - Read-only git access to the target repo (local clone or `glab` / `gh`).
22
+ - For `depth=full` cloud signal: `gcloud` / `bq` authenticated to the target GCP project.
23
+ - For `publish=confluence`: the Atlassian MCP connector connected.
24
+ - An approved enterprise assistant (no-training / no-retention) — the skill's security
25
+ guardrails (never ingest secrets, cost-aware cloud access) must be met.
26
+
27
+ ## Inputs
28
+ `repo`, `range`, `critical`, `depth` (`light` | `full`), `detail` (`summary` | `engineer`),
29
+ `publish` (`confluence` | `none`), `gcp_project`.
30
+
31
+ ## Trigger phrases
32
+ - "run impact analysis"
33
+ - "release impact analysis"
34
+ - "analyse this release before we ship"
35
+
36
+ ## Team
37
+ OOF
@@ -0,0 +1,310 @@
1
+ ---
2
+ name: oof-release-impact-analysis
3
+ description: 'Generate a structured Release Impact Analysis for a critical OOF release by correlating git changes with the surrounding code, linked Jira tickets, and live operational signal (cloud/outage status, GCP Cloud Logging, BigQuery), classify the blast radius, and optionally publish to Confluence. Use when the user says "run impact analysis", "release impact analysis", or before a critical release.'
4
+ ---
5
+
6
+ # OOF Release Impact Analysis
7
+
8
+ **Goal:** For a critical release, produce a structured, human-reviewed **Release Impact
9
+ Analysis** that focuses QA, documents blast radius, and serves as SOC2 change-management
10
+ evidence. The git diff is the *starting point*, not the whole picture — the analysis
11
+ correlates the diff with the surrounding code, the linked Jira tickets, and **live
12
+ operational signal** (cloud/outage status, GCP Cloud Logging, BigQuery) to judge real-world
13
+ impact, not just what a static diff shows.
14
+
15
+ **Your Role:** You are a release engineer performing change-impact analysis. You are
16
+ precise and conservative: you never overstate confidence, you flag what you *cannot*
17
+ determine from the available signal, and you treat the output as decision-support for a
18
+ human reviewer — never as an automatic release gate.
19
+
20
+ > ⚠️ AI-generated. This report assists a human decision. It must be reviewed and
21
+ > signed off before it is relied upon. A release is never gated solely on this output.
22
+
23
+ > 💰 **This deep, multi-source analysis is thorough but expensive** — it burns
24
+ > engineer/agent time, LLM tokens, and real query cost (GCP Logging / BigQuery scanned
25
+ > bytes). Run the **full** analysis only for **critical** releases, and **confirm depth up
26
+ > front** (Step 0) rather than defaulting into it. Non-critical releases should use the
27
+ > lightweight, git-only pass (`depth=light`, no cloud queries, no publish) — or skip the
28
+ > analysis entirely.
29
+
30
+ ## Inputs
31
+
32
+ - **repo** — Repository to analyse (defaults to the current workspace repo).
33
+ - **range** (optional) — Git range `<base>..<head>`. If omitted, resolve it (see Step 1).
34
+ - **critical** (optional) — Whether this is a critical release. Critical forces `depth=full`
35
+ **and** `detail=engineer`, and turns on the CDT-parity uplift (deployment/rollback
36
+ second-order analysis, per-risk severities, a mandatory **Required before production** gate
37
+ + go/no-go recommendation, and an exhaustive engineer-detail appendix).
38
+ - **depth** (optional) — `light` (git + code only) or `full` (also pulls Jira, cloud/outage
39
+ status, GCP logs, BigQuery). Defaults to `full` when `critical`, else `light`.
40
+ - **detail** (optional) — output verbosity: `summary` (default) or `engineer`. `engineer`
41
+ appends the **Required before production** gate and an **Engineer detail** appendix for
42
+ high-risk / infra-heavy releases; the readable summary stays on top either way. **Critical
43
+ releases force `engineer`.**
44
+ - **publish** (optional) — `confluence` to publish the report, or `none` (default) to
45
+ only produce Markdown.
46
+ - **gcp_project** (optional) — GCP project(s) to query for logs/BigQuery (e.g.
47
+ `bluedot-prod-ause1`). Required for `depth=full` cloud signal.
48
+
49
+ ## Security guardrails (MANDATORY — read before running)
50
+
51
+ 1. **Approved LLM only.** Run this only via an approved enterprise assistant with
52
+ no-training / no-retention terms. Do not paste diffs into ad-hoc consumer tools.
53
+ 2. **Never ingest secrets.** Exclude and never echo the contents of secret-bearing files.
54
+ Deny-list at minimum: `*.env`, `_config.*.env`, `*.pem`, `*.key`, `*credentials*`,
55
+ `*secret*`, `serviceAccount*.json`, terraform state, `*.tfvars`. If a diff touches one,
56
+ report **only the filename and that it changed** — never the values.
57
+ 3. **Least privilege.** Read-only git access. Do not push, tag, or modify anything.
58
+ 4. **Access-controlled output.** Publish only to an access-controlled Confluence space.
59
+ Do not expose internal implementation detail to a broad audience.
60
+ 5. **Cost-aware cloud access.** GCP Logging / BigQuery queries cost money and scan real
61
+ data. Always bound queries by the release time window + relevant service/resource, cap
62
+ scanned bytes, and prefer summaries/counts over dumping rows. Never run unbounded
63
+ `SELECT *`. Read-only only.
64
+ 6. **HALT** if you cannot confirm guardrails 1–2 for the current environment.
65
+
66
+ ## Signal sources (the diff is the starting point, not the whole picture)
67
+
68
+ Git tells you *what text changed*; these sources tell you *what it actually affects and
69
+ whether it is safe to ship now*. Use them according to `depth`:
70
+
71
+ - **Git diff + history** (always) — changed files, churn, commit messages, linked tickets.
72
+ - **Surrounding code** (always) — read the changed functions *and their call sites /
73
+ dependents* in the repo, not just the `+/-` lines, to judge real blast radius. A one-line
74
+ change to a shared helper can be higher impact than a large isolated feature.
75
+ - **Linked Jira tickets** (`full`) — pull the `BD-xxxx` keys for intent, acceptance
76
+ criteria, and whether the change is a fix for a known incident.
77
+ - **Cloud / outage status** (`full`) — is the platform currently healthy? Check GCP service
78
+ health and any ongoing SRE incidents for the target project/region. Releasing into an
79
+ active outage or degraded dependency raises risk and may warrant a hold.
80
+ - **GCP Cloud Logging (Logs Explorer)** (`full`) — for the services touched, check recent
81
+ error rates / 5xx / notable log signatures so the analysis reflects the *current* prod
82
+ behaviour of the code being changed (bounded to a short window).
83
+ - **BigQuery** (`full`) — where relevant (e.g. event/analytics tables), sample real volumes
84
+ or error patterns for the affected flow (bounded, capped-bytes, aggregate queries only).
85
+
86
+ ## Execution
87
+
88
+ ### Step 0: Confirm scope & depth (ask before spending)
89
+
90
+ The full analysis costs real time and money, so **confirm depth up front** rather than
91
+ silently defaulting into the expensive path. Unless the user has already specified, ask:
92
+
93
+ - **Critical release?** The full multi-source pass is intended for critical releases only.
94
+ - **Depth?** `full` — code + Jira + cloud/outage status + GCP Logging + BigQuery: thorough,
95
+ but burns agent time, LLM tokens, and **real GCP query charges** (Logging + BigQuery
96
+ scanned bytes). `light` — git + code only: fast and free, no cloud queries, no publish.
97
+ - **Publish?** `confluence`, or Markdown-only (`none`).
98
+
99
+ If the user defers, default to `full` + `detail=engineer` + publish when `critical`, else
100
+ `light` + `none` — but **don't assume `full` for an unspecified release; ask first.**
101
+ Non-critical releases use `light` or skip the analysis entirely. State the chosen depth (and
102
+ why) at the top of the report.
103
+
104
+ ### Step 1: Resolve the release range
105
+
106
+ - If `range` is given, use it.
107
+ - Otherwise resolve `<base>` = most recent production tag/release, `<head>` = the release
108
+ candidate (target branch or RC tag). Prefer, in order:
109
+ - `git describe --tags --abbrev=0` on the last prod tag, or the last tag matching the
110
+ project's release pattern (e.g. semantic-release tags), through `HEAD`.
111
+ - State the resolved `base..head`, both short SHAs, and the commit count. If you cannot
112
+ resolve it confidently, ask the user for the range and HALT.
113
+
114
+ ### Step 2: Gather signal (read-only)
115
+
116
+ Gather from the sources above, without ever printing secret values. Scale effort to
117
+ `depth`.
118
+
119
+ **Always (both `light` and `full`):**
120
+ - Changed files with status + churn: `git diff --stat <base>..<head>` and
121
+ `git diff --name-status <base>..<head>`.
122
+ - Commit messages: `git log --no-merges --pretty='%h %s' <base>..<head>`.
123
+ - Linked work items: Jira keys parsed from commit messages / branch names (e.g. `BD-\d+`).
124
+ **Revert-aware (critical):** a ticket only counts as *in the release* if its changes survive
125
+ in the **net** diff. When commits were reverted within the range (net ≠ history), verify
126
+ whether each ticket's files/content actually survive (e.g. a feature file added then deleted
127
+ is reverted). List reverted tickets **separately** as *reverted in-range (not shipped)* —
128
+ never imply reverted work is part of the release.
129
+ - For non-secret files, inspect the diff **and the surrounding code / call sites** to judge
130
+ real blast radius. For deny-listed files, record filename + "changed (contents not
131
+ inspected)".
132
+
133
+ **Additionally when `depth=full` (critical releases):**
134
+ - **Jira:** read each linked ticket for intent / acceptance criteria / incident linkage.
135
+ - **Cloud / outage status:** confirm the target project/region is healthy (GCP service
136
+ health + any ongoing SRE incidents). Note anything degraded.
137
+ - **GCP Cloud Logging:** for each touched service, sample recent error/5xx signatures in a
138
+ bounded window (e.g. last 1–24h) for `gcp_project` — e.g.
139
+ `gcloud logging read '<filter> severity>=ERROR' --project <p> --freshness=24h --limit=50`.
140
+ - **BigQuery:** where the change touches an event/analytics flow, run a bounded, aggregate
141
+ query (capped bytes, `--maximum_bytes_billed`) to sample real volume / error rate for the
142
+ affected path. Never `SELECT *` unbounded.
143
+ - Record every source actually consulted (feeds the "Data sources consulted" report field).
144
+ - If cloud access is unavailable or `gcp_project` is missing, note it as a gap and continue
145
+ with git+code+Jira signal only (do not fabricate cloud findings).
146
+
147
+ ### Step 3: Classify into impact areas (internal analysis)
148
+
149
+ Bucket every change into the areas below. This classification is **internal** — it drives
150
+ the report's `Found issues`, `Cross-service blast radius`, and the Overview `What changed`
151
+ summary. Do **not** emit a standalone per-area "What changed" section (the report no longer
152
+ uses one). For each touched area capture the concrete files/commits and a one-line "so what";
153
+ note clean areas so their absence can be reflected in the risk assessment.
154
+
155
+ - **API / contract changes** — swagger/openapi specs, route handlers, request/response
156
+ shapes. Flag anything **breaking** for consumers.
157
+ - **Database / migrations** — schema changes, migration scripts, index changes,
158
+ destructive operations.
159
+ - **Auth & security-sensitive** — `auth/`, `security/`, token/session logic, permissions,
160
+ crypto, dependency CVE-relevant bumps. Any change here raises the risk rating.
161
+ - **Infrastructure** — terraform, Dockerfiles, CI/CD pipelines, service definitions.
162
+ - **Config / environment** — per-region config (**AU / EU / US incl. DR**), feature flags,
163
+ env keys added/removed. Note if a change lands in some regions but not others.
164
+ - **Dependencies** — `package.json` / lockfiles and other manifests; separate security
165
+ bumps from feature bumps; note major-version jumps.
166
+ - **Cross-service blast radius** — shared patterns/libraries or contracts that other OOF
167
+ services depend on (a change here can affect repos outside this diff).
168
+ - **Client backwards-compatibility** — impact on Android / native / web clients consuming
169
+ the changed contracts.
170
+ - **Observability / operational** — logging, metrics, alerts, rollback affordances.
171
+ - **Deployment & rollback effects (second-order)** — reason beyond *what code changed* to
172
+ *what the deploy does*: artifact/checksum changes that force a **new revision** even with no
173
+ logic change; provider/toolchain upgrades (e.g. Terraform / `google` provider pins) that can
174
+ cause **state or computed-field drift** → require a `terraform plan` review **per environment
175
+ incl. DR**; CI rules that don't match the release config (e.g. `hotfix/*` allowed in CI but not
176
+ in `.releaserc`) that can tag a build semantic-release later refuses to release; and whether
177
+ the change also gates the **rollback path** (e.g. an auth / Workload Identity migration that
178
+ affects deploy *and* rollback). These are the subtle, high-impact issues a raw diff misses —
179
+ always assess them on `full` / critical runs.
180
+
181
+ ### Step 4: Risk rating
182
+
183
+ Assign an overall risk rating with a one-paragraph justification:
184
+
185
+ - **Low** — isolated, non-breaking, well-tested, easy rollback.
186
+ - **Medium** — touches a shared/contract surface OR config across regions OR notable deps.
187
+ - **High** — breaking API, auth/security, DB migration (esp. destructive), or infra with
188
+ no clean rollback.
189
+
190
+ Bias upward when auth/security, migrations, or cross-service contracts are involved, when
191
+ you had to inspect deny-listed files by name only, or when **live signal is adverse** —
192
+ e.g. an active outage / degraded dependency in the target region, or an elevated error rate
193
+ in Cloud Logging for a service this release touches.
194
+
195
+ **Critical releases (CDT-parity uplift):** tag **each Top risk with its own severity**
196
+ (High / Med / Low), consolidate the concrete pre-production validations into a **Required
197
+ before production** gate, and finish with an explicit **go/no-go recommendation** ("promote
198
+ only after X, Y, Z pass"). Populate the **Engineer detail** appendix in full — exact
199
+ versions/pins, **every** affected environment (incl. DR), and per-item failure mode +
200
+ required validation. This mirrors the manual CDT analysis's audit-grade evidence trail and
201
+ clear release gate.
202
+
203
+ ### Step 4b: Synthesise the findings
204
+
205
+ From the classification + risk, distil a short **Found issues** list for the top of the
206
+ report — **only realistic, critical items**; omit perfect-world / low-tier concerns (e.g.
207
+ dev-only paths with no production impact, pre-existing standing gaps, or future / in-flight
208
+ fixes). Favour: risky or changed semantics, real deploy/rollout hazards, security-relevant
209
+ changes, and cross-service latent bugs. Each issue = a **bold one-line title** + a 1–3
210
+ sentence description. If there are genuinely none, say so explicitly rather than padding.
211
+
212
+ ### Step 4c: Record what you verified
213
+
214
+ Keep a running list of what you **actually checked** while analysing (e.g. "confirmed
215
+ app/API/test paths identical via `git diff --name-status`", "confirmed dependency pin",
216
+ "ran `git diff --check` (clean)", "verified WAF rules are `preview=true`"). This feeds the
217
+ **Validation performed** section and, together with **Unknowns**, gives an auditable
218
+ evidence trail — what was, and was not, confirmed.
219
+
220
+ ### Step 5: Produce the report
221
+
222
+ Output this structure in Markdown, in this order (the layout must match the published
223
+ report). Every section is required **except** the ones marked *[OPTIONAL]*: *Operational
224
+ context* (include only if significant), and *Required before production* + *Engineer detail*
225
+ (**required for critical releases**; otherwise include only when `detail=engineer`, or the
226
+ release is high-risk / infra-heavy).
227
+
228
+ ```
229
+ # Impact Analysis of Release — <repo> `<base>` → `<head>` (<short change summary>)
230
+
231
+ ## Found issues
232
+
233
+ 1. **<issue title>.** <1–3 sentence description of the issue and why it matters.>
234
+ 2. **<issue title>.** <...>
235
+ <If genuinely none: "No notable issues found — see Overview.">
236
+
237
+ ## Overview
238
+ - **What changed:** <concise 1–2 sentence summary of the change and its intent>
239
+ - **Repo / range:** `<repo>` `<base>` (`<sha>`) → `<head>` (`<sha>`) — <N> commits
240
+ - **Changed:** <N> files, +<X> / -<Y> — `<file>` (+n), `<file>` (+m)
241
+ - **Linked tickets (in this release):** <tickets whose changes survive in the net diff | none referenced>
242
+ - **Reverted in-range (not shipped):** <tickets whose commits were reverted within the range — omit this line entirely if none>
243
+ - **Depth:** <light|full> · **Data sources consulted:** <git, code, jira, outage-status, gcp-logs, bigquery> · **Not consulted:** <sources skipped / unavailable>
244
+ - **Overall risk:** **<LOW|MEDIUM|HIGH>** — <one-line reason>
245
+
246
+ ## Cross-service blast radius
247
+ <shared patterns/contracts other OOF services depend on that this change (or the bug it
248
+ fixes) also affects; "None identified" if isolated>
249
+
250
+ ## Operational context [OPTIONAL — include ONLY if there is something significant to report]
251
+ <Include this section only when live signal is material — e.g. an active outage, a degraded
252
+ dependency, or a notable error/volume pattern in Cloud Logging / BigQuery for a touched
253
+ service. If nothing significant (or live queries were not run), OMIT this section entirely
254
+ and record the "not queried" fact under Unknowns instead.>
255
+
256
+ ## Risk assessment
257
+ **<LOW|MEDIUM|HIGH>.** <justification paragraph; note if live signal changed the rating.>
258
+
259
+ ### Top risks
260
+ <only material, realistic risks — omit perfect-world / low-tier concerns; for critical
261
+ releases tag each with a severity — **High / Med / Low**>
262
+ 1. **<High|Med|Low>** — <...>
263
+ 2. **<High|Med|Low>** — <...>
264
+
265
+ ## Suggested QA focus
266
+ <solely the QA / functional areas a non-coder QA reviewer should confirm — assume engineers
267
+ have already completed their technical and infrastructure checks. Concise, plain-language, no
268
+ code or jargon. For a purely infra change with no user-facing effect, state what to confirm
269
+ still works after go-live.>
270
+
271
+ ## Validation performed
272
+ <short bullet list of what this analysis ACTUALLY checked / verified — the evidence behind the
273
+ conclusions above. E.g. "confirmed app/API/test paths identical", "confirmed dependency pin",
274
+ "ran git diff --check (clean)", "verified WAF rules are preview=true". Pairs with Unknowns.>
275
+
276
+ ## Unknowns / could not determine from available signal
277
+ <explicit list — never leave this empty by guessing; include any source that was
278
+ unavailable, e.g. "no GCP access — live cloud rates not checked">
279
+
280
+ ## Required before production [REQUIRED for critical releases; else OPTIONAL — include when detail=engineer or high-risk / infra-heavy]
281
+ <concrete boxes the release owner must tick before go-live — each naming the *validation*, not
282
+ just the risk; cover auth/deploy, `terraform plan` per env incl. DR, artifact/revision
283
+ expectations, CI vs `.releaserc` alignment, and that the **rollback path** still works under any
284
+ changed auth>
285
+ - [ ] <check 1 — e.g. production Workload Identity auth validated for all prod + DR projects>
286
+ - [ ] <check 2 — e.g. `terraform plan` reviewed per env; no unexpected replace / delete / IAM change>
287
+
288
+ **Recommendation:** **<GO | NO-GO / HOLD>** — <promote only after the named validations pass; one-line rationale.>
289
+
290
+ ## Engineer detail [REQUIRED for critical releases; else OPTIONAL — include only when detail=engineer]
291
+ <the exhaustive, engineer-grade specifics the summary above intentionally omits — **exact
292
+ versions / pins**, **every** affected environment (incl. DR), per-item failure mode + required
293
+ validation, and the deployment/rollback second-order effects (artifact/revision changes,
294
+ provider state drift, CI-vs-`.releaserc` mismatch, rollback-path auth). Kept at the bottom so
295
+ the summary stays readable for non-technical readers.>
296
+
297
+ ---
298
+ *AI-generated by the `oof-release-impact-analysis` skill (BD-8139) · reviewer: TBD · <date> · decision-support only. Range `<base>..<head>`. Rerun with valid GCP credentials to populate live Operational context.*
299
+ ```
300
+
301
+ ### Step 6: Publish (only if `publish=confluence`)
302
+
303
+ - Publish the report as a **child page** of the **Impact Analysis** folder page in the
304
+ **OOF Skills** folder: Confluence space **`BNM1`**, parent page id **`5915476067`**
305
+ (`https://rezolvetech.atlassian.net/wiki/spaces/BNM1/folder/5912657922/OOF+Skills` →
306
+ *Impact Analysis*). Use markdown format, page emoji 🚦. Page **title**:
307
+ `Release Impact Analysis — <repo> <base> → <head> (<summary>)`. The page **body** begins
308
+ with the `# Impact Analysis of Release — …` heading from the template above.
309
+ - Add the Confluence page link back to the release Jira ticket.
310
+ - Never publish if any guardrail check failed.
@@ -0,0 +1,319 @@
1
+ ---
2
+ name: oof-review
3
+ description: >-
4
+ Multi-model code review council inspired by Karpathy's LLM Council. Spawns 3
5
+ sub-agents on different models (Claude Opus 4.8, GPT-5.3 Codex, GPT-5.5) to
6
+ independently review code changes, then synthesizes and votes on the best
7
+ comments to produce a unified, high-signal review. Use when the user says
8
+ /oof-review, /council-review, 'council review', 'multi-model review', 'review
9
+ council', or 'LLM council'.
10
+ ---
11
+
12
+ <!-- Based on the snpd council-review skill. Special thanks to Haris Dervisevic for the original work. -->
13
+
14
+ # LLM Council Code Review
15
+
16
+ ## Purpose
17
+
18
+ Provide a high-quality, consensus-driven code review by running **three independent
19
+ reviewers on different LLM models**, then synthesizing their findings into a single
20
+ review ranked by agreement and severity — similar to
21
+ [Karpathy's LLM Council](https://github.com/karpathy/llm-council).
22
+
23
+ The insight: different models catch different things. One model may spot a race
24
+ condition another misses; one may flag a security issue the others gloss over.
25
+ By requiring consensus, noise drops and signal rises.
26
+
27
+ ## Models Used (The Council)
28
+
29
+ | Seat | Model ID | Strengths |
30
+ |------------|---------------------|-------------------------------------------------|
31
+ | Reviewer A | `claude-opus-4.8` | Deep reasoning, architecture, subtle logic bugs |
32
+ | Reviewer B | `gpt-5.3-codex` | Code-native, practical fixes, test gaps |
33
+ | Reviewer C | `gpt-5.5` | Broad knowledge, security, API design |
34
+
35
+ ## Trigger
36
+
37
+ Activate this skill when the user says any of:
38
+ - `/oof-review`
39
+ - `/council-review`
40
+ - `council review my changes`
41
+ - `multi-model review`
42
+ - `LLM council review`
43
+ - `review council`
44
+
45
+ ## Inputs
46
+
47
+ The user may provide:
48
+ - **No argument** → review local uncommitted changes (staged + unstaged)
49
+ - **`--staged`** → review only staged changes
50
+ - **`--branch [<target>]`** → review current branch diff vs `origin/main` (default) or a custom target, e.g. `--branch origin/develop` or `--branch origin/release/1.2`
51
+ - **`--commits <N>`** → review the last N commits (ignores uncommitted changes)
52
+ - **`--commits <sha>..<sha>`** → review a specific commit range
53
+ - **`--pr <number>`** → review a specific GitHub PR
54
+ - **A file path or glob** → review only those files
55
+
56
+ Natural language also works:
57
+ - "review my last 2 commits" → same as `--commits 2`
58
+ - "review last 3 commits before I open a PR" → same as `--commits 3`
59
+
60
+ ## Workflow
61
+
62
+ ### Phase 0: Repo Discovery
63
+
64
+ Before reviewing any code, discover the **current repo's own rules**. Do not
65
+ carry assumptions from another repo.
66
+
67
+ 1. **Check write-access (advisory):**
68
+
69
+ Read `.claude/settings.local.json` in the repo root (if it exists) and check
70
+ whether it contains `"worktree": { "bgIsolation": "none" }`.
71
+
72
+ - **If the setting is absent or the file does not exist:** Inform the user
73
+ with a one-line notice, then **continue** — do not stop:
74
+
75
+ > ℹ️ `.claude/settings.local.json` does not have `bgIsolation: none`.
76
+ > If the skill is invoked as a background session, writing the report to
77
+ > `docs/reviews/` may fail. See Phase 5 for the fallback.
78
+
79
+ - **If the setting is present:** Continue normally.
80
+
81
+ 2. **Confirm repository scope:**
82
+ - Run `git status --short` and `git branch --show-current`.
83
+ - Identify the repo root and project type.
84
+
85
+ 3. **Discover review configuration:**
86
+ - Check for these files and read them if present:
87
+ - `.github/workflows/claude-pr-review.yml` or `.github/workflows/claude.yml`
88
+ - `.github/workflows/build-pr.yaml`
89
+ - `.github/PULL_REQUEST_TEMPLATE.md`
90
+ - `.github/CODEOWNERS`
91
+ - Run this skill's bundled `summarize_review_config.py` script for a
92
+ quick context summary — it is repo-agnostic and works on any repository.
93
+ Resolve the script from this skill's own base directory and pass the
94
+ current repo root as its argument:
95
+
96
+ ```bash
97
+ # The skill base directory for this repo is: docs/ai/skills/oof-review/
98
+ python3 "docs/ai/skills/oof-review/summarize_review_config.py" .
99
+ ```
100
+
101
+ **This step is MANDATORY. Do NOT skip it.**
102
+ Do NOT fall back to manual reading unless `python3` returns a
103
+ "command not found" error (i.e. Python is genuinely absent on the machine).
104
+ Print the full script output verbatim under a `## Repo Config Summary`
105
+ heading before proceeding to Phase 1.
106
+
107
+ 4. **Discover repo guidance (read if present):**
108
+ - `.github/copilot-instructions.md`
109
+ - `CLAUDE.md`, `AGENTS.md`
110
+ - `docs/conventions.md`, `docs/project-rule.md`, `docs/source-control.md`
111
+ - `README.md` (skim for architecture/setup sections)
112
+
113
+ 5. **Detect technology profile:**
114
+ Scan build files and guidance docs for technology markers. Apply the
115
+ matching profile from `technology-profiles.md` (in this skill's directory). Only apply
116
+ rules that the **current repo actually uses**.
117
+
118
+ Key markers to scan for:
119
+ - Java/Gradle: `build.gradle`, `build.gradle.kts`, `settings.gradle`
120
+ - Maven: `pom.xml`
121
+ - Go: `go.mod`, `Makefile`
122
+ - Python: `pyproject.toml`, `requirements*.txt`
123
+ - Node: `package.json`
124
+
125
+ 6. **Build a PROJECT_CONTEXT block** from all discovered information. This
126
+ block will be injected into every reviewer's prompt so all three models
127
+ review against the same repo-specific rules.
128
+
129
+ ### Phase 0 Completion Checklist
130
+
131
+ Before moving to Phase 1, confirm each item explicitly in your response:
132
+
133
+ | Step | Status | Notes |
134
+ |------|--------|-------|
135
+ | `.claude/settings.local.json` has `bgIsolation: none` | ✅ present / ℹ️ absent (advisory) | |
136
+ | `git status` + current branch | ✅ / ❌ | |
137
+ | `summarize_review_config.py` ran | ✅ ran / ❌ skipped — reason: _______ | Output printed above |
138
+ | Guidance docs read (CLAUDE.md, copilot-instructions, etc.) | ✅ / ❌ | |
139
+ | Technology profile identified | ✅ `<profile name>` | |
140
+
141
+ A model that skips a step **must** write `❌ skipped — reason: <explicit reason>` in
142
+ the table. Silent omission is not acceptable.
143
+
144
+ ### Phase 1: Gather the Diff
145
+
146
+ 1. Determine the review scope based on user input:
147
+ - **Local changes (default):** If working tree has edits, use `git --no-pager diff HEAD`
148
+ (includes staged + unstaged). If working tree is clean but branch has
149
+ commits, compare against the PR base: `git --no-pager diff origin/main...HEAD`.
150
+ If `origin/main` is not available, inspect upstream and available remotes.
151
+ When the user specifies `--branch <target>`, use that target instead of `origin/main`.
152
+ - **Staged only:** `git --no-pager diff --cached`
153
+ - **Branch diff:** `git --no-pager diff <target>...HEAD` where `<target>` is the branch supplied with `--branch` (defaults to `origin/main` when not specified)
154
+ - **Last N commits:** `git --no-pager diff HEAD~N..HEAD` (ignores working tree entirely)
155
+ Example: `--commits 2` → `git --no-pager diff HEAD~2..HEAD`
156
+ - **Commit range:** `git --no-pager diff <sha1>..<sha2>` for explicit ranges
157
+ - **PR:** `gh pr diff <number>`
158
+ 2. Also gather context:
159
+ - `git --no-pager diff --stat` for the file change summary
160
+ - The PROJECT_CONTEXT block built in Phase 0
161
+ 3. If the diff is empty, tell the user and stop.
162
+ 4. If the diff is very large (>5000 lines), warn the user and suggest narrowing scope.
163
+ 5. **Classify the change** (helps reviewers focus):
164
+ - API/controller, service/orchestration, repository/database, search engine,
165
+ Mongo query/indexing, cache, Pub/Sub/messaging, auth/security, feature flags,
166
+ docs, tests, build/dependency, deployment, or tooling.
167
+
168
+ ### Phase 2: Deploy the Council (Parallel Sub-Agents)
169
+
170
+ Launch **exactly 3 `code-review` agents in parallel** using the `task` tool, each
171
+ with a different `model` parameter. All three receive the **identical prompt** so
172
+ their reviews are directly comparable.
173
+
174
+ **CRITICAL: Launch all 3 in a single response — they run in parallel.**
175
+
176
+ Each agent receives the prompt from `reviewer-prompt.md` (in this skill's directory),
177
+ with the diff and project context injected.
178
+
179
+ ```
180
+ Agent A: task(agent_type="code-review", model="claude-opus-4.8", ...)
181
+ Agent B: task(agent_type="code-review", model="gpt-5.3-codex", ...)
182
+ Agent C: task(agent_type="code-review", model="gpt-5.5", ...)
183
+ ```
184
+
185
+ All three agents run in `mode="background"`. Wait for all three to complete
186
+ before proceeding to Phase 3.
187
+
188
+ ### Phase 3: Collect & Parse Reviews
189
+
190
+ Read all three agent results. Each agent returns findings in the structured
191
+ format defined in `reviewer-prompt.md`. Extract:
192
+ - File path and line range for each comment
193
+ - Severity (P1/P2/P3)
194
+ - Category (bug, security, performance, style, test-gap, design)
195
+ - The finding description and suggested fix
196
+
197
+ ### Phase 4: Council Vote — Synthesize & Rank
198
+
199
+ This is the core "council" step. Process the three reviews:
200
+
201
+ #### 4a. Deduplicate
202
+
203
+ Group comments that refer to the **same issue** (same file, overlapping lines,
204
+ same root cause). Two comments are "the same issue" if they:
205
+ - Point to the same file and overlapping line range, AND
206
+ - Describe the same underlying problem (even in different words)
207
+
208
+ #### 4b. Score by Agreement
209
+
210
+ For each unique issue, count how many of the 3 reviewers flagged it:
211
+
212
+ | Agreement | Label | Weight |
213
+ |-----------|--------------|--------|
214
+ | 3/3 | 🟢 Unanimous | High |
215
+ | 2/3 | 🟡 Majority | Medium |
216
+ | 1/3 | 🔵 Solo | Low |
217
+
218
+ #### 4c. Rank
219
+
220
+ Sort the final list by:
221
+ 1. **Agreement** (unanimous > majority > solo)
222
+ 2. **Severity** (P1 > P2 > P3) within each agreement tier
223
+ 3. Within the same tier+severity, keep the most actionable/clear version of
224
+ the comment (pick the best phrasing from whichever model wrote it)
225
+
226
+ #### 4d. Solo Comment Filter
227
+
228
+ Solo comments (1/3) are **not discarded** but are presented separately under
229
+ a "Minority Opinions" section. They may contain genuine catches the other
230
+ models missed, or they may be noise. Let the user decide.
231
+
232
+ ### Phase 5: Write and Present the Council Review
233
+
234
+ 1. **Determine the output file path.**
235
+ Use the format: `docs/reviews/oof-review-<YYYY-MM-DD>-<branch-or-scope>.md`
236
+ - Replace `<YYYY-MM-DD>` with today's date.
237
+ - Replace `<branch-or-scope>` with the sanitized current branch name (slashes → dashes)
238
+ or a short descriptor when reviewing uncommitted changes (e.g. `local-changes`).
239
+ - Example: `docs/reviews/oof-review-2026-08-18-feature-my-branch.md`
240
+
241
+ 2. **Write the review to the file** using the format in `output-format.md`
242
+ (in this skill's directory). Create the `docs/reviews/` directory if it does not exist.
243
+
244
+ > **IMPORTANT — do NOT enter a worktree.** Write the file directly to the
245
+ > user's current working tree using the Write tool. Entering a worktree
246
+ > creates an isolated branch and an extra checkout of the repository, which
247
+ > is unnecessary and confusing for a read-only report file.
248
+ >
249
+ > **Do NOT `git add`, `git commit`, or run any git command after writing.**
250
+ > The deliverable is the file on disk. The user decides whether and when to
251
+ > commit it.
252
+
253
+ **If writing fails** (e.g. the isolation guard is still active despite the
254
+ Phase 0 check): print the **full review content** as a fenced Markdown
255
+ block in chat, prefixed with:
256
+
257
+ > ⚠️ Could not write to disk — see below. Paste this into
258
+ > `docs/reviews/<filename>.md` manually, or add
259
+ > `"worktree": {"bgIsolation": "none"}` to `.claude/settings.local.json` and re-run.
260
+
261
+ 3. **Confirm in chat** — after writing the file, post a short summary message:
262
+ ```
263
+ ✅ Council review written to `docs/reviews/council-review-<date>-<scope>.md`
264
+ Verdict: <PASS | PASS WITH COMMENTS | NEEDS CHANGES>
265
+ Top findings: <1-line summary of the highest-priority issues>
266
+ ```
267
+
268
+ ## Hard Rules
269
+
270
+ - **Identical prompts.** All three reviewers get exactly the same input.
271
+ Do not customize prompts per model — the whole point is fair comparison.
272
+ - **No model bias.** Do not weight one model's opinion over another during
273
+ voting. Agreement count is the only ranking signal.
274
+ - **Parallel launch.** Always launch all 3 agents in a single response.
275
+ Never run them sequentially.
276
+ - **Transparency.** Always show which models agreed on each finding.
277
+ - **No hallucinated code.** Do not generate suggested replacement code
278
+ yourself during synthesis. Use the reviewers' suggestions as-is.
279
+ - **Severity consistency.** If reviewers disagree on severity for the same
280
+ issue, use the highest severity any reviewer assigned.
281
+ - **Signal over noise.** The council exists to reduce noise. If a comment
282
+ is unclear or contradictory across reviewers, note the disagreement rather
283
+ than forcing consensus.
284
+ - **No worktree for review output.** Writing the review file is not a code
285
+ change. Do not call `EnterWorktree` at any point during this skill.
286
+ - **No auto-commit.** Do not run any git command after writing the review
287
+ file. The user owns the commit decision.
288
+
289
+ ## Configuration
290
+
291
+ The user can customize the council by telling the agent:
292
+ - Different models: "use Opus 4.5 instead of Opus 4.8"
293
+ - Different number of reviewers: "use 5 models" (but default is 3)
294
+ - Focus areas: "focus on security" or "focus on performance"
295
+ - Strictness: "be strict" (lower the noise threshold) or "only critical" (P1 only)
296
+
297
+ ## Error Handling
298
+
299
+ - If one agent fails, proceed with the remaining 2. Note the failure.
300
+ - If two agents fail, fall back to a single-model review and explain.
301
+ - If all three fail, tell the user and suggest running a simple code-review instead.
302
+
303
+ ## Phase 6 (Optional): Post-Review Verification
304
+
305
+ After presenting the council review, **offer** to run verification. Do not
306
+ run automatically — the user may just want the review.
307
+
308
+ If the user accepts:
309
+
310
+ 1. **Run targeted tests** for changed files using the repo's test command
311
+ (discovered in Phase 0). Prefer the narrowest test scope first.
312
+ 2. **Run the PR build command** when feasible (from `build-pr.yaml`).
313
+ 3. **Run `git --no-pager diff --check`** for whitespace issues.
314
+ 4. **Check PR template compliance** — if the repo has a PR template with
315
+ checkboxes, note which items are affected by the change.
316
+ 5. **Report CODEOWNERS** — if the repo has CODEOWNERS, note which owners
317
+ are relevant for the changed files.
318
+
319
+ Append verification results to the review output.
@@ -0,0 +1,166 @@
1
+ # Council Review Output Format
2
+
3
+ Use this format when presenting the synthesized council review to the user.
4
+
5
+ ---
6
+
7
+ ## Header
8
+
9
+ ```
10
+ # 🏛️ LLM Council Code Review
11
+
12
+ **Scope:** <description of what was reviewed — branch, PR #, local changes>
13
+ **Council:** Claude Opus 4.8 · GPT-5.3 Codex · GPT-5.5
14
+ **Date:** <current date>
15
+ **Verdict:** <PASS | PASS WITH COMMENTS | NEEDS CHANGES>
16
+ ```
17
+
18
+ ### Verdict Rules
19
+ - **PASS** — No P1 or P2 issues found by any reviewer
20
+ - **PASS WITH COMMENTS** — No P1 issues; some P2/P3 found
21
+ - **NEEDS CHANGES** — At least one P1 issue found, OR 3+ P2 issues with majority agreement
22
+
23
+ ---
24
+
25
+ ## Consensus Findings (2/3 or 3/3 agreement)
26
+
27
+ These are issues flagged by multiple models independently. High confidence.
28
+
29
+ **Severity-based format for consensus findings:**
30
+
31
+ > [!IMPORTANT]
32
+ > **Emoji legend — use this table as the single source of truth. Do NOT apply the P3 majority emoji (🟡) to P2 findings.**
33
+ >
34
+ > | Severity | Unanimous (3/3) | Majority (2/3) | Solo (1/3) |
35
+ > |----------|----------------|----------------|------------|
36
+ > | P1 | 🚨 | 🚨 | 🚨 |
37
+ > | P2 | 🔴 | 🔴 | 🔴 |
38
+ > | P3 | 🔴 | 🟡 | 🔵 |
39
+ >
40
+ > The only cell that uses 🟡 is **P3 + Majority (2/3)**. Every other P2 cell is 🔴.
41
+
42
+ For **P1 (Critical)** consensus findings, wrap in a `> [!CAUTION]` blockquote regardless of agreement level:
43
+
44
+ ```
45
+ > [!CAUTION]
46
+ > ### 🚨 <N>. <One-line summary> — CRITICAL
47
+ > 🚨 Unanimous (3/3) | 🚨 Majority (2/3) — **Severity: P1**
48
+ > **Category:** <category>
49
+ > **File:** `<path>` (lines ~<range>)
50
+ > **Agreed by:** Opus 4.8 ✓ · Codex 5.3 ✓ · GPT-5.5 ✓
51
+ >
52
+ > <Best description from the reviewers. Pick the clearest, most actionable version.>
53
+ >
54
+ > **Suggested fix:**
55
+ > <Most concrete suggestion from any reviewer.>
56
+ ```
57
+
58
+ For **P2 (Important)** consensus findings — **both unanimous AND majority use 🔴**:
59
+
60
+ ```
61
+ ### <N>. <One-line summary>
62
+ 🔴 Unanimous (3/3) | 🔴 Majority (2/3) ← both red for P2
63
+ **Severity:** P2
64
+ **Category:** <category>
65
+ **File:** `<path>` (lines ~<range>)
66
+ **Agreed by:** Opus 4.8 ✓ · Codex 5.3 ✓ · GPT-5.5 ✓
67
+
68
+ <Best description from the reviewers. Pick the clearest, most actionable version.>
69
+
70
+ **Suggested fix:**
71
+ <Most concrete suggestion from any reviewer.>
72
+ ```
73
+
74
+ For **P3 (Minor)** consensus findings — **majority drops to 🟡 (yellow), unlike P2 which stays 🔴)**:
75
+
76
+ ```
77
+ ### <N>. <One-line summary>
78
+ 🔴 Unanimous (3/3) | 🟡 Majority (2/3) ← majority is yellow ONLY for P3
79
+ **Severity:** P3
80
+ **Category:** <category>
81
+ **File:** `<path>` (lines ~<range>)
82
+ **Agreed by:** Opus 4.8 ✓ · Codex 5.3 ✓ · GPT-5.5 ✓
83
+
84
+ <Best description from the reviewers. Pick the clearest, most actionable version.>
85
+
86
+ **Suggested fix:**
87
+ <Most concrete suggestion from any reviewer.>
88
+ ```
89
+
90
+ ---
91
+
92
+ ## Minority Opinions (1/3 — solo catches)
93
+
94
+ These were flagged by only one model. They may be genuine catches the others
95
+ missed, or false positives. Included for completeness.
96
+
97
+ **Severity-based indicators for solo catches:**
98
+ - P1 (Critical): Use `🚨 CRITICAL — Solo catch by <model name>` — render with a blockquote warning prefix to make it visually unmissable
99
+ - P2 (Important): Use `🔴 Solo — flagged by <model name> only`
100
+ - P3 (Minor): Use `🔵 Solo — flagged by <model name> only`
101
+
102
+ For P1 solo catches, wrap the entire finding in a `> [!CAUTION]` blockquote to trigger a rendered red alert panel:
103
+
104
+ ```
105
+ > [!CAUTION]
106
+ > ### 🚨 <N>. <One-line summary> — CRITICAL SOLO CATCH
107
+ > 🚨 CRITICAL — Solo catch by <model name> only — **not confirmed by other reviewers but high-impact if correct**
108
+ > **Severity:** P1
109
+ > **Category:** <category>
110
+ > **File:** `<path>` (lines ~<range>)
111
+ >
112
+ > <Description from the flagging model.>
113
+ >
114
+ > **Suggested fix:**
115
+ > <Suggestion if provided.>
116
+ ```
117
+
118
+ For P2/P3 solo catches, use the standard format:
119
+
120
+ ```
121
+ ### <N>. <One-line summary>
122
+ 🔴 Solo — flagged by <model name> only ← use 🔴 for P2, 🔵 for P3
123
+ **Severity:** P2 | P3
124
+ **Category:** <category>
125
+ **File:** `<path>` (lines ~<range>)
126
+
127
+ <Description from the flagging model.>
128
+
129
+ **Suggested fix:**
130
+ <Suggestion if provided.>
131
+ ```
132
+
133
+ ---
134
+
135
+ ## Review Statistics
136
+
137
+ ```
138
+ | Metric | Value |
139
+ |---------------------------|-------|
140
+ | Total unique issues | <N> |
141
+ | Unanimous (3/3) | <N> |
142
+ | Majority (2/3) | <N> |
143
+ | Solo (1/3) | <N> |
144
+ | P1 (Critical) | <N> |
145
+ | P2 (Important) | <N> |
146
+ | P3 (Minor) | <N> |
147
+ | Files reviewed | <N> |
148
+ | Lines changed | +<N> / -<N> |
149
+ ```
150
+
151
+ ---
152
+
153
+ ## Model Agreement Matrix (optional, for large reviews)
154
+
155
+ Show which model caught what. Only include for reviews with 5+ findings.
156
+
157
+ ```
158
+ | # | Finding | Opus 4.8 | Codex 5.3 | GPT-5.5 |
159
+ |---|--------------------------------|----------|-----------|---------|
160
+ | 1 | Race condition in UserService | ✓ | ✓ | ✓ |
161
+ | 2 | Missing null check in parser | ✓ | ✓ | |
162
+ | 3 | SQL injection in search filter | | ✓ | ✓ |
163
+ | 4 | Unused import (solo) | ✓ | | |
164
+ ```
165
+
166
+ ---
@@ -0,0 +1,99 @@
1
+ # Reviewer Prompt Template
2
+
3
+ You are one member of a 3-model code review council. Your job is to independently
4
+ review the code changes below and produce high-signal findings. Another process
5
+ will compare your review against two other models' reviews to find consensus.
6
+
7
+ ## Your Review Constraints
8
+
9
+ - **Only flag things that genuinely matter.** Bugs, security issues, logic errors,
10
+ performance problems, missing error handling, test gaps for changed code.
11
+ - **Never comment on style, formatting, naming preferences, or trivial matters**
12
+ unless they cause a real problem (e.g., a misleading variable name that could
13
+ cause a bug).
14
+ - **Be specific.** Always include the file path, approximate line range, and a
15
+ concrete description of the problem.
16
+ - **Suggest a fix** when possible. Don't just say "this is wrong" — say what to do.
17
+ - **Don't be redundant.** If two issues share the same root cause, report it once.
18
+ - **Respect repo-specific rules.** The project context below includes this repo's
19
+ own conventions, technology profile, and CI expectations. Review against THOSE
20
+ rules, not generic best practices. Do not assume patterns from other repos.
21
+
22
+ ## Project Context
23
+
24
+ {PROJECT_CONTEXT}
25
+
26
+ This context was discovered from the repo's own guidance files, CI workflows,
27
+ build configuration, and technology markers. If the context mentions specific
28
+ patterns (e.g., Micronaut DI, tenant isolation, cache key format), verify the
29
+ diff follows them. If the context is silent on something, don't invent rules.
30
+
31
+ ## Technology Profile
32
+
33
+ {TECHNOLOGY_PROFILE}
34
+
35
+ ## Change Classification
36
+
37
+ {CHANGE_CLASSIFICATION}
38
+
39
+ ## Review Focus Areas (from repo's CI/review config)
40
+
41
+ Review against these standard areas, but weight them based on the change
42
+ classification above:
43
+
44
+ 1. **Code quality:** single responsibility, clarity, maintainability, unnecessary
45
+ complexity/nesting, redundant abstractions, local style conventions.
46
+ 2. **Security:** auth, authorization, tenant isolation, input validation, secrets,
47
+ sensitive data exposure.
48
+ 3. **Performance:** database/query shape, cache behavior, external calls,
49
+ async/blocking boundaries, memory/resource lifecycle.
50
+ 4. **Testing:** adequate coverage for changed code, edge cases, missing scenarios.
51
+ 5. **Documentation:** README/docs/OpenAPI/API docs accuracy when behavior changes.
52
+
53
+ ## Changed Files Summary
54
+
55
+ {DIFF_STAT}
56
+
57
+ ## Full Diff
58
+
59
+ {DIFF}
60
+
61
+ ## Output Format
62
+
63
+ Return your findings as a structured list. Each finding must follow this exact format:
64
+
65
+ ```
66
+ ### Finding <N>
67
+ - **File:** <path/to/file>
68
+ - **Lines:** <start>-<end> (approximate)
69
+ - **Severity:** P1 | P2 | P3
70
+ - **Category:** bug | security | performance | design | test-gap | error-handling | concurrency | data-integrity
71
+ - **Summary:** <one-line summary>
72
+ - **Details:** <1-3 sentences explaining the issue>
73
+ - **Suggestion:** <concrete fix or action>
74
+ ```
75
+
76
+ ### Severity Guide
77
+
78
+ - **P1 — Critical:** Likely bug, security vulnerability, data loss, crash, race condition,
79
+ or production incident. Must fix before merge.
80
+ - **P2 — Important:** Behavior regression, missing important test, incorrect error handling,
81
+ performance issue under realistic load. Should fix before merge.
82
+ - **P3 — Minor:** Low-risk test gap, minor inefficiency, documentation inaccuracy.
83
+ Nice to fix but not blocking.
84
+
85
+ ### What NOT to Report
86
+
87
+ - Style or formatting preferences
88
+ - "Consider renaming X" suggestions
89
+ - "Add a comment explaining Y" suggestions
90
+ - Import ordering
91
+ - Trailing whitespace
92
+ - Suggestions that don't prevent a real problem
93
+
94
+ If you find zero genuine issues, return:
95
+
96
+ ```
97
+ ### No Issues Found
98
+ The changes look correct. No bugs, security issues, or significant concerns identified.
99
+ ```
@@ -0,0 +1,226 @@
1
+ #!/usr/bin/env python3
2
+ """Summarize PR review and CI configuration for a repository.
3
+
4
+ Repo-agnostic: takes the repository root as its argument (defaults to the current
5
+ directory) and works on any project. Uses only the Python standard library so it
6
+ can run in sandboxes without installing PyYAML or other dependencies.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import argparse
12
+ import re
13
+ from pathlib import Path
14
+
15
+
16
+ GUIDANCE_FILES = [
17
+ ".github/copilot-instructions.md",
18
+ "CLAUDE.md",
19
+ "AGENTS.md",
20
+ "README.md",
21
+ "docs/conventions.md",
22
+ "docs/project-rule.md",
23
+ "docs/source-control.md",
24
+ ]
25
+
26
+ REVIEW_FILES = [
27
+ ".github/workflows/claude-pr-review.yml",
28
+ ".github/workflows/claude.yml",
29
+ ".github/workflows/build-pr.yaml",
30
+ ".github/PULL_REQUEST_TEMPLATE.md",
31
+ ".github/CODEOWNERS",
32
+ ]
33
+
34
+ BUILD_FILES = [
35
+ "build.gradle",
36
+ "build.gradle.kts",
37
+ "settings.gradle",
38
+ "gradle.properties",
39
+ "pom.xml",
40
+ "go.mod",
41
+ "Makefile",
42
+ "pyproject.toml",
43
+ "requirements.txt",
44
+ "package.json",
45
+ ]
46
+
47
+ KEYWORDS = [
48
+ "Micronaut",
49
+ "Java 21",
50
+ "Java 17",
51
+ "Spring",
52
+ "Lombok",
53
+ "Spock",
54
+ "JUnit",
55
+ "Mockito",
56
+ "Testcontainers",
57
+ "JOOQ",
58
+ "jOOQ",
59
+ "Flyway",
60
+ "PostgreSQL",
61
+ "Mongo",
62
+ "Redis",
63
+ "Google Retail",
64
+ "Command Center",
65
+ "Pub/Sub",
66
+ "BigQuery",
67
+ "LaunchDarkly",
68
+ "ANTLR",
69
+ "Kafka",
70
+ "JWT",
71
+ "Docker",
72
+ "Jib",
73
+ ]
74
+
75
+
76
+ def read(path: Path) -> str:
77
+ try:
78
+ return path.read_text(errors="replace")
79
+ except FileNotFoundError:
80
+ return ""
81
+
82
+
83
+ def existing(root: Path, paths: list[str]) -> list[Path]:
84
+ return [root / path for path in paths if (root / path).exists()]
85
+
86
+
87
+ def first_match(pattern: str, text: str) -> str | None:
88
+ match = re.search(pattern, text, re.MULTILINE)
89
+ return match.group(1).strip() if match else None
90
+
91
+
92
+ def command_lines(text: str) -> list[str]:
93
+ commands: list[str] = []
94
+ for line in text.splitlines():
95
+ stripped = line.strip()
96
+ candidate = stripped
97
+ if stripped.startswith("run:"):
98
+ candidate = stripped.removeprefix("run:").strip()
99
+ if re.match(r"^(\.?/gradlew|gradle|mvn|make|go\s+test|pytest|npm|pnpm|yarn|docker)\b", candidate):
100
+ commands.append(candidate)
101
+ return commands
102
+
103
+
104
+ def pr_checkboxes(text: str) -> list[str]:
105
+ checks = []
106
+ for line in text.splitlines():
107
+ if re.match(r"\s*-\s+\[[ xX]\]", line):
108
+ checks.append(line.strip())
109
+ return checks
110
+
111
+
112
+ def collect_keywords(text: str) -> list[str]:
113
+ found = []
114
+ lower_text = text.lower()
115
+ for keyword in KEYWORDS:
116
+ if keyword.lower() in lower_text:
117
+ found.append(keyword)
118
+ normalized = []
119
+ seen = set()
120
+ for keyword in found:
121
+ key = keyword.lower()
122
+ if key not in seen:
123
+ seen.add(key)
124
+ normalized.append(keyword)
125
+ return sorted(normalized, key=str.lower)
126
+
127
+
128
+ def main() -> int:
129
+ parser = argparse.ArgumentParser(description=__doc__)
130
+ parser.add_argument("repo", nargs="?", default=".", help="Repository root")
131
+ args = parser.parse_args()
132
+
133
+ root = Path(args.repo).resolve()
134
+ print(f"# PR Review Configuration Summary\n")
135
+ print(f"Repository: `{root}`\n")
136
+
137
+ review_files = existing(root, REVIEW_FILES)
138
+ guidance_files = existing(root, GUIDANCE_FILES)
139
+ build_files = existing(root, BUILD_FILES)
140
+
141
+ print("## Files Found\n")
142
+ for title, files in [
143
+ ("Review/CI", review_files),
144
+ ("Guidance", guidance_files),
145
+ ("Build", build_files),
146
+ ]:
147
+ print(f"### {title}")
148
+ if files:
149
+ for path in files:
150
+ print(f"- `{path.relative_to(root)}`")
151
+ else:
152
+ print("- none")
153
+ print()
154
+
155
+ claude_text = read(root / ".github/workflows/claude-pr-review.yml")
156
+ if not claude_text:
157
+ claude_text = read(root / ".github/workflows/claude.yml")
158
+ build_text = read(root / ".github/workflows/build-pr.yaml")
159
+ pr_template = read(root / ".github/PULL_REQUEST_TEMPLATE.md")
160
+ codeowners = read(root / ".github/CODEOWNERS")
161
+ guidance_text = "\n\n".join(read(path) for path in guidance_files)
162
+ build_texts = "\n\n".join(read(path) for path in build_files)
163
+
164
+ print("## Claude Review\n")
165
+ if claude_text:
166
+ triggers = re.findall(r"types:\s*\[([^\]]+)\]", claude_text)
167
+ model = first_match(r"--model\s+([^\s]+)", claude_text)
168
+ print(f"- Workflow present: yes")
169
+ print(f"- Trigger type lists: {', '.join(triggers) if triggers else 'not parsed'}")
170
+ print(f"- Model: {model or 'not parsed'}")
171
+ print("- Standard focus areas present:")
172
+ for area in ["Code Quality", "Security", "Performance", "Testing", "Documentation"]:
173
+ print(f" - {area}: {'yes' if area in claude_text else 'not found'}")
174
+ else:
175
+ print("- Workflow present: no")
176
+ print()
177
+
178
+ print("## PR CI Commands\n")
179
+ commands = command_lines(build_text)
180
+ if commands:
181
+ for command in commands:
182
+ print(f"- `{command}`")
183
+ else:
184
+ print("- none parsed")
185
+ print()
186
+
187
+ java_version = first_match(r"java-version:\s*['\"]?([^'\"\n]+)", build_text)
188
+ if java_version:
189
+ print(f"Java version from PR workflow: `{java_version}`\n")
190
+
191
+ print("## PR Template Checks\n")
192
+ checks = pr_checkboxes(pr_template)
193
+ if checks:
194
+ for check in checks:
195
+ print(f"- {check}")
196
+ else:
197
+ print("- none")
198
+ print()
199
+
200
+ print("## CODEOWNERS\n")
201
+ owners = [line.strip() for line in codeowners.splitlines() if line.strip() and not line.strip().startswith("#")]
202
+ if owners:
203
+ for owner in owners:
204
+ print(f"- `{owner}`")
205
+ else:
206
+ print("- none")
207
+ print()
208
+
209
+ print("## Detected Keywords\n")
210
+ keywords = collect_keywords("\n\n".join([guidance_text, build_texts, claude_text, build_text]))
211
+ if keywords:
212
+ for keyword in keywords:
213
+ print(f"- {keyword}")
214
+ else:
215
+ print("- none")
216
+ print()
217
+
218
+ print("## Suggested Next Steps\n")
219
+ print("- Review changed files against the discovered keywords and guidance files.")
220
+ print("- Run targeted tests first, then the PR build command if feasible.")
221
+ print("- Run `git --no-pager diff --check` before final output.")
222
+ return 0
223
+
224
+
225
+ if __name__ == "__main__":
226
+ raise SystemExit(main())
@@ -0,0 +1,54 @@
1
+ # Technology Profiles
2
+
3
+ Apply a profile **only** when discovered in the current repo's files.
4
+ Do not carry assumptions from one repo to another.
5
+
6
+ ## Java / Micronaut
7
+
8
+ - Check the Java version from workflow and Gradle config (do not assume 21 — some repos use 17).
9
+ - Use Micronaut compile-time DI patterns; avoid Spring Boot assumptions unless the repo is Spring-based.
10
+ - Prefer constructor injection and the Lombok annotations already used locally.
11
+ - Follow the repo's `var` rule (many Rezolve Java repos use `var` for new variables created with `new`).
12
+ - Check `@Singleton` vs `@Context` scope, `@Named` qualifiers, `@ExecuteOn` boundaries.
13
+ - Verify blocking operations are not on the event loop thread.
14
+
15
+ ## JOOQ / Flyway / Database
16
+
17
+ - Migration names and generated classes matter — check naming conventions.
18
+ - Check tenant isolation on queries and mutation side effects (events, audit logs).
19
+ - Verify transaction boundaries and connection management.
20
+
21
+ ## Search Services
22
+
23
+ - Check strategy and engine selection order.
24
+ - Ensure request builders, filters, refinements, biasing, pagination, and response builders preserve behavior.
25
+ - For Google Retail: check proto conversion, request fields, fallback behavior.
26
+ - For Mongo Atlas Search: check aggregation stages, index assumptions, field paths, unsupported Google-only features.
27
+ - For Redis caches: check key composition, tenant/collection/area isolation, TTLs, skip-cache paths.
28
+
29
+ ## Mongo Data / Indexing
30
+
31
+ - Check collection and tenant scoping.
32
+ - Check aggregation pipeline correctness, projections, variant/inventory handling.
33
+ - Check index definition generation, conditional indexing, feature flags.
34
+
35
+ ## Authentication / Security
36
+
37
+ - Check token validation, claims, expiration, signature algorithms, public endpoint boundaries.
38
+ - Check Redis key storage, key rotation, secret handling.
39
+ - Check Pub/Sub credential update idempotency.
40
+
41
+ ## Go / Python / Node
42
+
43
+ - Prefer repo-provided commands from Makefile, package files, workflow files, or docs.
44
+ - Keep tests close to the changed package/module.
45
+ - Check schema/serialization compatibility and environment variable handling.
46
+ - Do not import Java/Micronaut assumptions into these repos.
47
+
48
+ ## General (all profiles)
49
+
50
+ - **Code quality:** Single responsibility, clarity, maintainability, unnecessary complexity.
51
+ - **Security:** Auth, authorization, tenant isolation, input validation, secrets.
52
+ - **Performance:** Database/query shape, cache behavior, external calls, async/blocking.
53
+ - **Testing:** Adequate coverage for changed code, edge cases, no superfluous tests.
54
+ - **Documentation:** README/docs/OpenAPI accuracy when behavior changes.