APEX Decompose

Break down features from a source codebase into detailed, implementation-ready specifications that an agent can use to rebuild them in a new architecture.

When to Use

Use this skill when you need to understand what existing code does before rewriting it. This is the first step in any replatforming or migration workflow. The output is a specification document, not code.

Workflow

Decomposing a feature involves these steps:

Identify the feature scope (files, modules, entry points)
Analyze behavior and contracts (inputs, outputs, side effects)
Extract implicit knowledge (edge cases, error handling, config dependencies)
Generate the specification document
Validate the spec against the source

Step 1: Identify Feature Scope

Collect all relevant source files. Ask the user or scan the directory:

What feature or module do you want to decompose?
Provide the path(s) to the relevant source files or directories.

Read every file in the scope. Build a dependency graph: which files import which, what external services are called, what state is mutated.

Run the dependency scanner to accelerate this step:

Linux/Mac:

bash "${CLAUDE_SKILL_DIR}/scripts/scan-deps.sh" <source-dir>

Windows:

powershell -File "${CLAUDE_SKILL_DIR}/scripts/scan-deps.ps1" <source-dir>

Step 2: Analyze Behavior and Contracts

For each function, class, or module in scope, document:

Aspect	What to Capture
Inputs	Parameters, environment variables, config values, request shapes
Outputs	Return values, response shapes, files written, events emitted
Side effects	Database writes, API calls, cache mutations, logging
Error handling	Try/catch patterns, error codes, fallback behavior
Dependencies	Internal imports, external packages, services called

Step 3: Extract Implicit Knowledge

This is the critical step most migrations miss. Look for:

Magic values — hardcoded strings, numbers, or thresholds with no documentation
Ordering dependencies — operations that must happen in a specific sequence
Race conditions — concurrent access patterns or timing-sensitive logic
Feature flags — conditional behavior based on config or environment
Undocumented APIs — internal endpoints or contracts between services

Step 4: Generate the Specification

Write the spec to specs/{feature-name}.md using the template in references/spec-template.md.

Step 5: Validate the Spec

Cross-reference the spec against the source code. For each behavior documented, confirm it matches the actual implementation. Flag any ambiguities with [VERIFY] tags for human review.

Output

The final deliverable is a Markdown specification file in specs/ that another agent (or apex-replatform) can consume to implement the feature in a new architecture without needing access to the original source code.

Example output location: specs/user-authentication.md

# Feature: User Authentication

## Overview
Handles user login, session management, and token refresh for the web application.

## Behavior Contract

### Inputs
| Name | Type | Source | Required |
|------|------|--------|----------|
| email | string | request.body | yes |
| password | string | request.body | yes |

### Outputs
| Name | Type | Destination |
|------|------|-------------|
| accessToken | JWT | response.json |
| refreshToken | string | httpOnly cookie |

### Side Effects
1. Creates session record in `sessions` table
2. Emits `user.logged_in` event

## Edge Cases
1. **Invalid credentials** — Returns 401 with generic message
2. **Account locked** — Returns 403 after 5 failed attempts

## Migration Notes
- [VERIFY] Confirm bcrypt rounds (currently 12)

apex-decompose