portable-extract

What this skill does

# Portable Component Extraction

Extract tech-agnostic, reusable component specs from StackShift reverse-engineering documentation.

**Prerequisites:** Gear 2 (Reverse Engineer) completed with all 11 docs
**Output:** 2 portable artifacts in `_portable-extract/`

---

## Terminology

- **FR** - Functional Requirement from source reverse-engineering docs (input)
- **Story** - Portable output story mapped 1:1 from a source FR, unless an FR is split during domain grouping
- **Persona** - Abstract role: `[User]`, `[Admin]`, or `[System]`

---

## When to Activate

Activate when the user says any of:
- "Extract portable component specs"
- "Create tech-agnostic specs from this codebase"
- "Generate portable epics for reuse"
- "Extract business logic for cross-project migration"
- "Run portable extraction"

Also activate when Gear 2 is complete and the user chose `portable-extract` as the implementation framework.

---

## What This Skill Produces

Read all 11 reverse-engineering docs and distill them into 2 portable artifacts:

| Artifact | Primary Source Docs | Purpose |
|---|---|---|
| `epics.md` | functional-specification, business-context, integration-points | BMAD-format epics with abstract personas, no tech-specific stories |
| `component-spec.md` | functional-specification, data-architecture, business-context, integration-points, visual-design-system | Business rules, data contracts, edge cases, interaction patterns |

**Included:** Core business logic, abstract personas, data contracts, edge cases, error states, interaction patterns, accessibility/performance requirements (functional only).

**Excluded (5 categories):**
1. **Tech Setup** - Framework config, build tooling, bundler settings
2. **CI/CD** - Deployment pipelines, Docker configs, environments
3. **Tech Debt** - Source-platform refactoring, version upgrades
4. **Source-Platform Integration** - Specific API endpoints, SDK references, service names
5. **Test Infrastructure** - Test framework config, test runners, coverage tools

---

## Three Modes

### Mode 1: YOLO (Fully Automatic)

Execute all steps without user interaction. Resolve ambiguities by choosing the most restrictive classification (e.g., `[Admin]` over `[User]` when uncertain) and mark with `[AUTO-RESOLVED]`. Log progress at each step boundary.

### Mode 2: Guided (Recommended)

Auto-populate high-confidence items. Present 3-7 targeted questions for genuinely ambiguous items:
- Persona mapping confirmation
- Conflicting business rule priority
- Integration abstraction phrasing
- Epic grouping validation

### Mode 3: Interactive

Pre-load all 11 docs. Walk through each extraction step with the user for review and approval. Present persona abstraction, exclusion filter results, draft business rules, and epic groupings individually.

---

## Document Mapping

### epics.md Sources

```
functional-specification.md
  +-- Functional Requirements  -> Epic grouping (domain-based)
  +-- User Stories             -> Abstracted stories with [User]/[Admin]/[System]
  +-- Acceptance Criteria      -> Preserved (tech-neutral criteria only)
  +-- Business Rules           -> Cross-referenced to component-spec.md (BR-*)

business-context.md
  +-- Target Users & Personas  -> Persona abstraction input
  +-- Business Goals           -> Epic priority ordering
  +-- Product Vision           -> Epic context/rationale

integration-points.md
  +-- External Services        -> Abstracted integration stories
  +-- Data Flow Diagrams       -> Interaction pattern references
```

### component-spec.md Sources

```
functional-specification.md
  +-- Business Rules           -> BR-CALC-*, BR-VAL-*, BR-DEC-*, BR-STATE-*
  +-- Non-Functional Reqs      -> Accessibility, Performance (functional only)
  +-- System Boundaries        -> Data contract boundaries

data-architecture.md
  +-- Data Models              -> DC-IN-*, DC-OUT-*, DC-STATE-*
  +-- API Contracts            -> Abstracted data contracts
  +-- Domain Model             -> State machine definitions

business-context.md
  +-- Business Constraints     -> Constraint rules in business rules section
  +-- Personas                 -> Persona definitions with abstract mapping

integration-points.md
  +-- External Services        -> Abstracted external data providers
  +-- Data Flow Diagrams       -> Interaction patterns (FLOW-*)

visual-design-system.md
  +-- User Flows               -> FLOW-* interaction patterns
  +-- Accessibility Standards  -> Accessibility requirements (functional)
  +-- Responsive Breakpoints   -> Responsive behavior requirements
```

