/decompose

name: decompose
description: "Phase 3: Dependency decomposition. Only invoke when explicitly requested by the user or by the yoink orchestrator."
argument-hint: "[--package PACKAGE_NAME]"

Decompose

> **Do not invoke this skill unless explicitly requested.** It is called by `/yoink:yoink` or run standalone by the user.

**Prerequisite:** `/yoink:curate-tests` must have been completed first.

Seed the decomposition queue with the target package:

uv run python ${CLAUDE_SKILL_DIR}/scripts/decomp.py enqueue <PACKAGE_NAME>

Then run the decomposition loop below until the queue is empty.

---

Decomposition Loop

**Begin loop.** Repeat until the queue is empty.

1. Dequeue

uv run python ${CLAUDE_SKILL_DIR}/scripts/decomp.py dequeue

• If **queue is empty** then **decomposition complete, remove the real library and stop**.

  uv remove <PACKAGE_NAME>

2. Evaluate

Use the **yoink:decomp-evaluator** agent to evaluate whether the dequeued library should be kept or decomposed.

Pass input as JSON:

{
  "library_name": "<DEQUEUED_LIBRARY>",
  "package_name": "yoink_<PACKAGE_NAME>"
}

• If **Keep** then **go back to step 1**.
• If **Decompose** then **continue to step 3** with the evaluation output.

3. Prepare the sub-package for the implementer agent

Complete these steps IN ORDER before entering the loop.

> **Exception:** When the dequeued item is `{original_package}` (the first item in the queue), skip steps 3a–3c and go straight to 3d. Baseline verification (3a) was already completed by `/yoink:curate-tests`, scaffolding (3c) was already done by `/yoink:setup`, and import rewriting (3b) is a no-op for the original package since there are no sub-package imports to rewrite yet.

a. Verify baseline

Run the top-level generated tests:

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/run_tests.py --project-dir . 2>&1

• If **all tests pass** then **proceed to step b**.
• If **any test fails** then **the baseline is broken and must be fixed before proceeding**. Investigate the test failures, fix the issues, and re-run the tests until they all pass.

b. Rewrite imports

Swap `{sub_package}` imports in `yoink_{top_package}/` source code to point at `yoink_{sub_package}`:

uv run ${CLAUDE_PLUGIN_ROOT}/scripts/rewrite_imports.py --package {sub_package} --target-dir yoink_{top_package}

c. Scaffold the sub-package

mkdir -p yoink_{sub_package}
touch yoink_{sub_package}/__init__.py

d. Seed & populate state body

Seed the state file with placeholder values:

"${CLAUDE_SKILL_DIR}/scripts/activate-inner-yoink-loop.sh" --max-iterations 10

e. Populate loop state

Read `.claude/decomp_context.md` and fill in the `PLACEHOLDER` values in the JSON block inside `.claude/inner-yoink-loop.local.md`:

| Field | Where to get the value | |---|---| | top_package | `{top_package}` | | sub_package | `{sub_package}` | | category | from `decomp_context.md` | | strategy | from `decomp_context.md` | | functions_to_replace | JSON array of strings from `decomp_context.md` | | reference_material | from `decomp_context.md`, default: `.yoink/reference/{sub_package}/` | | acceptable_sub_dependencies | JSON array of strings from `decomp_context.md` |

4. Implement & Validate

Use the **yoink:decomp-implementer** agent to implement the sub-package.

• If **completion_promise = `DONE`** then **proceed to step 5**.
• If **completion_promise = `MAX_ITERATIONS_REACHED`** then **stop the loop and report back to the user that the maximum number of iterations has been reached**.
• If **the agent exits without returning `DONE`** then **spin up a new yoink:decomp-implementer agent to continue the task.**

5. Enqueue new dependencies

Using **new_imports** from the implementer's output, enqueue external libraries that `yoink_<PACKAGE>/` now depends on:

uv run python ${CLAUDE_SKILL_DIR}/scripts/decomp.py enqueue <lib1> <lib2> ...

Only enqueue what `yoink_<PACKAGE>/` actually imports, not the full dependency tree of the original library. Use `uv run python ${CLAUDE_SKILL_DIR}/scripts/decomp.py deps <library>` to see pip dependencies as reference.

**Loop back to step 1.**