---
name: aoa-port-adapter-refactor
description: Refactor code toward clearer ports and adapters so domain or application logic is less entangled with infrastructure details. Use when concrete dependencies leak into core logic, tests are hard because external concerns bleed inward, or a module needs a clearer seam before further change. Do not use for tiny local fixes or when there is no meaningful boundary to clarify.
license: Apache-2.0
compatibility: Designed for Codex or similar coding agents with repository file access and an interactive shell. Network access is optional and only needed when repository validation or referenced workflows require it.
metadata:
  aoa_scope: core
  aoa_status: evaluated
  aoa_invocation_mode: explicit-preferred
  aoa_source_skill_path: skills/aoa-port-adapter-refactor/SKILL.md
  aoa_source_repo: 8Dionysus/aoa-skills
  aoa_technique_dependencies: AOA-T-0016,AOA-T-0015
  aoa_portable_profile: codex-facing-wave-3
---

# aoa-port-adapter-refactor

## Intent
Use this skill to separate domain or application logic from concrete infrastructure details by introducing or clarifying ports and adapters.

## Trigger boundary
Use this skill when:
- business or domain logic is tightly coupled to a concrete dependency
- tests are hard to write because external concerns leak into the core logic
- the same dependency pattern is beginning to repeat across modules
- a module needs a clearer seam before further change

Do not use this skill when:
- the task is a tiny local fix with no architectural pressure
- there is no meaningful boundary to clarify yet
- the code would become more ceremonial than useful after extraction
- the main problem is deciding whether logic belongs in the core or at the edge; use `aoa-core-logic-boundary` first
- the main problem is clarifying repository docs or source-of-truth ownership; use `aoa-source-of-truth-check` first

## Inputs
- target module or slice
- concrete dependency that currently leaks into the core logic
- desired scope of refactor
- validation expectations

## Outputs
- clearer boundary between logic and infrastructure
- proposed or implemented port shape
- proposed or implemented adapter shape
- verification summary

## Procedure
1. identify the concrete dependency that is making change or testing harder
2. isolate the reusable logic from the infrastructure-specific behavior
3. define a narrow port around what the core actually needs
4. move infrastructure-specific behavior behind an adapter or equivalent seam
5. keep the refactor bounded and avoid unrelated cleanup
6. verify that the new boundary improves clarity and does not silently change behavior

## Contracts
- the extracted boundary should reduce coupling, not add decorative abstraction
- the port should stay narrow and purpose-shaped
- the refactor should not widen into a hidden rewrite
- the final result should remain understandable to another human or agent

## Risks and anti-patterns
- introducing empty abstractions with no real boundary value
- extracting a port that mirrors an overgrown concrete dependency instead of narrowing it
- using the refactor as a pretext for unrelated architectural churn
- making tests more indirect without improving clarity

## Verification
- confirm the concrete dependency pressure was real
- confirm the new boundary is narrower and clearer than before
- confirm behavior did not drift silently
- confirm the refactor stayed inside the declared scope

## Technique traceability
Manifest-backed techniques:
- AOA-T-0016 from `8Dionysus/aoa-techniques` at `5c6f0496edc3c2e74590baa35627c85fe58ef765` using path `techniques/docs/bounded-context-map/TECHNIQUE.md` and sections: Intent, When to use, Outputs, Core procedure, Contracts, Validation
- AOA-T-0015 from `8Dionysus/aoa-techniques` at `5c6f0496edc3c2e74590baa35627c85fe58ef765` using path `techniques/evaluation/contract-test-design/TECHNIQUE.md` and sections: Intent, When to use, Inputs, Outputs, Core procedure, Contracts, Risks, Validation

## Adaptation points
Future project overlays may add:
- local architecture conventions
- preferred adapter locations
- local test commands
- repository-specific review rules