@alanwang-merit/meritdata-platform-skill-package 1.0.8 → 1.0.10

package/skills/code-low-level-check/references//345/211/215/347/253/257UI/345/212/237/350/203/275/344/275/216/347/272/247/351/227/256/351/242/230/346/243/200/346/237/245/346/270/205/345/215/225.md

@@ -0,0 +1,338 @@
+# 前端 UI 与功能低级问题检查清单
+
+> ⚠️ **重要**：本清单仅作为参考框架，**开发者和测试人员应发散性识别更多低级问题**。
+
+本清单来源于 **美林数据技术股份有限公司大数据研发中心技术平台研发部** 编制的"常见&低级问题清单 V1.0"（2022 年 4 月），并进行了扩展，适用于所有 Web/前端项目的功能送测与低级问题排查。
+
+---
+
+## 一、页面样式问题
+
+### 1.1 基础样式
+
+- [ ] 页面上一眼能看出的样式问题（双滚动条、字体大小、颜色、图标、对齐、换行、冒泡显示、alert 提示语颜色等）
+- [ ] 页面颜色跟换肤不一致（图片除外）
+- [ ] 字体、字号、行高、间距统一
+- [ ] 颜色搭配符合设计规范
+- [ ] 主题切换（深色/浅色）样式一致
+
+### 1.2 渲染性能
+
+- [ ] 切换、刷新页面，可看到渲染过程
+- [ ] 页面正常情况下 3s 内加载
+- [ ] 登录页面用户应无感知加载过程
+- [ ] 首屏白屏时间过长
+- [ ] 页面闪烁/抖动
+
+### 1.3 响应式适配
+
+- [ ] 不同分辨率下显示正常
+- [ ] 不同浏览器显示一致
+- [ ] 移动端/平板适配正确
+
+---
+
+## 二、登录退出问题
+
+### 2.1 登录
+
+- [ ] 页面访问、登录失败
+- [ ] 登录失败提示不明确
+- [ ] 登录成功后未跳转正确页面
+- [ ] 记住密码功能失效
+- [ ] 验证码失效或刷新异常
+- [ ] 多次登录失败未锁定账号
+
+### 2.2 退出
+
+- [ ] 退出失败
+- [ ] 退出后浏览器后退仍可访问
+- [ ] Session/Token 未正确清除
+- [ ] 退出后页面缓存未清理
+- [ ] 多标签页退出不同步
+
+### 2.3 权限
+
+- [ ] 未登录访问受限页面未拦截
+- [ ] Session 过期未提示重新登录
+- [ ] 权限不足页面未友好提示
+
+---
+
+## 三、增删改查操作
+
+### 3.1 通用操作
+
+- [ ] 增删改查提示操作失败
+- [ ] 增加、编辑成功，页面未返回上一级
+- [ ] 状态值未及时更新（根据页面设计而定）
+- [ ] 操作成功后未给用户明确反馈
+- [ ] 操作失败时未显示具体原因
+
+### 3.2 输入校验
+
+- [ ] 输入框为空未校验
+- [ ] 极限值未校验（最大长度、最大数值）
+- [ ] 空格未校验
+- [ ] 特殊字符未校验
+- [ ] 攻击脚本（XSS、SQL 注入）未过滤
+- [ ] 输入框超出字符未限制输入
+- [ ] 必填项未标注
+- [ ] 输入格式校验（邮箱、手机号、身份证等）
+- [ ] 重复输入未检测
+
+### 3.3 弹窗/表单
+
+- [ ] 弹窗标题不正确
+- [ ] 面包屑显示不正确
+- [ ] 表单字段回填不正确
+- [ ] 表单字段显示/隐藏逻辑错误
+- [ ] 弹窗关闭后未清理状态
+
+### 3.4 数据一致性
+
+- [ ] 编辑、查看页面回填信息不正确
+- [ ] 下拉框、单选框选项值不一致
+- [ ] 字典值跨页面不一致
+- [ ] 缓存未及时刷新
+
+### 3.5 删除操作
+
+- [ ] 删除操作没有确认弹框
+- [ ] 删除成功列表未刷新
+- [ ] 删除成功统计数值未刷新
+- [ ] 批量删除未校验
+- [ ] 删除关联数据未提示
+
+### 3.6 查询操作
+
+- [ ] 查询结果不正确
+- [ ] 不支持回车键查询
+- [ ] 不支持点击搜索图标查询
+- [ ] 查询条件未清除/重置
+- [ ] 查询性能差（大数据量卡顿）
+
+### 3.7 防重复提交
+
+- [ ] 连续点击确定/提交按钮，数据显示异常（重复、丢失）
+- [ ] 网络慢时重复点击
+- [ ] 提交后按钮未禁用
+
+### 3.8 分页查询
+
+- [ ] 先翻页再查询，应列表全局查询，而非只对当前页查询
+- [ ] 翻页丢失查询条件
+- [ ] 总数显示不正确
+- [ ] 跳页功能异常
+
+### 3.9 取消操作
+
+- [ ] 点击取消，未清除之前的操作状态和数据
+- [ ] 再次进入页面未显示默认状态
+
+---
+
+## 四、页面联动、状态更新
+
+### 4.1 列表与组织树联动
+
+- [ ] 列表数据进行"增、删、改、查、移动"，组织树未联动
+- [ ] 组织树选中状态，相应列表未联动
+- [ ] 删除数据后，列表和组织树未同步刷新
+
+### 4.2 状态联动
+
+- [ ] 删除角色、密级分类、数据字典值，页面数据未联动
+- [ ] 例如：删除密级分类，页面中分类已删除，但标签底色还显示，或下拉框未更新
+- [ ] 状态切换未同步更新关联数据
+- [ ] 多 Tab 数据未联动
+
+### 4.3 实时刷新
+
+- [ ] 长时间停留页面数据过期
+- [ ] 多用户协作数据不同步
+- [ ] 缓存数据与实际数据不一致
+
+---
+
+## 五、提示语问题
+
+### 5.1 提示语准确性
+
+- [ ] 校验语、提示语、占位符显示错误、缺失、换行、未对齐
+- [ ] 页面、提示语、字段名称带有错别字
+- [ ] 提示信息未对标需求文档
+- [ ] 提示信息模糊不清
+- [ ] 中英文标点混用
+
+### 5.2 提示语场景覆盖
+
+- [ ] 操作成功提示
+- [ ] 操作失败提示（带原因）
+- [ ] 网络异常提示
+- [ ] 权限不足提示
+- [ ] 数据为空提示
+- [ ] 加载中提示
+- [ ] 超时提示
+- [ ] 中间件、应用服务端口号被占用后需要提示信息
+- [ ] 业务异常提示（带错误码）
+
+### 5.3 国际化
+
+- [ ] 多语言支持
+- [ ] 时区显示正确
+- [ ] 数字、日期格式本地化
+
+---
+
+## 六、导入导出类问题
+
+### 6.1 下载/导出
+
+- [ ] 下载、导出文件，列表数据、字段顺序未跟列表保持一致
+- [ ] 文件名显示不正确（中文名称时注意乱码）
+- [ ] 文件格式正确（Excel/CSV/PDF）
+- [ ] 大量数据导出超时
+- [ ] 导出进度提示
+
+### 6.2 上传/导入
+
+- [ ] 未做字段、文本格式校验
+- [ ] 文件大小限制
+- [ ] 文件类型限制
+- [ ] 重复数据处理（跳过/覆盖/提示）
+- [ ] 导入失败错误信息明确
+- [ ] 导入进度提示
+- [ ] 部分成功处理
+
+### 6.3 数据计算
+
+- [ ] 计算逻辑错误
+- [ ] 页面数字不应出现负值、NaN
+- [ ] 科学计数法显示不正确
+- [ ] 精度丢失问题（金额、数量）
+- [ ] 合计/平均值计算错误
+- [ ] 百分比计算错误
+
+---
+
+## 七、日志类问题
+
+### 7.1 日志准确性
+
+- [ ] 日志记录不一致：登录、访问、操作日志显示结果不正确
+- [ ] 重复打印日志
+- [ ] 日志格式不统一
+- [ ] 日志级别使用不当
+- [ ] 日志缺少关键上下文
+
+### 7.2 日志完整性
+
+- [ ] 新增功能带有打印日志的
+- [ ] 列表字段日志样式正确
+- [ ] 操作信息、操作内容显示正确
+- [ ] 异常日志包含堆栈
+- [ ] 日志包含 traceId/用户信息
+
+### 7.3 日志性能
+
+- [ ] 日志量大影响性能
+- [ ] 同步日志阻塞主流程
+- [ ] 日志文件过大未切割
+- [ ] 日志未设置过期清理
+
+---
+
+## 八、兼容性问题
+
+### 8.1 浏览器兼容
+
+- [ ] 谷歌 85 及以上功能、样式正常
+- [ ] 火狐 89 及以上功能、样式正常
+- [ ] IE10、IE11 功能、样式兼容
+- [ ] Edge 浏览器兼容
+- [ ] Safari 浏览器兼容
+
+### 8.2 设备兼容
+
+- [ ] 移动端 iOS Safari 兼容
+- [ ] 移动端 Android Chrome 兼容
+- [ ] 平板设备兼容
+- [ ] 不同分辨率屏幕
+
+### 8.3 系统兼容
+
+- [ ] Windows 系统兼容
+- [ ] macOS 系统兼容
+- [ ] Linux 系统兼容
+
+---
+
+## 九、数据库问题
+
+### 9.1 SQL 升级
+
+- [ ] 新增功能中，程序中带有升级 SQL，系统初始化失败
+- [ ] SVN 提交的升级 SQL 中，SQL 语句执行失败
+- [ ] 升级 SQL 未提供回滚方案
+- [ ] 升级 SQL 与现有数据冲突
+
+### 9.2 数据库操作
+
+- [ ] 缺少必要的索引
+- [ ] SQL 性能问题
+- [ ] 事务处理不当
+- [ ] 锁等待/死锁
+
+---
+
+## 附：常见前端 UI 低级错误 Top 30
+
+| # | 错误类型 | 示例 |
+|---|---------|------|
+| 1 | 双滚动条 | 页面嵌套滚动条 |
+| 2 | 字体不一致 | 不同模块字体大小不一 |
+| 3 | 颜色与换肤不符 | 切换主题后部分样式未变 |
+| 4 | 页面渲染过程可见 | 白屏/闪烁 |
+| 5 | 登录失败提示不清 | "登录失败"无具体原因 |
+| 6 | 退出后浏览器后退可访问 | session 未清除 |
+| 7 | 未登录可访问受限页面 | 权限校验缺失 |
+| 8 | 增删改查提示失败 | 操作成功但提示失败 |
+| 9 | 状态未及时更新 | 添加后列表未刷新 |
+| 10 | 输入框未校验空值 | 必填项可为空 |
+| 11 | 极限值未校验 | 输入超长字符串无限制 |
+| 12 | 特殊字符未过滤 | XSS 攻击 |
+| 13 | 输入超出字符未限制 | 文本框无限输入 |
+| 14 | 必填项未标注 | 表单未标注必填 |
+| 15 | 表单回填不正确 | 编辑时数据错误 |
+| 16 | 下拉框选项不一致 | 不同页面同一字段选项不同 |
+| 17 | 删除无确认弹窗 | 误删数据 |
+| 18 | 删除后列表未刷新 | 数据残留 |
+| 19 | 不支持回车查询 | 必须点击搜索按钮 |
+| 20 | 连续点击重复提交 | 数据重复创建 |
+| 21 | 翻页后查询错误 | 只查询当前页 |
+| 22 | 取消后状态未清 | 再次打开有残留 |
+| 23 | 组织树未联动 | 列表修改但树未同步 |
+| 24 | 字典值删除后残留 | 下拉框还有已删项 |
+| 25 | 提示语错别字 | 用户体验差 |
+| 26 | 导出文件名乱码 | 中文文件名乱码 |
+| 27 | 未做导入校验 | 格式错误数据导入 |
+| 28 | 数字出现 NaN | 除零等计算错误 |
+| 29 | 日志重复打印 | 同一操作多次日志 |
+| 30 | 浏览器不兼容 | 仅支持 Chrome |
+
+---
+
+## 使用说明
+
+本清单应作为**前端送测前/正式评审前**的快速检查工具，由开发人员或测试人员按清单逐项检查。
+
+- **检查时机**：功能送测前、合并请求前、正式评审前
+- **检查时间**：15-20 分钟
+- **检查视角**：开发者、测试人员、UX 设计师
+- **适用范围**：Web 应用、移动端 H5、小程序等
+
+**来源**：
+- 美林数据技术股份有限公司大数据研发中心技术平台研发部
+- 《常见&低级问题清单 V1.0》（2022 年 4 月）
+- 后续扩展补充