---

## Process

### Step 0: Verify Prerequisites

Run the following check:

```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
DOCS_DIR="$PROJECT_ROOT/docs/reverse-engineering"
REQUIRED_DOCS=("functional-specification.md" "integration-points.md" "configuration-reference.md" "data-architecture.md" "operations-guide.md" "technical-debt-analysis.md" "observability-requirements.md" "visual-design-system.md" "test-documentation.md" "business-context.md" "decision-rationale.md")

MISSING=0
MISSING_NAMES=()
for doc in "${REQUIRED_DOCS[@]}"; do
  if [ ! -f "$DOCS_DIR/$doc" ]; then
    MISSING_NAMES+=("$doc")
    MISSING=$((MISSING + 1))
  fi
done

if [ $MISSING -gt 0 ]; then
  echo "MISSING $MISSING docs: ${MISSING_NAMES[*]}"
  exit 1
fi

echo "All 11 reverse-engineering docs found. Ready for portable extraction."
```

**Error recovery:**
- If ALL docs missing: halt and tell the user to run `/stackshift.reverse-engineer` first.
- If only `business-context.md` and/or `decision-rationale.md` missing (legacy 9-doc run): log `[REDUCED COVERAGE]` warning and proceed. See "Legacy 9-Doc Handling" below.
- If any other doc is missing: halt and tell the user which docs are missing. Do not proceed with partial core docs.

#### Legacy 9-Doc Handling

Older Gear 2 runs produced 9 docs (missing `business-context.md` and `decision-rationale.md`). When these are missing, apply these reduced-coverage rules throughout the pipeline:

- **Persona extraction**: Source personas from `functional-specification.md` user stories only. Skip business-context.md persona scan.
- **Epic priority ordering**: Default all epics to P1 (no business goal data available for priority differentiation).
- **Business constraints**: Omit the business constraints sub-section in component-spec.md. Add a note: `[REDUCED COVERAGE - business-context.md unavailable]`.
- **Decision rationale**: Omit decision rationale references. This does not affect core extraction.

Log at start: `"[REDUCED COVERAGE] Proceeding with 9 docs. business-context.md and/or decision-rationale.md missing. Persona sources, epic priorities, and business constraints will have reduced coverage."`

### Step 1: Load All Reverse-Engineering Docs

Read all available docs from `docs/reverse-engineering/` into memory. Parse each for structured content:
- Extract all FRs, NFRs, user stories, personas
- Extract all business rules, validation rules, calculation formulas
- Extract all data models and API contracts (for data contract abstraction)
- Extract all integration points (for abstraction)
- Note all `[INFERRED]` and `[NEEDS USER INPUT]` markers

**Error recovery:** If any individual doc fails to read, log a warning with the filename and continue with remaining docs. Track which docs were skipped and note affected coverage areas in the final portability report.

Log: `"Loaded N/11 docs. Extracted M FRs, K personas, J integration points."`

### Step 2: Choose Mode

Ask the user which mode to use:

```
How should portable component specs be generated?

A) YOLO - Fully automatic, no questions asked (~10 min)
B) Guided - Auto-fill + 3-7 targeted questions (~15-20 min) (Recommended)
C) Interactive - Step-by-step review (~20-25 min)
```

If running in batch context with `extraction_mode` pre-set, skip this prompt and use the specified mode.

### Step 3: Abstract Personas

Follow the process in `operations/abstract-personas.md`