logic-extract

What this skill does

# Logic Extract

Trace a specific business logic flow across repos. Produce tech-agnostic specs.

**Estimated Time:** 20-60 minutes (depending on system count, mode, and complexity)
**Prerequisites:** At least one starting-point repo or file path
**Output:** 6 artifacts in `_logic-extract/` (see `operations/output-templates.md`)

---

## When to Use

- Trace a **specific** piece of business logic across multiple repos
- Understand an algorithm end-to-end (entry point to final output)
- Produce tech-agnostic specs for a particular flow (not an entire system)
- Migrate a specific feature and capture every edge case
- Unify logic scattered across services into one picture
- Generate BMAD-format epics scoped to a single capability

**When NOT to use:**
- Entire codebase analysis: use `/stackshift.reverse-engineer`
- All integration points between systems: use `/stackshift.integration-analysis`
- All business logic from one repo: use `/stackshift.portable-extract`
- Repo discovery only: use `/stackshift.discover`

---

## Three Modes

### YOLO (Fully Automatic)
**Time:** ~20-30 min | **User input:** None after kickoff

Auto-explores, auto-clones (max 2 hops), auto-traces. Marks uncertain items with `[AUTO - review recommended]`. Generates all 6 artifacts in one shot. After each phase, output a progress line: `Phase N complete -- {summary}. Proceeding to Phase N+1.`

### Guided (Recommended)
**Time:** ~30-45 min | **User input:** 3-7 targeted questions

Auto-explores high-confidence paths. Pauses for ambiguous branches, discovered repos, business rule interpretation, and edge case handling.

### Interactive
**Time:** ~45-60 min | **User input:** Full walkthrough

Review and approval at each phase boundary. Presents per-repo findings, discovered repos, and traced algorithm steps for confirmation.

---

## Process

### Phase 0: KICKOFF

#### 0.1 Collect Extraction Prompt

Ask the user what logic to trace:

```
What business logic should I trace?

Describe the flow, algorithm, or behavior you want to extract.
Be as specific or broad as you like -- I'll figure out the scope from the code.

Examples:
  "How does dealer config inheritance work across DVS and CMS?"
  "Trace the payment calculation from user input to final amount"
  "How does inventory availability get determined and displayed?"
```

If the prompt is too broad to filter code exploration (e.g., "everything" or "all the logic"), ask the user to narrow scope before proceeding.

Save the extraction prompt. This guides ALL exploration.

#### 0.2 Collect Starting Points

```
Where should I start looking?

Give me repos, directories, or files where this logic lives (or might live).

Examples:
  ~/git/dvs-services-aws                    (repo)
  ~/git/cms-web/src/services/config/        (directory)
  ~/git/payment-service/src/Calculator.java  (specific file)
  "DVS, CMS Web"                            (system names)
```

Accept repos, directories, files, or system names. If zero starting points are provided, ask for at least one before proceeding.

#### 0.3 Mode Selection

```
How should I run the extraction?

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

#### 0.4 Validate Starting Points

For each starting point:
- Verify the path exists on disk.
- For system names without paths: search `~/git/`, `~/code/`, `~/repos/`, sibling directories.
- If not found locally, note for remote search in Phase 2.

Report missing paths and ask the user to correct.

#### 0.5 Check for Existing State

Read `.stackshift-state.json`. If a `logic-extract` entry exists with `status: "in_progress"`:
- **Less than 24 hours old:** Ask the user: "A previous extraction is in progress (Phase {N}, started {time}). Resume or restart?"
- **Older than 24 hours:** Ask the user: "A previous extraction appears abandoned (started {time}). Clear and restart?"

On restart or fresh start, write initial state:

```json
{
  "logic-extract": {
    "status": "in_progress",
    "phase": 0,
    "mode": "guided",
    "extraction_prompt": "How does dealer config inheritance work?",
    "starting_points": [
      { "path": "~/git/dvs-services-aws", "type": "repo", "exists": true }
    ],
    "discovered_repos": [],
    "started_at": "2026-02-23T10:00:00Z",
    "last_updated": "2026-02-23T10:00:00Z"
  }
}
```

Log: `Phase 0 complete -- collected prompt, {N} starting points, mode: {mode}. Proceeding to Phase 1.`

---

### Phase 1: TARGETED RECON

**Input:** Extraction prompt + starting points from Phase 0
**Output:** Per-repo summaries of prompt-relevant findings

Explore ONLY parts of each repo relevant to the extraction prompt. This is NOT exhaustive analysis.

**Dispatch:** Launch parallel Task agents (`stackshift:stackshift-code-analyzer:AGENT`) for each starting point. Wait for all agents to complete before proceeding to Phase 2. Aggregate per-repo summaries into a single findings document.

**Error recovery:** If a Task agent fails or times out, log the failure and continue with remaining agents. If fewer than half of starting points produce results, warn the user before proceeding. See `operations/edge-cases.md` for details.

| What to Find | Guided By | Output |
|--------------|-----------|--------|
| Entry points | Functions/classes/routes matching prompt keywords | Where the logic begins |
| Data models | Types, schemas, entities touched by the logic | What data flows through |
| Business rules | Validations, calculations, decision branches | The core logic |
| Config lookups | Config reads, environment checks, feature flags | What configures behavior |
| API calls | HTTP clients, service calls, event publishing | Where logic crosses boundaries |
| Error handling | Try/catch, error responses, fallback paths | What can go wrong |

**Per-repo summary format:**

```markdown
## [Repo Name] -- Targeted Recon

**Relevant to prompt:** YES / PARTIAL / TANGENTIAL

### Entry Points Found
- `src/services/config/ConfigService.java:getConfig()` -- main config retrieval

### Business Logic Found
- 6-level override hierarchy: national > regional > group > dealer > site > page

### Outbound References (discovery targets)
- Calls `ADD` service for dealer metadata
```

Update state: `phase: 1`. Log: `Phase 1 complete -- recon on {N} repos, found {M} outbound references. Proceeding to Phase 2.`

---

### Phase 2: DISCOVERY & EXPANSION

**Input:** Phase 1 outbound references
**Output:** Expanded repo set

#### 2.1 Identify Discovery Targets

From each Phase 1 summary, extract API endpoints called, service client imports, config references to external systems, event topics published/consumed, and shared data stores.

#### 2.2 Locate Discovered Repos

For each discovery target:

1. Search locally: sibling directories, `~/git/`, `~/code/`, `~/repos/`.
2. Search GitHub if not found locally: auto-detect org from starting-point repos' git remotes, then `gh api search/repositories -f q="org:{org} {system-name}"`.
3. Clone if found remotely:
   - **YOLO:** Clone automatically. On clone failure, mark as `[CLONE FAILED]` and trace from consumer-side only.
   - **Guided:** List discovered repos and ask: "Include these? (Y/n per repo)". On clone failure, report and ask whether to skip or retry.
   - **Interactive:** Present each and ask before cloning.

**Max depth:** 2 hops from starting points.

#### 2.3 Re-run Targeted Recon on New Repos

For each newly added repo, run Phase 1 targeted recon (focused on the extraction prompt).

#### 2.4 Present Confirmed Repo Set

```
Starting from {N} starting points, I traced references and found {M} total repos:

| # | Repo | Relevance | Key Findings |
|---|------|-----------|-------------|
| 1 | dvs-services-aws | PRIMARY | Config hierarchy, override logic |
| 2 | cms-web | PRIMARY | Config consumer |

Does this set look right?
A) Looks good -- proceed with d