package/skills/code-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: code-review
+description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X".
+---
+
+Two-axis review of the diff between `HEAD` and a fixed point the user supplies:
+
+- **Standards** — does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec?
+
+Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings.
+
+The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if `docs/agents/issue-tracker.md` is missing.
+
+## Process
+
+### 1. Pin the fixed point
+
+Whatever the user said is the fixed point — a commit SHA, branch name, tag, `main`, `HEAD~5`, etc. If they didn't specify one, ask for it.
+
+Capture the diff command once: `git diff <fixed-point>...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log <fixed-point>..HEAD --oneline`.
+
+Before going further, confirm the fixed point resolves (`git rev-parse <fixed-point>`) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents.
+
+### 2. Identify the spec source
+
+Look for the originating spec, in this order:
+
+1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
+2. A path the user passed as an argument.
+3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
+4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
+
+### 3. Identify the standards sources
+
+Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
+
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
+### 4. Spawn both sub-agents in parallel
+
+Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
+
+**Standards sub-agent prompt** — include:
+
+- The full diff command and commit list.
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
+
+**Spec sub-agent prompt** — include:
+
+- The diff command and commit list.
+- The path or fetched contents of the spec.
+- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words."
+
+If the spec is missing, skip the Spec sub-agent and note this in the final report.
+
+### 5. Aggregate
+
+Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
+
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+
+## Why two axes
+
+A change can pass one axis and fail the other:
+
+- Code that follows every standard but implements the wrong thing → **Standards pass, Spec fail.**
+- Code that does exactly what the issue asked but breaks the project's conventions → **Spec pass, Standards fail.**
+
+Reporting them separately stops one axis from masking the other.

package/skills/code-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Code Review"
+  short_description: "Review a diff on standards and spec"

package/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."*
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](SKILL.md) — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md))
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both [SKILL.md](SKILL.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md))
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the user can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the user wants a strong read, not a menu.

package/skills/codebase-design/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
+---
+
+# Codebase Design
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
+
+## Going deeper
+
+- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): spin up parallel sub-agents to design the interface several radically different ways, then compare on depth, locality, and seam placement.

package/skills/codebase-design/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Codebase Design"
+  short_description: "Vocabulary for deep-module design"