@groupby/ai-dev 0.5.18 → 0.5.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groupby/ai-dev",
-  "version": "0.5.18",
+  "version": "0.5.19",
   "description": "Interactive installer for Rezolve Ai development content",
   "type": "module",
   "bin": {

package/teams/OOF/skills/oof-release-impact-analysis/README.md

@@ -0,0 +1,37 @@
+# OOF Release Impact Analysis
+
+Generates a structured, human-reviewed **Release Impact Analysis** for a critical OOF
+release by correlating the git diff with the surrounding code, linked Jira tickets, and
+live operational signal (GCP Cloud Logging / BigQuery), then optionally publishes it to
+Confluence. Output is AI-generated decision-support and requires human sign-off.
+
+## What it does
+- Resolves the release range (last prod tag → release candidate, or a supplied `base..head`)
+  and gathers signal: diff + changed code and its call sites, linked Jira keys (revert-aware),
+  and — for critical releases — live cloud/outage status, GCP Cloud Logging, and BigQuery.
+- Classifies the blast radius (API/contract, DB/migrations, auth/security, infra/terraform,
+  per-region config, dependencies, cross-service, client compatibility, observability).
+- Produces a consistent, readable report: Found issues → Overview → Cross-service blast
+  radius → Risk assessment + Top risks → Suggested QA focus (non-technical) → Validation
+  performed → Unknowns; with optional Operational context, Pre-launch checklist, and an
+  Engineer detail appendix (`detail=engineer`).
+- Optionally publishes the report to Confluence.
+
+## Prerequisites
+- Read-only git access to the target repo (local clone or `glab` / `gh`).
+- For `depth=full` cloud signal: `gcloud` / `bq` authenticated to the target GCP project.
+- For `publish=confluence`: the Atlassian MCP connector connected.
+- An approved enterprise assistant (no-training / no-retention) — the skill's security
+  guardrails (never ingest secrets, cost-aware cloud access) must be met.
+
+## Inputs
+`repo`, `range`, `critical`, `depth` (`light` | `full`), `detail` (`summary` | `engineer`),
+`publish` (`confluence` | `none`), `gcp_project`.
+
+## Trigger phrases
+- "run impact analysis"
+- "release impact analysis"
+- "analyse this release before we ship"
+
+## Team
+OOF

package/teams/OOF/skills/oof-release-impact-analysis/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: oof-release-impact-analysis
+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.'
+---
+
+# OOF Release Impact Analysis
+
+**Goal:** For a critical release, produce a structured, human-reviewed **Release Impact
+Analysis** that focuses QA, documents blast radius, and serves as SOC2 change-management
+evidence. The git diff is the *starting point*, not the whole picture — the analysis
+correlates the diff with the surrounding code, the linked Jira tickets, and **live
+operational signal** (cloud/outage status, GCP Cloud Logging, BigQuery) to judge real-world
+impact, not just what a static diff shows.
+
+**Your Role:** You are a release engineer performing change-impact analysis. You are
+precise and conservative: you never overstate confidence, you flag what you *cannot*
+determine from the available signal, and you treat the output as decision-support for a
+human reviewer — never as an automatic release gate.
+
+> ⚠️ AI-generated. This report assists a human decision. It must be reviewed and
+> signed off before it is relied upon. A release is never gated solely on this output.
+
+> 💰 **This deep, multi-source analysis is thorough but expensive** — it burns
+> engineer/agent time, LLM tokens, and real query cost (GCP Logging / BigQuery scanned
+> bytes). Run the **full** analysis only for **critical** releases, and **confirm depth up
+> front** (Step 0) rather than defaulting into it. Non-critical releases should use the
+> lightweight, git-only pass (`depth=light`, no cloud queries, no publish) — or skip the
+> analysis entirely.
+
+## Inputs
+
+- **repo** — Repository to analyse (defaults to the current workspace repo).
+- **range** (optional) — Git range `<base>..<head>`. If omitted, resolve it (see Step 1).
+- **critical** (optional) — Whether this is a critical release. Critical forces `depth=full`
+  **and** `detail=engineer`, and turns on the CDT-parity uplift (deployment/rollback
+  second-order analysis, per-risk severities, a mandatory **Required before production** gate
+  + go/no-go recommendation, and an exhaustive engineer-detail appendix).
+- **depth** (optional) — `light` (git + code only) or `full` (also pulls Jira, cloud/outage
+  status, GCP logs, BigQuery). Defaults to `full` when `critical`, else `light`.
+- **detail** (optional) — output verbosity: `summary` (default) or `engineer`. `engineer`
+  appends the **Required before production** gate and an **Engineer detail** appendix for
+  high-risk / infra-heavy releases; the readable summary stays on top either way. **Critical
+  releases force `engineer`.**
+- **publish** (optional) — `confluence` to publish the report, or `none` (default) to
+  only produce Markdown.
+- **gcp_project** (optional) — GCP project(s) to query for logs/BigQuery (e.g.
+  `bluedot-prod-ause1`). Required for `depth=full` cloud signal.
+
+## Security guardrails (MANDATORY — read before running)
+
+1. **Approved LLM only.** Run this only via an approved enterprise assistant with
+   no-training / no-retention terms. Do not paste diffs into ad-hoc consumer tools.
+2. **Never ingest secrets.** Exclude and never echo the contents of secret-bearing files.
+   Deny-list at minimum: `*.env`, `_config.*.env`, `*.pem`, `*.key`, `*credentials*`,
+   `*secret*`, `serviceAccount*.json`, terraform state, `*.tfvars`. If a diff touches one,
+   report **only the filename and that it changed** — never the values.
+3. **Least privilege.** Read-only git access. Do not push, tag, or modify anything.
+4. **Access-controlled output.** Publish only to an access-controlled Confluence space.
+   Do not expose internal implementation detail to a broad audience.
+5. **Cost-aware cloud access.** GCP Logging / BigQuery queries cost money and scan real
+   data. Always bound queries by the release time window + relevant service/resource, cap
+   scanned bytes, and prefer summaries/counts over dumping rows. Never run unbounded
+   `SELECT *`. Read-only only.
+6. **HALT** if you cannot confirm guardrails 1–2 for the current environment.
+
+## Signal sources (the diff is the starting point, not the whole picture)
+
+Git tells you *what text changed*; these sources tell you *what it actually affects and
+whether it is safe to ship now*. Use them according to `depth`:
+
+- **Git diff + history** (always) — changed files, churn, commit messages, linked tickets.
+- **Surrounding code** (always) — read the changed functions *and their call sites /
+  dependents* in the repo, not just the `+/-` lines, to judge real blast radius. A one-line
+  change to a shared helper can be higher impact than a large isolated feature.
+- **Linked Jira tickets** (`full`) — pull the `BD-xxxx` keys for intent, acceptance
+  criteria, and whether the change is a fix for a known incident.
+- **Cloud / outage status** (`full`) — is the platform currently healthy? Check GCP service
+  health and any ongoing SRE incidents for the target project/region. Releasing into an
+  active outage or degraded dependency raises risk and may warrant a hold.
+- **GCP Cloud Logging (Logs Explorer)** (`full`) — for the services touched, check recent
+  error rates / 5xx / notable log signatures so the analysis reflects the *current* prod
+  behaviour of the code being changed (bounded to a short window).
+- **BigQuery** (`full`) — where relevant (e.g. event/analytics tables), sample real volumes
+  or error patterns for the affected flow (bounded, capped-bytes, aggregate queries only).
+
+## Execution
+
+### Step 0: Confirm scope & depth (ask before spending)
+
+The full analysis costs real time and money, so **confirm depth up front** rather than
+silently defaulting into the expensive path. Unless the user has already specified, ask:
+
+- **Critical release?** The full multi-source pass is intended for critical releases only.
+- **Depth?** `full` — code + Jira + cloud/outage status + GCP Logging + BigQuery: thorough,
+  but burns agent time, LLM tokens, and **real GCP query charges** (Logging + BigQuery
+  scanned bytes). `light` — git + code only: fast and free, no cloud queries, no publish.
+- **Publish?** `confluence`, or Markdown-only (`none`).
+
+If the user defers, default to `full` + `detail=engineer` + publish when `critical`, else
+`light` + `none` — but **don't assume `full` for an unspecified release; ask first.**
+Non-critical releases use `light` or skip the analysis entirely. State the chosen depth (and
+why) at the top of the report.
+
+### Step 1: Resolve the release range
+
+- If `range` is given, use it.
+- Otherwise resolve `<base>` = most recent production tag/release, `<head>` = the release
+  candidate (target branch or RC tag). Prefer, in order:
+  - `git describe --tags --abbrev=0` on the last prod tag, or the last tag matching the
+    project's release pattern (e.g. semantic-release tags), through `HEAD`.
+- State the resolved `base..head`, both short SHAs, and the commit count. If you cannot
+  resolve it confidently, ask the user for the range and HALT.
+
+### Step 2: Gather signal (read-only)
+
+Gather from the sources above, without ever printing secret values. Scale effort to
+`depth`.
+
+**Always (both `light` and `full`):**
+- Changed files with status + churn: `git diff --stat <base>..<head>` and
+  `git diff --name-status <base>..<head>`.
+- Commit messages: `git log --no-merges --pretty='%h %s' <base>..<head>`.
+- Linked work items: Jira keys parsed from commit messages / branch names (e.g. `BD-\d+`).
+  **Revert-aware (critical):** a ticket only counts as *in the release* if its changes survive
+  in the **net** diff. When commits were reverted within the range (net ≠ history), verify
+  whether each ticket's files/content actually survive (e.g. a feature file added then deleted
+  is reverted). List reverted tickets **separately** as *reverted in-range (not shipped)* —
+  never imply reverted work is part of the release.
+- For non-secret files, inspect the diff **and the surrounding code / call sites** to judge
+  real blast radius. For deny-listed files, record filename + "changed (contents not
+  inspected)".
+
+**Additionally when `depth=full` (critical releases):**
+- **Jira:** read each linked ticket for intent / acceptance criteria / incident linkage.
+- **Cloud / outage status:** confirm the target project/region is healthy (GCP service
+  health + any ongoing SRE incidents). Note anything degraded.
+- **GCP Cloud Logging:** for each touched service, sample recent error/5xx signatures in a
+  bounded window (e.g. last 1–24h) for `gcp_project` — e.g.
+  `gcloud logging read '<filter> severity>=ERROR' --project <p> --freshness=24h --limit=50`.
+- **BigQuery:** where the change touches an event/analytics flow, run a bounded, aggregate
+  query (capped bytes, `--maximum_bytes_billed`) to sample real volume / error rate for the
+  affected path. Never `SELECT *` unbounded.
+- Record every source actually consulted (feeds the "Data sources consulted" report field).
+- If cloud access is unavailable or `gcp_project` is missing, note it as a gap and continue
+  with git+code+Jira signal only (do not fabricate cloud findings).
+
+### Step 3: Classify into impact areas (internal analysis)
+
+Bucket every change into the areas below. This classification is **internal** — it drives
+the report's `Found issues`, `Cross-service blast radius`, and the Overview `What changed`
+summary. Do **not** emit a standalone per-area "What changed" section (the report no longer
+uses one). For each touched area capture the concrete files/commits and a one-line "so what";
+note clean areas so their absence can be reflected in the risk assessment.
+
+- **API / contract changes** — swagger/openapi specs, route handlers, request/response
+  shapes. Flag anything **breaking** for consumers.
+- **Database / migrations** — schema changes, migration scripts, index changes,
+  destructive operations.
+- **Auth & security-sensitive** — `auth/`, `security/`, token/session logic, permissions,
+  crypto, dependency CVE-relevant bumps. Any change here raises the risk rating.
+- **Infrastructure** — terraform, Dockerfiles, CI/CD pipelines, service definitions.
+- **Config / environment** — per-region config (**AU / EU / US incl. DR**), feature flags,
+  env keys added/removed. Note if a change lands in some regions but not others.
+- **Dependencies** — `package.json` / lockfiles and other manifests; separate security
+  bumps from feature bumps; note major-version jumps.
+- **Cross-service blast radius** — shared patterns/libraries or contracts that other OOF
+  services depend on (a change here can affect repos outside this diff).
+- **Client backwards-compatibility** — impact on Android / native / web clients consuming
+  the changed contracts.
+- **Observability / operational** — logging, metrics, alerts, rollback affordances.
+- **Deployment & rollback effects (second-order)** — reason beyond *what code changed* to
+  *what the deploy does*: artifact/checksum changes that force a **new revision** even with no
+  logic change; provider/toolchain upgrades (e.g. Terraform / `google` provider pins) that can
+  cause **state or computed-field drift** → require a `terraform plan` review **per environment
+  incl. DR**; CI rules that don't match the release config (e.g. `hotfix/*` allowed in CI but not
+  in `.releaserc`) that can tag a build semantic-release later refuses to release; and whether
+  the change also gates the **rollback path** (e.g. an auth / Workload Identity migration that
+  affects deploy *and* rollback). These are the subtle, high-impact issues a raw diff misses —
+  always assess them on `full` / critical runs.
+
+### Step 4: Risk rating
+
+Assign an overall risk rating with a one-paragraph justification:
+
+- **Low** — isolated, non-breaking, well-tested, easy rollback.
+- **Medium** — touches a shared/contract surface OR config across regions OR notable deps.
+- **High** — breaking API, auth/security, DB migration (esp. destructive), or infra with
+  no clean rollback.
+
+Bias upward when auth/security, migrations, or cross-service contracts are involved, when
+you had to inspect deny-listed files by name only, or when **live signal is adverse** —
+e.g. an active outage / degraded dependency in the target region, or an elevated error rate
+in Cloud Logging for a service this release touches.
+
+**Critical releases (CDT-parity uplift):** tag **each Top risk with its own severity**
+(High / Med / Low), consolidate the concrete pre-production validations into a **Required
+before production** gate, and finish with an explicit **go/no-go recommendation** ("promote
+only after X, Y, Z pass"). Populate the **Engineer detail** appendix in full — exact
+versions/pins, **every** affected environment (incl. DR), and per-item failure mode +
+required validation. This mirrors the manual CDT analysis's audit-grade evidence trail and
+clear release gate.
+
+### Step 4b: Synthesise the findings
+
+From the classification + risk, distil a short **Found issues** list for the top of the
+report — **only realistic, critical items**; omit perfect-world / low-tier concerns (e.g.
+dev-only paths with no production impact, pre-existing standing gaps, or future / in-flight
+fixes). Favour: risky or changed semantics, real deploy/rollout hazards, security-relevant
+changes, and cross-service latent bugs. Each issue = a **bold one-line title** + a 1–3
+sentence description. If there are genuinely none, say so explicitly rather than padding.
+
+### Step 4c: Record what you verified
+
+Keep a running list of what you **actually checked** while analysing (e.g. "confirmed
+app/API/test paths identical via `git diff --name-status`", "confirmed dependency pin",
+"ran `git diff --check` (clean)", "verified WAF rules are `preview=true`"). This feeds the
+**Validation performed** section and, together with **Unknowns**, gives an auditable
+evidence trail — what was, and was not, confirmed.
+
+### Step 5: Produce the report
+
+Output this structure in Markdown, in this order (the layout must match the published
+report). Every section is required **except** the ones marked *[OPTIONAL]*: *Operational
+context* (include only if significant), and *Required before production* + *Engineer detail*
+(**required for critical releases**; otherwise include only when `detail=engineer`, or the
+release is high-risk / infra-heavy).
+
+```
+# Impact Analysis of Release — <repo> `<base>` → `<head>` (<short change summary>)
+
+## Found issues
+
+1. **<issue title>.** <1–3 sentence description of the issue and why it matters.>
+2. **<issue title>.** <...>
+   <If genuinely none: "No notable issues found — see Overview.">
+
+## Overview
+- **What changed:** <concise 1–2 sentence summary of the change and its intent>
+- **Repo / range:** `<repo>` `<base>` (`<sha>`) → `<head>` (`<sha>`) — <N> commits
+- **Changed:** <N> files, +<X> / -<Y> — `<file>` (+n), `<file>` (+m)
+- **Linked tickets (in this release):** <tickets whose changes survive in the net diff | none referenced>
+- **Reverted in-range (not shipped):** <tickets whose commits were reverted within the range — omit this line entirely if none>
+- **Depth:** <light|full> · **Data sources consulted:** <git, code, jira, outage-status, gcp-logs, bigquery> · **Not consulted:** <sources skipped / unavailable>
+- **Overall risk:** **<LOW|MEDIUM|HIGH>** — <one-line reason>
+
+## Cross-service blast radius
+<shared patterns/contracts other OOF services depend on that this change (or the bug it
+fixes) also affects; "None identified" if isolated>
+
+## Operational context   [OPTIONAL — include ONLY if there is something significant to report]
+<Include this section only when live signal is material — e.g. an active outage, a degraded
+dependency, or a notable error/volume pattern in Cloud Logging / BigQuery for a touched
+service. If nothing significant (or live queries were not run), OMIT this section entirely
+and record the "not queried" fact under Unknowns instead.>
+
+## Risk assessment
+**<LOW|MEDIUM|HIGH>.** <justification paragraph; note if live signal changed the rating.>
+
+### Top risks
+<only material, realistic risks — omit perfect-world / low-tier concerns; for critical
+releases tag each with a severity — **High / Med / Low**>
+1. **<High|Med|Low>** — <...>
+2. **<High|Med|Low>** — <...>
+
+## Suggested QA focus
+<solely the QA / functional areas a non-coder QA reviewer should confirm — assume engineers
+have already completed their technical and infrastructure checks. Concise, plain-language, no
+code or jargon. For a purely infra change with no user-facing effect, state what to confirm
+still works after go-live.>
+
+## Validation performed
+<short bullet list of what this analysis ACTUALLY checked / verified — the evidence behind the
+conclusions above. E.g. "confirmed app/API/test paths identical", "confirmed dependency pin",
+"ran git diff --check (clean)", "verified WAF rules are preview=true". Pairs with Unknowns.>
+
+## Unknowns / could not determine from available signal
+<explicit list — never leave this empty by guessing; include any source that was
+unavailable, e.g. "no GCP access — live cloud rates not checked">
+
+## Required before production   [REQUIRED for critical releases; else OPTIONAL — include when detail=engineer or high-risk / infra-heavy]
+<concrete boxes the release owner must tick before go-live — each naming the *validation*, not
+just the risk; cover auth/deploy, `terraform plan` per env incl. DR, artifact/revision
+expectations, CI vs `.releaserc` alignment, and that the **rollback path** still works under any
+changed auth>
+- [ ] <check 1 — e.g. production Workload Identity auth validated for all prod + DR projects>
+- [ ] <check 2 — e.g. `terraform plan` reviewed per env; no unexpected replace / delete / IAM change>
+
+**Recommendation:** **<GO | NO-GO / HOLD>** — <promote only after the named validations pass; one-line rationale.>
+
+## Engineer detail   [REQUIRED for critical releases; else OPTIONAL — include only when detail=engineer]
+<the exhaustive, engineer-grade specifics the summary above intentionally omits — **exact
+versions / pins**, **every** affected environment (incl. DR), per-item failure mode + required
+validation, and the deployment/rollback second-order effects (artifact/revision changes,
+provider state drift, CI-vs-`.releaserc` mismatch, rollback-path auth). Kept at the bottom so
+the summary stays readable for non-technical readers.>
+
+---
+*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.*
+```
+
+### Step 6: Publish (only if `publish=confluence`)
+
+- Publish the report as a **child page** of the **Impact Analysis** folder page in the
+  **OOF Skills** folder: Confluence space **`BNM1`**, parent page id **`5915476067`**
+  (`https://rezolvetech.atlassian.net/wiki/spaces/BNM1/folder/5912657922/OOF+Skills` →
+  *Impact Analysis*). Use markdown format, page emoji 🚦. Page **title**:
+  `Release Impact Analysis — <repo> <base> → <head> (<summary>)`. The page **body** begins
+  with the `# Impact Analysis of Release — …` heading from the template above.
+- Add the Confluence page link back to the release Jira ticket.
+- Never publish if any guardrail check failed.