reimagine

What this skill does

# Reimagine

Take reverse-engineering docs from multiple repos. Reimagine them as something better.

**Estimated Time:** 30-60 minutes (depending on repo count and depth)
**Prerequisites:** Batch processing completed on 2+ repos, OR manually prepared reverse-engineering docs from multiple repos
**Output:** Capability map, reimagined vision, new specifications (Spec Kit or BMAD format)

This skill assumes single-session execution. If interrupted, the capability map and vision documents written to disk serve as partial checkpoints. Resume from Step 4 using the saved `CAPABILITY_MAP.md`.

---

## When to Use This Skill

Activate when:
- The user has batch-processed multiple related repos with StackShift
- The user wants to consolidate or redesign multiple services/apps
- The user is planning a major platform modernization
- The user wants to explore how existing capabilities could work together differently
- The user has reverse-engineering docs from several codebases and wants a fresh perspective

**Trigger Phrases:**
- "Reimagine these services as a unified platform"
- "How could these apps work together better?"
- "Consolidate these microservices"
- "Design a new system from these existing capabilities"
- "Synthesize a new vision from multiple repos"

---

## Process

### Step 1: Locate Repo Documentation

Determine where the reverse-engineering docs live using one of three options.

**Option A: From Batch Results**

Run the following command (adapt paths as needed):
```bash
BATCH_DIR="${HOME}/git/stackshift-batch-results"
find "${BATCH_DIR}" -type d -name "reverse-engineering" -path "*/docs/*"
```

**Option B: Manual Repo List**

Ask the user to provide paths to repos or their reverse-engineering docs:
```
Which repos should I analyze?

Provide paths to repos or their docs/reverse-engineering/ directories:
1. ~/git/user-service
2. ~/git/billing-api
3. ~/git/notification-hub
4. ~/git/admin-dashboard
...
```

**Option C: From Active Directory**

If in a monorepo, scan for subdirectories with reverse-engineering docs (adapt paths as needed):
```bash
for dir in "${PWD}"/*/; do
  if [ -d "${dir}docs/reverse-engineering" ]; then
    echo "Found: ${dir}"
  fi
done
```

**Validate each discovered repo.** Each repo must have at minimum:
- `functional-specification.md` (required)
- `integration-points.md` (required)
- `data-architecture.md` (required)
- Additional docs improve analysis quality but are not required

**Error handling for Step 1:**
1. Use Glob to list all files in each repo's `docs/reverse-engineering/` directory.
2. For each repo, check whether all 3 required documents exist.
3. If a repo is missing any required document: inform the user which docs are missing from which repo and ask whether to (a) proceed with available docs, (b) skip that repo, or (c) abort entirely.
4. If Option A or C finds zero repos with reverse-engineering docs: stop and tell the user to run batch processing first or provide paths manually.
5. If only 1 repo is found: warn the user that reimagine requires 2+ repos. Ask whether to proceed with a single-repo analysis (reduced value) or abort.
6. Track which repos had complete vs. incomplete docs for annotation in the capability map.

Log after completing Step 1: "Step 1 complete: Found [N] repos with reverse-engineering docs. [M] repos have all 3 required docs. [List any repos with missing docs.]"

### Step 2: Load and Parse All Docs

For each validated repo, read the key documents using parallel Task agents.

**Per-repo extraction targets (required docs):**
- From `functional-specification.md`: All FRs, user stories, personas, business rules
- From `integration-points.md`: External services, APIs consumed/exposed, data flows
- From `data-architecture.md`: Data models, API contracts, domain boundaries

**Per-repo extraction targets (optional docs -- skip if not found, note the gap):**
- From `business-context.md`: Product vision, personas, business goals
- From `decision-rationale.md`: Tech stack, ADRs, design principles
- From `technical-debt-analysis.md`: Pain points, migration priorities
- From `configuration-reference.md`: Shared config patterns
- From `operations-guide.md`: Deployment model, infrastructure

For optional documents: if the document does not exist, skip it and note the gap. Missing optional docs reduce analysis depth but do not block processing.

**Parallel processing:** Dispatch Task agents to read docs from multiple repos concurrently. For large batches (10+ repos), process in batches of 5 repos at a time.

**Error handling for Step 2:**
1. If a Task agent fails or times out on a repo: retry once. If the retry fails, proceed with available results and inform the user which repo could not be fully loaded.
2. If a required document exists but contains no extractable content (empty or malformed): treat that repo as having incomplete documentation and annotate accordingly.
3. If more than half of the repos fail to load: stop and report the failures to the user. Ask whether to proceed with the successfully loaded repos or abort.

Log after each repo loads: "Loaded [repo-name]: [N] documents found, [M] capabilities extracted."
Log after completing Step 2: "Step 2 complete: Loaded docs from [N] of [T] repos. [List any repos with load failures or incomplete data.]"

### Step 3: Generate Capability Map

Synthesize all extracted information into a unified capability map with four sub-analyses.

#### 3.1 Business Capability Inventory

Group all functional requirements across repos by business domain:

```
Business Capability Map
=======================

Authentication & Identity
  +-- user-service: User registration, login, password reset, OAuth
  +-- admin-dashboard: Admin login, role management, SSO
  +-- billing-api: API key authentication, webhook signatures
  Overlap: 3 separate auth implementations

Payment & Billing
  +-- billing-api: Stripe integration, invoicing, subscription management
  +-- user-service: Basic payment method storage
  Overlap: Payment data in 2 services
```

#### 3.2 Technical Overlap Analysis

Identify where repos duplicate functionality. Report shared data models, duplicated logic, inconsistent APIs, and shared dependencies.

#### 3.3 Pain Points and Opportunities

Extract from technical debt analyses across repos. List each pain point with the number of repos affected.

#### 3.4 Dependency Graph

Show how repos depend on each other using a Mermaid diagram. For 10+ services, simplify the graph by clustering related services.

**Error handling for Step 3:**
1. If extracted data is insufficient to build a meaningful capability map (fewer than 3 total capabilities identified across all repos): stop and tell the user the docs lack sufficient detail. Suggest running a more thorough reverse-engineering pass.
2. If a repo contributed zero capabilities (all docs were present but no extractable content): annotate the repo as "no capabilities extracted" in the map and inform the user.

**Validation checkpoint:** Before proceeding to Step 4, verify that:
- Every repo that was loaded contributed at least one capability (or is annotated as empty).
- Every required doc that was loaded was processed.
- The overlap analysis identified at least one overlap or explicitly stated "no overlap found."

Log after completing Step 3: "Step 3 complete: Capability map generated with [X] business capabilities across [N] repos. [Y]% functional overlap identified. [Z] pain points found."

### Step 4: Present Capability Map to User

Write `CAPABILITY_MAP.md` to the output directory (see Step 7 for output location). Then display the capability map and ask for the user's reaction:

```
I've analyzed [N] repositories and extracted the capability map above.

Key findings:
- [X] distinct business capabilities identified
- [Y]% functional overlap between services
- [Z] pain points spanning multiple repos
- [W] different tech stacks in use

What direction would you like to explore?

A) Consolidation -- Merge overlappi