mapping-suite

What this skill does

# Mapping Suite

## Overview

You have a small library of skills that map, audit, and document a system from different angles — `architectural-analysis`, `release-analysis`, `wiring-audit`, `doc-claim-validator`, `doc-completeness-audit`, etc. They share conventions (`docs/<skill>/<date>/`, mermaid + cited reports, cross-skill callout reuse, `--style corporate` HTML output) and they share a common prior: a recent `architectural-analysis` run is the foundational artifact most of the others can build on.

Coordinating them by hand means resolving the same scope four times, threading the same prior through four different Phase 0 lookups, and ending up with four standalone HTMLs to share. This skill owns the coordination so you don't.

The skill is a **coach, not an autorunner**. At each step it presents:

1. The next sibling skill in the recipe.
2. The scope it should inherit (resolved once at suite start).
3. The recommended invocation.
4. An approval gate.

You invoke the sibling. The orchestrator records what landed and proposes the next step.

## When to use

Trigger this skill when:

- You want a complete onboarding artifact for a system you don't already know — release-engineer onboarding, on-call rotation prep, knowledge transfer.
- You name two or more sibling skills to run together — "do an arch-analysis and a release-analysis on this repo."
- You want the combined HTML at the end — one navigable artifact spanning multiple sibling outputs.
- You're staring at a fresh codebase and want a recommended sequence of skills to run.

Do not trigger when:

- You only need one sibling skill — invoke it directly.
- You want autonomous execution — this skill always pauses at approval gates. If you want a hands-off run, run each sibling individually with explicit prompts.
- You're already mid-flight in another orchestration — don't nest mapping-suite inside itself.

## Recipes

A recipe is a named sequence of sibling-skill invocations with recommended scope inheritance. v1 ships two; both are release-engineer-onboarding flavored.

### Recipe 1: release-driver onboarding

**For:** tooling that drives releases for other systems (PowerShell fleet orchestrators, deploy-bot scripts, release-cutting CLIs). The unit of analysis is the *operations* the tool performs, not the tool itself.

**Reader:** a release engineer onboarding to a tool they'll be running.

**Plan:** see `references/recipes/release-driver-onboarding.md`. Summary:

1. **release-analysis** with `scope_shape: driver-only` (or `driver+kube` if the tool also ships itself). Skip arch-analysis prior — the tool isn't a deployed system, so an arch-analysis on it would mostly produce noise.
2. **doc-claim-validator** against the runbooks under `docs/runbooks/`, scoped narrowly. Catches drifted procedures the release-analysis Phase 5b reconciliation flagged but didn't resolve.
3. **Combined HTML** linking both outputs. The release-analysis report is the primary; doc-claim-validator's output is the appendix.

### Recipe 2: deployed-system onboarding

**For:** systems that get deployed (single repo or multi-repo union). The unit of analysis is the system itself.

**Reader:** any new engineer onboarding — release-engineer-flavored but applicable to anyone who needs to read the system end-to-end.

**Plan:** see `references/recipes/deployed-system-onboarding.md`. Summary:

1. **architectural-analysis** with full mode set (or scope-driven subset if the user specifies). Foundational.
2. **release-analysis** layered on the arch-analysis output. Phase 0 inherits scope automatically from the prior README's frontmatter.
3. **wiring-audit** (optional) — runs against the same scope, opportunistically consumes the arch-analysis's UI-surfaces and integrations findings as priors.
4. **Combined HTML** linking all sibling outputs. Architecture-analysis is the primary read; release-analysis is the secondary; wiring-audit (if run) is the appendix.

### Custom plans

The user can name a sequence directly: *"run release-analysis, then doc-completeness-audit, then combined HTML."* The orchestrator treats this as a one-off recipe — same coaching loop, same manifest, same combined-HTML output. No need to formalize it as a stored recipe.

## Workflow

Six phases. Phases 0 and 5 are unique to this skill; phases 1–4 are the coaching loop.

| Phase | Name | Purpose |
|---|---|---|
| 0 | Resolve scope and prior arch-analysis | Same three-tier resolution release-analysis uses. Result is shared with every sibling. |
| 1 | Choose recipe | Named recipe (release-driver onboarding, deployed-system onboarding) or user-defined sequence. |
| 2 | Generate run plan | Sequence of sibling-skill invocations with inherited scope and recommended args. |
| 3 | Coach through the plan | For each step: present, wait for user to invoke, capture output path, update manifest, propose next. |
| 4 | Combine | Run `scripts/compile-combined.sh` against the manifest to produce one navigation HTML. |
| 5 | Hand-off | Recommend next steps based on what each sibling surfaced (e.g., "doc-claim-validator flagged 3 drifted runbooks — want to invoke doc-maintenance?"). |

### 0. Resolve scope and prior arch-analysis (one-time)

Same three-tier resolution as `release-analysis`'s Phase 0:

1. **User-supplied path** (preferred) — *"run mapping-suite for `~/source/source-control-automation` building on `~/source/docs/architecture/2026-05-16/`."* Skip search.
2. **Search well-known locations** — `<cwd>/docs/architecture/*/` and `<cwd>/../docs/architecture/*/`.
3. **Ask** — when both miss.

Parse the prior README's frontmatter:

- `scope`, `target_repo`, `modes`, `date`.

Propose the inherited scope to the user. Confirm before proceeding.

If no prior arch-analysis exists *and* the recipe needs one (deployed-system onboarding does; release-driver onboarding doesn't), this is the first decision point: run arch-analysis first, or proceed without prior context. Ask.

Persist the result to `docs/<suite-date>-suite/suite-scope.md`:

```markdown
---
suite_date: 2026-05-18
recipe: release-driver-onboarding
scope: source-control-automation
target_repo: ~/source/source-control-automation
prior_arch_analysis: none (recipe doesn't require one)
eve_mcp_used: true
---
```

### 1. Choose recipe

Present the recipes:

```
Two recipes are available. Which fits this run?

1. release-driver onboarding — for tooling that drives releases for other systems
2. deployed-system onboarding — for systems that get deployed

Or describe a custom sequence.
```

If the user named a recipe in the trigger, skip the prompt and confirm: *"Running release-driver onboarding. Plan: release-analysis + doc-claim-validator + combined HTML. Sound right?"*

### 2. Generate run plan

Read `references/recipes/<recipe>.md` for the recipe-specific plan. The plan is a list of steps; each step has:

- Skill name.
- Scope (typically inherited from suite-scope.md).
- Recommended invocation prompt.
- Approval gate description.
- Expected output path (used to populate the manifest).

Write the plan to `docs/<suite-date>-suite/suite.yaml` per `references/suite-manifest.md`. Initialize all steps with `status: pending`.

### 3. Coach through the plan

For each step in order:

1. **Present.** Show the user:
   - Step number and skill name.
   - Why this step (one sentence).
   - The recommended invocation prompt (verbatim, as a code block they can copy).
   - What output to expect.
2. **Wait for user invocation.** The user runs the sibling skill themselves via `Skill` tool or by typing the prompt. The orchestrator does not auto-invoke.
3. **Capture output.** Once the sibling finishes, ask the user for the output path (or detect it via `find docs/<skill>/*/`). Validate the path resolves to a directory containing the expected artifacts (per the recipe's `expected output path`).
4. **Update manifest.** Mark the step `completed`, record the path. If the user skipped the step, mark `skipped` with a note.
5. **Propose next.** *"Step