alexion/ai-artifacts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add artifact vault contents

Browse Source
This commit is contained in:
alexion
2026-08-01 14:05:09 -04:00
parent 361bde2621
commit 3230f9395b
78 changed files with 6156 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
projects/skills/065-implement-workflow-codebase-design-research.md Normal file
View File

@@ -0,0 +1,53 @@
---
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.