integration-analysis

What this skill does

# Integration Analysis

**Estimated Time:** 30-90 minutes (depending on system count, mode, and available inputs)
**Prerequisites:** At least one starting-point repo or config directory
**Output:** Analysis artifacts + dependency-ordered epics in `_integration-analysis/`

---

## Resume Check

Before starting, check for `.stackshift-state.json` with `integration-analysis.status = 'in_progress'`. If found, present:

```
A previous integration analysis was interrupted at Phase {N}.
Resume from Phase {N+1}? (Y/n)
```

If yes, load the saved system list and generated artifacts, skip completed phases. In YOLO mode, auto-resume from the interrupted phase.

---

## Three Modes

### YOLO (Fully Automatic)
~30-45 min. No user input after initial system list. Auto-extracts, auto-tiers, marks uncertain items with `[AUTO - review recommended]`.

### Guided (Recommended)
~45-60 min. Auto-extracts + 5-10 targeted questions about ambiguous boundaries, pain points, tier assignments, data ownership, and missing context.

### Interactive
~60-90 min. Full walkthrough with review and approval at each phase.

---

## Phase 0: KICKOFF

### 0.1 Mode Selection

```
How should I run the integration analysis?

A) YOLO -- Fully automatic, no questions after setup (~30-45 min)
B) Guided -- Auto-extract + 5-10 targeted questions (recommended) (~45-60 min)
C) Interactive -- Full walkthrough with review at each phase (~60-90 min)
```

Save selection to state.

### 0.2 Collect Starting Points

```
Give me one or more starting points and I'll figure out the ecosystem.
Anything helps -- repos, config dirs, system names, docs, context packs.
```

Accept any combination of: code paths, config directories, context pack paths, Discover output (`.stackshift/ecosystem-map.md`), system names, Reverse Engineer docs.

**When consuming Discover output,** expect `ecosystem-map.md` to contain a systems table with columns [Name, Confidence, Path, Signals] and a dependency section with system-to-system edges. If the format is unrecognizable, fall back to treating the file as a context document and extract system names manually.

### 0.3 Discover the Ecosystem

Trace actual API contracts, data flows, and consumer/provider relationships from starting points. Discovery works in two bands:

- **In-band:** Deep analysis of locally available codebases and docs (high confidence)
- **Off-band:** GitHub/GitLab searches for systems not found locally (lower confidence)

**Step 1: In-band -- Analyze integration surfaces in starting-point repos**

For each starting-point repo with local code access, use Task agents in parallel to extract:
- API clients and HTTP calls (reveals consumed systems)
- API contracts exposed (reveals consumers of this system)
- Service interfaces and SDKs (formalized dependencies)
- Config referencing external systems (env vars, endpoint URLs)
- Database and cache connections (shared data stores)
- Event/message contracts (async integration partners)
- Documented integration points (README, ADRs, docs/)
- Reverse Engineer docs if available (highest quality source)

**Step 2: In-band -- Locate discovered systems locally**

Search common development directories for newly discovered systems. Quote all paths in shell commands to handle spaces and special characters:

```bash
SEARCH_DIRS=(
  "$(dirname "$STARTING_REPO")"
  "$HOME/git"
  "$HOME/code"
  "$HOME/src"
  "$HOME/repos"
)
```

If found locally, repeat Step 1 on the new repo (recursive discovery). **MUST NOT exceed recursion depth of 2 hops** from user-provided starting points without user confirmation. In YOLO mode, stop at 2 hops and log: "Recursion depth limit reached. Proceeding with discovered systems."

**Step 3: In-band -- Analyze config data directories**

Parse config files (XML, YAML, JSON, properties) for service endpoints, data sources, feature flags, and override keys.

**Step 4: In-band -- Analyze context packs and existing docs**

Extract system names, API contracts, and data flow descriptions from context packs or reverse-engineering docs.

**Step 5: Off-band -- GitHub/GitLab search for unfound systems**

Search for repos matching discovered system names. Auto-clone for deeper analysis:
- **YOLO:** Auto-clone all discovered repos, re-run Step 1
- **Guided:** List repos and ask per-repo
- **Interactive:** Present each repo and ask before cloning

If cloning fails: (1) Mark the system as `[NO CODE ACCESS - clone failed: {error}]` in the state file. (2) Include the system in Phase 2 profiling using only consumer-side code references and off-band search results. (3) Mark the resulting profile as `[PARTIAL - no code access]`.

**Step 6: Build the ecosystem graph**

Merge all discovery results. Assign confidence per node:

| Level | Criteria |
|-------|----------|
| **CONFIRMED** | User-provided starting point, or user explicitly added |
| **HIGH** | In-band tracing from 2+ independent sources |
| **MEDIUM** | Single in-band source OR found locally after off-band hint |
| **LOW** | Off-band search only, no integration evidence |

### 0.4 Present Discovered Ecosystem

Present the ecosystem as a table of systems with confidence, local code, config, docs, and relationship columns. Include a Mermaid graph of integration edges.

In Guided/Interactive mode, offer: confirm, add systems, remove systems, add context, go deeper.

**In YOLO mode:** Auto-include CONFIRMED + HIGH, include MEDIUM with `[AUTO - review recommended]`, drop LOW. Skip confirmation.

### 0.5 Save State and Proceed

Save the confirmed system list to `.stackshift-state.json`. Update state at every subsequent phase boundary.

**Log:** "Phase 0 complete -- {N} systems confirmed, {M} integration edges discovered. Proceeding to Phase 1."

---

## Phase 1: INVENTORY

**Input:** System list from Phase 0
**Output:** `system-inventory.md`

1. Auto-detect metadata for systems with code access (tech stack, repo status, monorepo detection, description)
2. Import metadata from Discover output if available (confidence scores, dependency hints)
3. Enrich with user-provided notes from Phase 0
4. Classify system roles: Source of Truth, Consumer, Transformer, Orchestrator, Gateway
5. Generate `_integration-analysis/system-inventory.md`

In Guided/Interactive mode, present enriched inventory for confirmation.

**Log:** "Phase 1 complete -- system inventory generated for {N} systems. Proceeding to Phase 2."

Update state: `"phase": 1`.

---

## Phase 2: SYSTEM PROFILING

**Input:** Per-system code repos, config data, Reverse Engineer docs (optional)
**Output:** `system-profiles/{name}.md` (one per system)

Follow the detailed process in `operations/system-profiling.md`.

Use Task agents to profile multiple systems concurrently. For each system, extract: capabilities, API surface, data models, config structures, integration points, override/inheritance patterns, auth model, constraints, pain points.

**IMPORTANT:** If a Task agent fails or times out, mark that system's profile as `[FAILED - {reason}]` in the state file. Continue with available profiles. In Guided/Interactive mode, inform the user which profiles failed and offer to retry. In YOLO mode, proceed with available profiles and flag missing ones in all downstream artifacts.

**Before proceeding to Phase 3,** verify the quality checklist in `operations/system-profiling.md`. In YOLO mode, log any failures but proceed. In Guided/Interactive mode, inform the user.

**Log:** "Phase 2 complete -- {N}/{M} system profiles generated ({K} failed). Proceeding to Phase 3."

Update state: `"phase": 2`.

---

## Phase 3: CROSS-SYSTEM ANALYSIS

**Input:** All system profiles from Phase 2
**Output:** `capability-map.md`, `integration-contracts.md`, `data-architecture.md`

**IMPORTANT:** Run this phase in the main context. Do not delegate to subagents -- this phase requires synthesizing information from all profiles simultaneously.

Follow the detailed process in `operations/cross-system-mapping.md`. Generate three artifacts:
- `_inte