release-analysis

What this skill does

# Release Analysis

## Overview

Produce diagram-first release reports for a codebase that ships somewhere — locally via Docker Compose, to a Kubernetes cluster via Eve, or both. The primary artifact is a set of mermaid diagrams under `docs/release/<report-date>/<mode>/`, accompanied by markdown reports that resolve every callout to a `path:line` citation (or, for cloud-side topology claims, an `eve-mcp:<tool>:<query>` citation). Every node and every edge in every diagram is grounded in source or in a verifiable platform query — no exceptions outside the synthesized-concept escape hatch.

This skill is a **layer on top of** `architectural-analysis`. When that skill has already run against the same scope and the report is fresh (default: ≤30 days), release-analysis ingests its findings rather than re-deriving them. The seam is explicit and load-bearing — see Phase 0 below.

## When to use

Trigger this skill when the user asks for:

- A full release map of a system ("map how we deploy this," "diagram the release")
- A specific release-shaped question by name ("trace the promotion path to prod," "where does `WAF_ENABLED` come from in stage," "what's the rollback story for the migration job")
- An environment topology view ("show me which manifests run in which namespaces," "which compose profile has which services")

Do not trigger for:

- Architectural snapshots that don't focus on deployment ("diagram the data flow") → use `architectural-analysis`
- CI pipeline correctness or `.gitlab-ci.yml` review → use code review
- Designing a new release process from a blank page → use `system-design`
- Single-question lookups that don't justify diagrams ("what's the prod image tag?") → answer directly

## Modes

Four analysis modes. Each has its own callout prefix, primary mermaid diagram type, and dedicated reference file in `references/`.

| Mode | Prefix | Primary diagram | Reference |
|---|---|---|---|
| Promotion path | `R-` | `flowchart LR` (commit → build → image → manifest → running instance) | `references/mode-promotion-path.md` |
| Environment matrix | `E-` | `graph TD` (env × namespace × cluster) for cloud; profile × service matrix for local | `references/mode-environment-matrix.md` |
| Configuration provenance | `K-` | layered annotation graph (key → source → override order) | `references/mode-configuration-provenance.md` |
| Recovery & rollback | `V-` | `stateDiagram-v2` (healthy → degraded → recovering) plus procedure list | `references/mode-recovery-rollback.md` |

Callout IDs are stable across modes — `R-7` referenced from a recovery report points to the same physical node in the promotion-path diagram. The cross-mode index in the synthesis README binds them.

### Cross-skill callout reuse

Callouts ingested from a prior `architectural-analysis` run keep their original prefix (`I-`, `C-`, `F-`, `X-`, etc.) and are referenced by ID without reproduction. A release-analysis callout `R-7` may cite `[C-17]` from the prior arch-analysis report; the synthesis README links to the originating mode's report rather than copying the entry.

## Three release shapes

Most release-analysis targets are systems that *get* deployed — the unit of analysis is the system itself. But some targets are tooling that *drives* releases for other systems — the unit of analysis flips. The skill recognizes three shapes:

| Concern | Compose-shaped (local) | Kube-shaped (cloud) | Driver-shaped (orchestrator) |
|---|---|---|---|
| What the target is | a deployable system, run locally | a deployable system, run in Kube | tooling that performs release operations on other systems |
| Unit | service in `compose.*.yml` | application in a `manifest` | release operation (cut, forward-merge, close-release, environment-roll) |
| Group | profile / compose project | namespace | targeted fleet (the repos / namespaces this tool operates on) |
| Boundary | docker network | cluster + namespace | the set of repos / channels this tool manages |
| Promotion | image rebuild + `docker compose pull` + `up.sh` | channel-based version promotion via Eve | the multi-step pipeline this tool encodes (e.g., cut → forward-merge → close-release) |
| Pinning | image tag in `.env` or `compose.*.yml` | `SetManifestVersion` / `SetNamespaceVersion` | how the tool selects targets per run (`config.json`, `namespaces.json`, `manifests.json`, cron config) |
| Rollback | revert image tag, `docker compose up -d` | `UnpinManifestVersion` then re-promote prior version | the recovery procedures the tool itself implements (or the runbooks for when its operations fail mid-flight) |
| Config layering | compose merge order, `.env`, profile YAMLs | manifest metadata, env-specific overrides, secrets, ConfigMaps | how `config.json`, env vars, `.profile`, per-namespace data files resolve at runtime |

A repo can be one shape, multiple, or — in driver-shaped cases — all three at once if the tool also ships itself. Detection happens in Phase 0.

### Driver-shaped reframe

When the target is driver-shaped (PowerShell tooling that orchestrates fleet releases, deploy-bot scripts, release-cutting CLIs, etc.), each mode reframes:

- **Promotion path** — the multi-step pipeline this tool drives across the targeted fleet, not how the tool itself reaches a runtime. CI publishing of the tool itself is a footnote, not the main diagram.
- **Environment matrix** — the namespaces / clusters / repos the tool manages, sourced from its config files (`namespaces.json`, `manifests.json`, etc.). The tool's *own* runtime is incidental.
- **Configuration provenance** — how the tool's per-run inputs resolve (config files, env vars, profile overrides, cron parameters). Same provenance machinery, different keys.
- **Recovery & rollback** — runbooks the tool documents for partial-pipeline failures (close-release stuck, forward-merge gap, environment-roll mid-state). These are usually the spine of the report; runbook-precedence applies aggressively.

If the target has no Dockerfile, no Compose, no manifests, but does have a `data/` or `config/` directory describing other systems and a `docs/runbooks/` describing fleet operations, it's driver-shaped. Treat the runbooks as the spine and let mode prompts reflect the reframe.

## Workflow

Eight phases. Phases 0, 1b, 5b, and 6 are release-analysis-specific or mirror arch-analysis additions. Do not skip phases.

| Phase | Name | Purpose |
|---|---|---|
| 0 | Ingest prior arch-analysis | Pull in control-flow, integrations, failure-modes findings if a recent report exists |
| 1 | Scope | Establish target, modes, output root, shape detection (compose / kube / driver), eve-mcp availability |
| 1b | Docs inventory | Reuse arch-analysis's `doc-map.md` + `docs-inventory.txt` if ingested; otherwise build fresh. Seeds Phase 5b. |
| 2 | Dispatch sub-agents | Parallel enumeration per mode |
| 3 | Verify | Mechanical citation check (file + eve-mcp) |
| 4 | Render | Mermaid + per-mode reports |
| 5 | Synthesize | Top-level README with cross-mode index |
| 5b | Docs reconciliation | Read in-tree runbooks; reconcile against verified findings; runbooks usually win |
| 6 | Hand-off | Recommend follow-up skills (wiring-audit, doc-claim-validator, etc.) — do not auto-invoke |

### 0. Locate prior architectural analysis (and let it propose scope)

The canonical entry point. A prior arch-analysis run already decided what counts as "the system" — its frontmatter is the source of truth for scope and target_repo. Read it first; let it propose the scope; the user confirms or overrides.

#### Step 0a — Find the most recent prior README

Three resolution paths, in priority order. Stop at the first that resolves.

**1. User-supplied path (preferred when known).** The user can pass a path explicitly — either to a specific run's directory (`docs/architecture/2026-05-16/`) or to its README (`docs/architecture/2026-05-16/README.md`) or to the parent (`docs/architecture/`, in which case pick the latest dated subdirectory). Examples:

> "ru