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 release-analysis against ~/source/docs/architecture/2026-05-16/" > "build on the arch-analysis at ~/source/docs/architecture/" When a path is supplied, skip the search below and verify the README exists at the resolved location. If the supplied path doesn't resolve, surface the failure to the user — don't silently fall back to a search. **2. Search well-known locations.** When no path is supplied: ```bash # Inside the cwd (single-repo scope) ls -dt <cwd>/docs/architecture/*/ 2>/dev/null | head -1 # Parent directory (common for multi-repo unified scopes — e.g., ~/source/docs/ # holds the union analysis of ~/source/{mainwebcode,cosential-proxy,dev-stack}) ls -dt <cwd>/../docs/architecture/*/ 2>/dev/null | head -1 ``` If multiple candidates resolve (e.g., a per-repo run *and* a unified parent run), prefer the broader scope unless the user specifies otherwise — the broader run usually has more useful integrations and failure-mode coverage. Surface the choice to the user when ambiguity exists. **3. Ask the user.** When both checks miss: ask whether they have a prior arch-analysis path you should use, or whether to proceed without prior context. Never invent a location. #### Step 0b — Parse frontmatter and propose scope Read the README's frontmatter and the first ~30 lines (the Scope section). Extract: - `scope` — what was analyzed (e.g., `full (mainwebcode + cosential-proxy + dev-stack)`) - `target_repo` — the actual paths (e.g., `~/source/{mainwebcode,cosential-proxy,dev-stack}`) - `modes` — which arch-analysis modes ran - `date` — for staleness check - The "Scope" section's prose, which often names exclusions ("Gen3 SPA not analyzed," "test code excluded") that should carry forward Present to the user: > Found architectural analysis from `<date>` at `<path>`, covering `<scope>` (target: `<target_repo>`). Use the same scope for this release analysis? > > - **Yes** — inherit scope and ingest findings. > - **Override** — supply a different target. > - **Run fresh** — proceed without prior context (worse signal; note in Provenance). Default to "Yes" if the user provided no contradicting hint. Don't silently override. #### Step 0c — Decide ingest vs. fresh run Once scope is fixed: - **Prior found, ≤30 days old, scope matches:** ingest. Mine the prior report for release-relevant context: - `doc-map.md` (Phase 2 of arch-analysis) → topic→doc index of in-tree runbooks. **Reuse as the spine** for release-analysis's Phase 5b instead of re-discovering docs from scratch. Carry the `*(stale)*` markers forward. - `docs-inventory.txt` → raw list of docs found by arch-analysis. Use as starting point for Phase 1b. - `control-flow/report.md` → seeds promotion-path (startup ordering, `depends_on`, healthcheck gates). - `integrations/report.md` → seeds environment-matrix substrate (boundaries, external systems). - `failure-modes/report.md` → seeds recovery & rollback (cascade-blocking, restart policies, opt-in/opt-out flags). - The cross-mode callout index → carry forward verbatim; release-analysis findings reference these IDs by their original prefix. - **Sub-agent classifications** in arch-analysis findings: each ingested callout carries a `classification` (`confirms`, `drift`, `gap`, `extends`) and `doc_ref`/`doc_claim` fields. Release-analysis preserves these — a `gap` from arch-analysis stays a gap when referenced from release-analysis, and a `drift` carries forward as-is. - **Prior found, >30 days old:** ask the user. Either trust the older run (note staleness in Provenance) or fall through to the next branch. - **Prior not found, or user chose "Run fresh":** ask the user before triggering anything else. Do not silently re-run an 8-mode analysis. Offer: - **Focused arch-analysis run** of just the release-relevant subset (control-flow + failure-modes + integrations modes only) — 3 sub-agents instead of 8. - **Proceed without prior context** — release-analysis sub-agents re-derive with worse signal. Note in Provenance. #### Step 0d — Record the decision In `docs/release/<date>/README.md`'s **Provenance** section, capture: - The path of the prior README (or "none"). - The date and age of the prior run. - The inherited scope and target_repo (or the override the user supplied). - Which ingest path was taken. ### 1. Scope If Phase 0 inherited a scope from prior arch-analysis frontmatter, most of this is already decided — only the release-specific fields remain. If Phase 0 found nothing, scope from scratch. Establish: - **Target**: inherited from Phase 0 if a prior run was ingested, otherwise full repo / subtree / multi-repo union. For multi-repo systems (e.g., `~/source/{dev-stack,mainwebcode,cosential-proxy}`), the union is treated like a single scope. - **Modes**: which of the four (default: all) - **Output root**: `docs/release/<YYYY-MM-DD>/` — create now if missing. Place under the same parent as the prior arch-analysis run (so `~/source/docs/architecture/2026-05-16/` and `~/source/docs/release/2026-05-17/` are siblings). - **Shape detection** — see "Three release shapes" above for the framings: - **Compose-shaped indicators**: `compose*.yml`, `docker-compose.yml`, `up.sh`/`down.sh`, `.env` with image tags - **Kube-shaped indicators**: `kube/` or `aws/` directory with config subdirs (`*-dev-config`, `*-config`); markdown referencing `manifest`/`channel`/`namespace`; `.gitlab-ci.yml` jobs that publish images to a registry; presence of an Eve channel name in any markdown - **Driver-shaped indicators**: no Dockerfile / Compose / manifests for the target itself, but presence of a `data/<namespace>/`, `data/manifests.json`, `data/namespaces.json`, or similar describing *other* systems; `docs/runbooks/` directory naming fleet operations (cut, forward-merge, close-release, environment-roll); CLI entrypoints (`.ps1`, scripts/) that take channel/namespace/manifest names as arguments - Record what was detected and let it shape the mode prompts. A repo can hit one, two, or all three (a release-driver tool that also ships itself is hybrid). - **eve-mcp availability**: check whether the `eve-mcp` MCP server is configured. If yes, cloud-side verification (Phase 3) uses live queries on par with codanna/grep — read tools only (`Show*`, `Get*`). Action tools (`Deploy`, `Run*`, `Restart*`, `Set*Version`, `Unpin*`, `Patch*`, `Update*`) are release levers and are never invoked from this skill — they may be cited as mechanism in recovery-rollback findings but are not called. If eve-mcp is not configured, fall back to reading manifest YAML and config-directory markdown — note the fallback in the verification log. ### 1b. Docs inventory (reuse or build) Find authoritative in-tree release docs. Two paths depending on what Phase 0 ingested: **If a prior arch-analysis run was ingested**, it already produced `docs-inventory.txt` and (more usefully) `doc-map.md` — the topic→doc index that names which doc is authoritative on which subsystem. Reuse both: 1. Copy `<prior>/docs-inventory.txt` → `docs/release/<date>/docs-inventory.txt`. 2. Copy `<prior>/doc-map.md` → `docs/release/<date>/doc-map.md` (or symlink). This is the spine for Phase 5b. 3. Append release-specific finds the arch-analysis inventory may have missed: ```bash # Release-specific roots arch-analysis may not have walked find <target>/kube <target>/aws <target>/*/kube <target>/*/aws -maxdepth 4 -type f \ \( -name '*.md' -o -name 'README*' \) 2>/dev/null # Compose-shaped repos: top-level walkthroughs find <target> -maxdepth 2 -type f \ \( -name 'CHEATSHEET*' -o -name 'PR.md' -o -name 'up.sh' -o -name 'down.sh' \) 2>/dev/null # Eve manifest documentationUrl fields (cloud, optional — only when eve-mcp available) # eve-mcp:GetManifest:name=<each manifest> — capture documentationUrl from metadata ``` Add new finds to `docs-inventory.txt` (mark them with `# release-specific addition` comment). Update `doc-map.md` with rows for the new docs, classifying their topic and which release-analysis modes they overlap. **If no prior arch-analysis was ingested**, build the inventory from scratch: ```bash # Generic doc roots find <target>/docs <target>/*/docs -maxdepth 4 -type f \( -name '*.md' -o -name 'CHANGELOG*' \) 2>/dev/null # Top-level CLAUDE.md / README.md per repo find <target>/CLAUDE.md <target>/*/CLAUDE.md <target>/*/README.md 2>/dev/null # Release-specific roots find <target>/kube <target>/aws <target>/*/kube <target>/*/aws -maxdepth 4 -type f \ \( -name '*.md' -o -name 'README*' \) 2>/dev/null # Compose-shaped repos: top-level walkthroughs find <target> -maxdepth 2 -type f \