octopus-workflow/core/skills/implement/reference/mapping-and-design.md

# Concept Mapping, Gap Analysis & Adaptation Design — Detailed Processes

> Extracted from `implement/SKILL.md` (Mode: port) Phase A2, A3, A4.
> Read this file when executing the Mapping and Design phases in standalone mode.

---

## Phase A2 — Map Concepts

For every source concept, identify the target project's equivalent. This is a
bidirectional mapping — every source entity, every source API call, every
source pattern must have a corresponding target concept.

### Mapping Table

| Source Concept     | Target Equivalent                           | Notes                                                |
| ------------------ | ------------------------------------------- | ---------------------------------------------------- |
| Express middleware | Fastify hook                                | Different signature — adapt order and error handling |
| Sequelize model    | Drizzle schema                              | Different migration strategy — adapt CLI             |
| bcrypt hash        | argon2                                      | Target project's existing auth module uses argon2    |
| Redis cache        | Memory cache (no Redis)                     | Compromise — simplify to in-memory with TTL          |
| Pino logger        | Existing logger module in `src/util/log.ts` | Reuse target's logger                                |

### Rules

- If a source concept has no clear target equivalent, pause and log `[GAP]`.
- If the target has a different pattern for the same concept (e.g. callbacks
  vs. async/await), prefer the TARGET pattern, not the source's.
- If the source uses a library that exists in the target's ecosystem, use the
  version already in the target's `package.json` — do not introduce a different
  version.

---

## Phase A3 — Gap Analysis

For every `[GAP]` from Phase A2, analyze the impact:

### Gap Analysis Table

| Gap                | Impact                               | Alternatives                                                                                | Decision   | Deferred To (slug) | Reactivation Trigger |
| ------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------- | ---------- | ------------------ | -------------------- |
| No Redis in target | Source uses Redis for session store  | 1. Add Redis to target, 2. Use DB for sessions, 3. Use in-memory (not for production)       | {decision} |                    |                      |
| No message queue   | Source uses RabbitMQ for async tasks | 1. Add queue to target, 2. Make synchronous, 3. Use a simpler queue (e.g. database polling) | {decision} |                    |                      |

### Rules

- Do NOT add infrastructure to the target unless absolutely necessary — prefer
  alternatives that use existing target infrastructure.
- If a gap forces a behavior change, mark it as `[FIDELITY DEVIATION]` — the
  port will not behave identically. This must be explicitly approved.

### Deferral Rules

- A gap marked `Deferred` MUST populate both "Deferred To" and "Reactivation Trigger" columns.
- "Deferred To" must reference a concrete artifact slug (e.g. `port-{name}/chunk-http`).
- "Reactivation Trigger" must specify a condition (e.g. "After chunk-auth verification passes").
- Gaps without a reactivation path are treated as `[PORT GAP]` — a blocker for the current port.

---

## Phase A4 — Adaptation Design

Design how the source feature will fit into the target project:

1. **File structure** — where in the target project will the ported code live?
2. **Interface adaptations** — source API signatures must adapt to target
   conventions (e.g. source uses `snake_case`, target uses `camelCase`).
3. **Dependency replacements** — for each source dependency, use the target
   equivalent or the Gap decision from Phase A3.
4. **Test adaptation** — source test framework → target test framework mapping
   (e.g. `describe`/`it` → `describe`/`it` if both use the same pattern, or
   map to target's test DSL).

### Adaptation Design Template

````markdown
## Adaptation Design

### File Structure
```
src/
  {module}/
    {ported_file}.ts — (from source/src/{module}/{file}.js)
    ...
test/
  {module}/
    {ported_test}.test.ts — (from source/test/{module}/{file}.test.js)
```

### Interface Adaptations
| Source | Target | Reason |
|--------|--------|--------|
| `req.body.created_at` | `req.body.createdAt` | Target convention: camelCase |
| `throw new AppError(400, '...')` | `yield* new BadRequest('...')` | Target uses Effect errors |

### Fidelity Deviations
| What Changes | Why | Impact |
|-------------|-----|--------|
| Session store: Redis → DB | Target has no Redis | Slightly higher latency (~5ms), CAP consistency trade |
| Async queue: RabbitMQ → DB polling | Target has no queue broker | Higher latency, lower throughput — acceptable for < 100 ops/min |
````