release-analysis

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:

"run