---
status: resolved
parent: "[[038-implement-skill-map]]"
claimed-by: "019fbb66-80d0-7a01-8ac9-01255adfc7b2"
claimed-at: "2026-08-01T00:00:00-04:00"
blocked-by: []
tags:
  - ticket/research
---

# Implement workflow codebase design research

## Question

What role should `codebase-design` have in the packaged Wayfinder-aware implementation workflow, especially for `test-driven-development` and review?

## Findings

The old local `codebase-design` skill and Matt Pocock's `codebase-design` skill are nearly the same direct counterpart.
Both define deep-module vocabulary around module, interface, implementation, depth, seam, adapter, leverage, and locality.
Both aim to make code more testable and maintainable by placing behavior behind a small interface at a clean seam.
Sources: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/SKILL.md`, `https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/SKILL.md`.

The old local `test-driven-development` skill explicitly invokes `/codebase-design` during planning to identify deep modules and testability checks, regardless of what triggered TDD.
That makes `codebase-design` part of the old implementation workflow's dependency graph, not just an opportunistic extra.
Source: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/test-driven-development/SKILL.md`.

The important testing contract is that the interface is the test surface.
Codebase-design says callers and tests cross the same seam, and if tests need to reach past the interface then the module is probably the wrong shape.
This directly supports the TDD and no-mistakes anti-slop rules against implementation-coupled tests.
Source: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/SKILL.md`.

The deepening reference classifies dependencies as in-process, local-substitutable, remote-but-owned, or true external, and maps each category to a testing strategy.
This gives `test-driven-development` a concrete way to choose where a seam goes and what adapter or stand-in is legitimate for tests.
Source: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DEEPENING.md`.

The deepening reference also says to replace, not layer, tests when deepening shallow modules.
Old unit tests on shallow modules become waste once tests exist at the deepened module interface, and tests should assert observable outcomes through the interface rather than internal state.
This is relevant to implementation slices that include prefactoring before behavior.
Source: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DEEPENING.md`.

The design-it-twice reference is a heavier HITL or parallel-agent pattern for exploring alternative interfaces.
It is useful when a task reveals that seam placement or interface shape is a substantive design decision, but it should not become a mandatory step in every implementation slice.
Sources: `/home/alexion/wrk/dotfiles/modules/agents/claude-code/skills/codebase-design/DESIGN-IT-TWICE.md`, `https://raw.githubusercontent.com/mattpocock/skills/main/skills/engineering/codebase-design/DESIGN-IT-TWICE.md`.

The packaged local skills repository does not currently contain a packaged `codebase-design` skill.
If the workflow includes a packaged `test-driven-development` skill that depends on codebase-design vocabulary, either `codebase-design` should be packaged too, or the TDD skill must inline enough of the deep-module and seam-placement contract to stand alone.
Source: `/home/alexion/wrk/skills/skills`.

## Conclusion

Add `codebase-design` to the implementation workflow scope or explicitly inline its deep-module seam guidance into `test-driven-development` and review.
The cleaner workflow is to package `codebase-design` as a supporting skill because TDD, review, and implementation all need the same vocabulary for seams, interfaces, adapters, test surfaces, and prefactoring.