architecture-onboarding

What this skill does

# Architecture Onboarding Skill

## Purpose

This skill is the **entry point for new team members** joining a project that uses the solutions-architect-skills documentation suite. It reads the project's existing architecture docs and generates an interactive concept map — a canvas-based, draggable node-and-edge visualization — that helps users explore:

- The **5-phase lifecycle pipeline** (Readiness → Docs → Compliance → Review → Handoff)
- **Use cases** from the PO Spec / system overview, traced through sections and components
- The **13-section architecture structure** (S1-S13) with their file paths and dependency tiers
- **Architecture types** (META, 3-Tier, Microservices, N-Layer, BIAN) with the detected type highlighted
- **Components** from the component index with their types and connections
- **Compliance contract slots** (10 contracts) with scores if available
- **Architecture principles** (9 required) with presence indicators
- **Available skills** (9 skills) and when to invoke each
- **Architecture Decision Records** if `adr/` exists

Users can cycle knowledge levels per node (Know / Fuzzy / Unknown) and copy a targeted learning prompt pre-shaped by their knowledge gaps.

**Distinct from `architecture-peer-review`** (which reviews quality) and **`architecture-compliance-review`** (which analyzes contract health) — this skill is for exploration and learning, not evaluation.

---

## When to Invoke This Skill

- User is new to the project and wants an overview of the architecture
- User asks for an "architecture overview", "architecture tour", "architecture map", or "concept map"
- User asks "what is this architecture?", "how does this architecture work?", or "where do I start?"
- User asks for an "onboarding" experience or "explore the architecture"
- User uses `/skill architecture-onboarding`

**Do NOT invoke for:**
- Creating or editing ARCHITECTURE.md → use `architecture-docs` skill
- Generating compliance contracts → use `architecture-compliance` skill
- Peer review of architecture quality → use `architecture-peer-review` skill
- Compliance gap analysis → use `architecture-compliance-review` skill
- Generating component handoffs → use `architecture-dev-handoff` skill

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — entry point and workflow |
| `PLAYGROUND_TEMPLATE.md` | Concept map playground template for the interactive HTML explorer |

---

## Workflow

### Step 1 — Locate ARCHITECTURE.md (Required)

Search for `ARCHITECTURE.md` at the project root (and one level up if running from a subdirectory). If not found, **abort** with:

> *"No ARCHITECTURE.md found. Use `/skill architecture-docs` to create one first, then run onboarding."*

Detect structure type:
- **Multi-file**: `ARCHITECTURE.md` is a navigation index + `docs/` directory with section files
- **Monolithic**: Single `ARCHITECTURE.md` contains all content

---

### Step 2 — Extract Architecture Metadata

From `ARCHITECTURE.md`:
- **Project name**: From the first H1 heading or the "Project" field in Document Control
- **Architecture type**: Search for `<!-- ARCHITECTURE_TYPE: XXX -->` comment. If not found, infer from content (look for "META", "BIAN", "Microservices", "3-Tier", "N-Layer" keywords). Default to `"unknown"`.
- **Structure type**: Whether `docs/` directory exists with numbered files

---

### Step 3 — Read Section Presence

Glob for `docs/NN-*.md` files. Map each found file to its S-number using this fixed table:

| File | S-number | Tier |
|------|----------|------|
| `docs/01-system-overview.md` | S1+S2 | 0 (Foundation) |
| `docs/02-architecture-principles.md` | S3 | 0 (Foundation) |
| `docs/03-architecture-layers.md` | S4 | 1 |
| `docs/04-data-flow-patterns.md` | S6 | 3 |
| `docs/05-integration-points.md` | S7 | 3 |
| `docs/06-technology-stack.md` | S8 | 3 |
| `docs/07-security-architecture.md` | S9 | 4 |
| `docs/08-scalability-and-performance.md` | S10 | 4 |
| `docs/09-operational-considerations.md` | S11 | 5 |
| `docs/components/` (directory) | S5 | 2 |
| `adr/` (directory) | S12 | 0 (Foundation) |

