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/.

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:

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.

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:

# 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:

# 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:

# 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 \
    \( -name 'CHEATSHEET*' -o -name 'PR.md' -o -name 'up.sh' -o -name 'down.sh' \) 2>/dev/null

Persist the list to docs/release/<date>/docs-inventory.txt. Do not read the files yet — Phase 5b reads them.

If the target has no docs/, no kube/*-config/, and no top-level markdown beyond README.md + CLAUDE.md, skip Phase 5b and note the absence in the synthesis README.

2. Dispatch sub-agents (parallel)

Read references/subagent-dispatch.md for the agent type / model matrix and prompt templates. One sub-agent per mode, dispatched in a single message with multiple Agent tool calls (parallel), one-shot — never with team_name.

Each sub-agent receives:

• The scope from phase 1
• The detected shape (local-only, cloud-only, both)
• Any ingested findings from phase 0 — sub-agents reference these IDs rather than re-discovering the underlying facts
• The structured output contract from references/subagent-dispatch.md

Sub-agents return candidate findings. Findings are not yet committed to a diagram.

3. Verify (orchestrator)

Read references/verification-protocol.md. The orchestrator runs the mechanical verification pass:

• Resolve every cited symbol or file (codanna preferred, grep fallback).
• Read each cited line and confirm content matches the evidence string.
• For absence claims — grep for the asserted-missing symbol; discard if present.
• For cloud-side topology claims — use eve-mcp queries (ShowChannels, GetManifest, ShowDeploymentCrons, GetDeploymentCron) to confirm. Treat eve-mcp results as a verification source on par with codanna.
• For configuration provenance claims — confirm the override order by reading the actual resolution mechanism (compose merge order, manifest metadata resolution), not by inferring from filename order.
• For synthesized concepts — confirm justification names ≥2 contributing files; cap synthesized share at 20% per mode (see references/citation-protocol.md).

Maintain a discard log for each report's verification log section.

4. Render

For each verified mode:

• Author <mode>/<diagram>.mmd per references/mermaid-conventions.md
• Render to SVG: bash scripts/render.sh docs/release/<date>/ --style corporate (produces <base>-corporate-light.svg and <base>-corporate-dark.svg; render --style blueprint too if you want all four combos available)
• Author <mode>/report.md per references/report-template.md

5. Synthesize

• Author top-level docs/release/<date>/README.md per references/synthesis-readme.md — Provenance section (what was ingested from arch-analysis), cross-mode callout index, headline release findings, verification summary.

5b. Docs reconciliation (read the in-tree docs now)

Before finalizing the synthesis README, reconcile findings with the docs listed in Phase 1b. Read references/docs-reconciliation.md for the full protocol. Summary:

1. Read each in-tree doc once (orchestrator, not delegated). Group by topic.
2. For each doc, decide overlap with each mode. A runbook for promoting a service overlaps promotion-path; a recovery procedure doc overlaps recovery-rollback; a config-overrides cheatsheet overlaps configuration-provenance.
3. For overlapping docs, run doc-claim-validator via the Skill tool. Pass the doc and the relevant mode reports as input. Capture (a) confirmed claims, (b) contradicted claims (where verified findings disagree), (c) claims the validator couldn't reach.
4. Apply the release-specific reconciliation rule (per references/docs-reconciliation.md): when reconciling against a runbook for promotion or recovery, the runbook's procedure (the ordered steps) is almost always authoritative — even if the report's mechanism citations are correct. A runbook saying "to roll back, first pause the cron, then unpin" supersedes a report saying "rollback uses SetManifestVersion(prior)" because the report is missing the cron-pause prerequisite. Promote the runbook; defer.
5. Author docs/release/<date>/docs-reconciliation.md — table mapping each in-tree doc to the modes it overlaps, with status per doc:
   • In-tree doc supersedes — the doc has more correctness or procedural detail. Reference it from the relevant mode report's narrative.
   • Report supersedes — the report's verified finding contradicts the doc; the doc is stale. Flag for the team.
   • Complementary — covers different surface; cite both.
   • Adds capability/view — fills a gap the report missed entirely (prod runbook, on-call recovery, deployment checklist).
   • Drift — both are partially right; surface the contradiction explicitly.
6. Update the synthesis README with an "Authoritative in-tree docs" section per references/synthesis-readme.md. Lead with this section so readers go to the canonical doc first.
7. Update individual mode reports to cite in-tree docs where they supersede the report's coverage. One sentence each in the relevant mode's Summary or Narrative.

This phase is the institutional fix for the failure mode where the analysis duplicates or contradicts existing team runbooks. For release analysis specifically, the cost of skipping is high — runbooks encode hard-won procedural knowledge that report-style mechanism citations don't capture.

6. Hand-off

The release analysis is descriptive. If the user wants to act on it:

• Stale runbooks surfaced in Phase 5b → invoke doc-claim-validator directly to triage the full set, or hand the drift findings to the doc owners.
• Configuration drift between environments surfaced in configuration-provenance → invoke wiring-audit (configuration drift is a wiring concern when the UI or CLI for changing the value is also drifted).
• Recovery procedures with no documentation → recommend the team author runbooks for the gap states surfaced in recovery-rollback.
• Stale ingested arch-analysis → recommend re-running architectural-analysis if Phase 6 callout-resolution found significant decay.

Do not auto-invoke. Recommend, let the user choose.

Shareable artifacts

HTML — produced automatically. Two-step pipeline at end of Phase 5/5b, mirrors arch-analysis:

bash scripts/render.sh docs/release/<date>/ --style corporate
bash scripts/compile-html.sh docs/release/<date>/

Defaults:

• Style: corporate — Stripe/Linear-style modern SaaS doc (Inter font, generous whitespace, soft shadows, deep-blue accent).
• Theme: light — initial theme baked at compile time; users toggle at runtime via the top-right button.

Available styles: corporate (default), blueprint (engineering/violet aesthetic). Both ship with light + dark themes; the runtime toggle just swaps data-theme on <html> and the paired SVG variants render appropriately.

Flags (passed to compile-html.sh):

• --style {corporate|blueprint} — must match what render.sh produced.
• --theme {light|dark} — initial theme. Default light.
• --banner <path> — header banner image, resolved relative to --repo-root (default cwd).
• --out <path> — output HTML path. Default <report-dir>/<dirname>.html.

Important: render.sh --style <X> produces <base>-<X>-light.svg and <base>-<X>-dark.svg. compile-html.sh --style <X> looks for those exact filenames. Render both styles upfront if you want all four combos available simultaneously.

PDF — only on request. Run bash scripts/compile-pdf.sh docs/release/<date>/ only when the user explicitly asks for a PDF. Defaults to landscape; pass --portrait to override. PDF consumes the style-agnostic .png files (no light/dark there).

Combined report (optional). When the user wants one artifact spanning multiple sibling analyses (architectural + release + wiring-audit, etc.), use the combined compile flow described under "Combined sibling reports" below.

Combined sibling reports

Release-analysis is a sibling artifact to other diagram-first analyses that build on the same prior arch-analysis (wiring-audit, future security-audit, etc.). Convention:

• Each analysis writes its own dated subdirectory: docs/architecture/<date>/, docs/release/<date>/, docs/wiring-audit/<date>/, etc. — all under the same parent.
• Each analysis emits its own self-contained HTML by default. Sibling artifacts stay immutable; nothing rewrites a completed arch-analysis run.
• When the user wants a single combined report, run the combined compile (one level up):

bash <skill-with-combined>/scripts/compile-combined.sh <parent-docs-dir>/ \
    --include architecture/<date> \
    --include release/<date> \
    --include wiring-audit/<date> \
    --banner <path>
# → <parent-docs-dir>/combined-<YYYY-MM-DD>.html

The combined script concatenates the included analyses' README + per-mode reports, resolves cross-skill callout references in-document, and embeds all SVGs. Cross-skill references (e.g., a release-analysis [R-5] referencing arch-analysis [C-17]) become anchor links rather than text-only IDs.

The combined compile script is not yet implemented in this skill — it's a planned addition. Until it lands, share each sibling's HTML separately and let the cross-skill ID conventions do the linking work.

Output layout

docs/release/2026-05-16/
├── README.md                          # synthesis + provenance + cross-mode callout index
│                                      # — leads with "Authoritative in-tree docs" section
├── docs-inventory.txt                 # Phase 1b: list of in-tree release docs (reused or built)
├── doc-map.md                         # Phase 1b: topic→doc index (reused from arch-analysis,
│                                      #   or built fresh; spine for Phase 5b)
├── docs-reconciliation.md             # Phase 5b: per-doc overlap + status table
├── promotion-path/
│   ├── promotion.mmd
│   ├── promotion-corporate-light.svg
│   ├── promotion-corporate-dark.svg
│   └── report.md
├── environment-matrix/{matrix.mmd, *.svg, report.md}
├── configuration-provenance/{provenance.mmd, *.svg, report.md}
├── recovery-rollback/{recovery.mmd, *.svg, report.md}
├── 2026-05-16.html                    # automatic, compile-html.sh
└── 2026-05-16.pdf                     # opt-in only, compile-pdf.sh

Strict citation policy

Read references/citation-protocol.md before authoring any diagram. Summary:

• Every node carries a callout ID and either a path:line citation or an eve-mcp:<tool>:<query> citation.
• Every edge carries a citation.
• Synthesized concepts are visually distinct in the diagram (classDef synthesized stroke-dasharray:5) and listed separately in the report. Cap: ≤20% per mode.
• Every report carries a verification log of what was discarded and why.
• Release-specific rule: configuration override-order claims must be confirmed by reading the resolution mechanism, not inferred from filename ordering. Release-specific rule: cloud topology claims preferentially cite eve-mcp queries when available.

Fabricated citations are the dominant failure mode for diagram-first analysis. The verification phase is the load-bearing part of this skill — do not skip it.

Resources

• references/citation-protocol.md — strict citation rules, eve-mcp citation format, synthesized cap
• references/verification-protocol.md — orchestrator's mechanical verification pass with eve-mcp hooks
• references/subagent-dispatch.md — agent/model matrix, prompt templates, ingested-findings handoff
• references/mermaid-conventions.md — diagram types, callout prefixes, classDef rules
• references/report-template.md — per-mode report.md skeleton
• references/synthesis-readme.md — top-level README.md template (incl. Authoritative in-tree docs and Provenance sections)
• references/docs-reconciliation.md — Phase 5b protocol: reading in-tree runbooks, dispatching doc-claim-validator, release-specific procedure-precedence rule
• references/mode-promotion-path.md
• references/mode-environment-matrix.md
• references/mode-configuration-provenance.md
• references/mode-recovery-rollback.md
• scripts/render.sh — render *.mmd to *.svg via mmdc
• scripts/compile-html.sh — combine reports into a single self-contained styled HTML via pandoc
• scripts/compile-pdf.sh — combine reports into a single PDF via pandoc
• scripts/verify-citations.sh — quick path:line existence check over a report
• assets/template.html — pandoc HTML template
• assets/styles/{corporate,blueprint}/ — stylesheet + mermaid theme JSONs (pass --style to compile-html.sh)