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

## 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 |