For monolithic docs: use heading patterns to infer which sections are present.

**Design drivers** (if S1 present): Search `docs/01-system-overview.md` for `### Design Drivers` heading. Extract Value Delivery, Scale, and Impacts levels — include in S1+S2 node detail.

---

### Step 4 — Read Optional Data

All items in this step are **optional** — the skill works with just `ARCHITECTURE.md`.

**Components** (`docs/components/README.md`):
- If exists: parse the 4-column index table (`#`, `Component`, `File`, `Type`)
- Limit to first 15 components to avoid node overload on large projects
- Status: `"present"` if file exists, `"not-created"` otherwise

**Handoffs** (`handoffs/` directory):
- If exists: scan each handoff file's "Business Context" field for UC references
- Used to build use case → component `served-by` edges

**PO Spec** (`PRODUCT_OWNER_SPEC.md`):
- Check if file exists; used as fallback source for use case extraction if S2 lacks them

**Use Cases** (extracted from two sources in priority order):
1. **Primary source** — `docs/01-system-overview.md` Section 2.3 "Primary Use Cases": Parse use case headings (`### Use Case N: <Name>`) and extract: name, description (first line after heading), actors, and success metrics.
2. **Fallback source** — `PRODUCT_OWNER_SPEC.md` Section 4 "Use Cases": Parse `### Use Case N: <Name>` headings with description, actors, primary flow steps, and success metrics.
3. If neither source has use cases, skip — no use case nodes are created.
- Limit to 10 use cases maximum.

**Use Case → Component mapping** (from handoff docs):
- If `handoffs/` exists: scan each handoff file for the "Business Context" field (typically line ~30). Extract use case references (e.g., "UC 1", "UC 2", "Use Case 1") and map them to component IDs.
- If handoffs don't exist: infer mapping from component descriptions and use case names (best-effort keyword matching).

---

### Step 5 — Build Nodes and Edges

Assemble `onboardingData` JSON following the schema in `PLAYGROUND_TEMPLATE.md`.

**Node construction rules:**
- Create one node per **use case** extracted in Step 4 (id: `uc-N`, group: `usecases`). Include description, actors, and success metrics in the detail field.
- Create one node per S-number (id: `s1-s2`, `s3` … `s12`, group: `sections`). Present nodes fully opaque; missing nodes as ghost nodes with `status: "missing"`.
- Create one node per component (id: `comp-<slug>`, group: `components`, up to 15).
- Default all `knowledge` fields to `"fuzzy"`

**Edge construction rules:**

Section tier dependencies (always present):
- S4 → S1+S2 (depends-on), S4 → S3 (depends-on)
- S5 → S1+S2 (depends-on), S5 → S4 (depends-on)
- S6 → S5, S7 → S5, S8 → S5 (depends-on)
- S9 → S5, S9 → S7, S9 → S8 (depends-on)
- S10 → S5, S10 → S8 (depends-on)
- S11 → S5, S11 → S8, S11 → S10 (depends-on)

Use case → section edges (traces-to):
- Every use case traces to S1+S2 (where use cases are technically defined)
- Use case → S6 (data flow) if the use case involves async flows or event processing
- Use case → S7 (integration) if the use case involves external systems

Use case → component edges (served-by) — extracted from handoff docs:
- Each component's "Business Context" field lists which use cases it serves
- Create `{ from: "uc-N", to: "comp-<slug>", type: "served-by" }` for each mapping

Component → S5 edges (implements) — one per component from component index

---

### Step 6 — Invoke Playground

Invoke the `playground` skill using `PLAYGROUND_TEMPLATE.md` as the template. Pass the assembled `onboardingData` as the data to embed.

Output filename: `architecture-onboarding-<YYYY-MM-DD>.html` (use today's date)

After writing the file, run: `open architecture-onboarding-<YYYY-MM-DD>.html`

---

### Step 7 — Fallback (No Playground Plugin)

If the `playground` plugin is not installed, output a structured plain-text repor