wiring-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wiring Test Skill

接线验证Skill

Overview

概述

The Problem: Tests can pass, code can compile, but the feature may never be wired up — command not registered, endpoint not mounted, module not imported, component never rendered. This is a common failure mode in integration.

The Solution: Wiring verification proves integration through three types of evidence:

Truths — Observable behaviors (shell commands returning exit 0)
Artifacts — Files that must exist with real implementation (not just empty files)
Wiring — Code patterns proving connection points (imports, registrations, mounts)

This skill helps you write strong

truths

artifacts

, and

wiring

fields for loom plan stage YAML metadata.

问题： 测试可以通过，代码可以编译，但功能可能从未完成接线——命令未注册、端点未挂载、模块未导入、组件从未渲染。这是集成过程中常见的失败模式。

解决方案： 接线验证通过三类证据证明集成情况：

Truths（事实验证）——可观察的行为（shell命令返回退出码0）
Artifacts（产物验证）——必须存在且包含真实实现的文件（不只是空文件）
Wiring（接线验证）——证明连接点的代码模式（导入、注册、挂载）

本Skill帮助你为loom计划阶段的YAML元数据编写完善的

truths

、

artifacts

和

wiring

字段。

When to Use

使用场景

When writing loom plan stages (especially
```
integration-verify
```
stages)
When verifying that a feature is actually integrated into the application
When reviewing acceptance criteria to ensure they prove functional integration
When debugging why a "passing" feature doesn't work in practice

编写loom计划阶段时（尤其是
```
integration-verify
```
阶段）
验证功能是否实际集成到应用中时
评审验收标准以确保其能证明功能集成有效性时
调试“通过测试但实际无法工作”的功能时

Wiring YAML Format Reference

接线YAML格式参考

Loom plans use three verification fields to prove integration:

yaml

truths:
  - "command-that-proves-behavior"
  - "another-observable-check"

artifacts:
  - "path/to/implementation.rs"
  - "path/to/another/file.ts"

wiring:
  - source: "path/to/integration/point.rs"
    pattern: "mod feature_name"
    description: "Feature module is imported in main"
  - source: "path/to/router.rs"
    pattern: "mount_feature_routes"
    description: "Feature routes are mounted in router"

CRITICAL PATH RULE: All paths (

artifacts

wiring.source

) are relative to the stage's

working_dir

field. If

working_dir: "loom"

, then paths resolve from inside the

loom/

directory.

YAML SYNTAX WARNING: NEVER put triple backticks inside YAML

description

fields. Use plain indented text for code examples instead.

loom计划使用三类验证字段来证明集成情况：

yaml

truths:
  - "command-that-proves-behavior"
  - "another-observable-check"

artifacts:
  - "path/to/implementation.rs"
  - "path/to/another/file.ts"

wiring:
  - source: "path/to/integration/point.rs"
    pattern: "mod feature_name"
    description: "Feature module is imported in main"
  - source: "path/to/router.rs"
    pattern: "mount_feature_routes"
    description: "Feature routes are mounted in router"

关键路径规则： 所有路径（

artifacts

、

wiring.source

）均相对于阶段的

working_dir

字段。若

working_dir: "loom"

，则路径从

loom/

目录下解析。

YAML语法警告： 切勿在YAML的

description

字段中使用三重反引号。代码示例请使用普通缩进文本。

Templates by Feature Type

按功能类型分类的模板

CLI Command

CLI命令

For a new CLI command (e.g.,

loom verify <stage-id>

yaml

truths:
  - "loom verify --help"  # Command responds
  - "loom verify stage-1 --suggest"  # Primary use case works

artifacts:
  - "src/commands/verify.rs"  # Implementation exists
  - "src/verify/mod.rs"  # Supporting module exists

wiring:
  - source: "src/main.rs"
    pattern: "mod commands"
    description: "Commands module imported"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify command exported"
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify variant in CLI enum"

Path Context: If

working_dir: "loom"

, these paths resolve to

loom/src/commands/verify.rs

, etc.

针对新的CLI命令（例如：

loom verify <stage-id>

）：

yaml

truths:
  - "loom verify --help"  # 命令可响应
  - "loom verify stage-1 --suggest"  # 主用例可正常工作

artifacts:
  - "src/commands/verify.rs"  # 实现文件存在
  - "src/verify/mod.rs"  # 支持模块存在

wiring:
  - source: "src/main.rs"
    pattern: "mod commands"
    description: "Commands module imported"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify command exported"
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify variant in CLI enum"

路径上下文： 若

working_dir: "loom"

，这些路径将解析为

loom/src/commands/verify.rs

等。

API Endpoint

API端点

For a REST endpoint (e.g.,

POST /api/features

yaml

truths:
  - "curl -f -X POST http://localhost:8080/api/features -d '{\"name\":\"test\"}'"
  - "curl -f http://localhost:8080/api/features | grep -q '\"features\"'"

artifacts:
  - "src/handlers/features.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "post(\"/features\", create_feature)"
    description: "POST /features route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", api_routes())"
    description: "API routes mounted in application"
  - source: "src/handlers/mod.rs"
    pattern: "pub mod features"
    description: "Features handler exported"

Note: Functional check (curl) proves endpoint is reachable, not just that tests pass.

针对REST端点（例如：

POST /api/features

）：

yaml

truths:
  - "curl -f -X POST http://localhost:8080/api/features -d '{\"name\":\"test\"}'"
  - "curl -f http://localhost:8080/api/features | grep -q '\"features\"'"

artifacts:
  - "src/handlers/features.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "post(\"/features\", create_feature)"
    description: "POST /features route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", api_routes())"
    description: "API routes mounted in application"
  - source: "src/handlers/mod.rs"
    pattern: "pub mod features"
    description: "Features handler exported"

注意： 功能性检查（curl）证明端点可访问，而非仅测试通过。

Module/Library

模块/库

For a new internal module (e.g., authentication module):

yaml

truths:
  - "cargo test auth::"  # Module tests pass
  - "cargo check"  # Module compiles in context

artifacts:
  - "src/auth/mod.rs"
  - "src/auth/jwt.rs"
  - "src/auth/session.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod auth"
    description: "Auth module exported from library root"
  - source: "src/main.rs"
    pattern: "use crate::auth"
    description: "Auth module imported in main"

针对新的内部模块（例如：认证模块）：

yaml

truths:
  - "cargo test auth::"  # 模块测试通过
  - "cargo check"  # 模块在当前上下文可编译

artifacts:
  - "src/auth/mod.rs"
  - "src/auth/jwt.rs"
  - "src/auth/session.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod auth"
    description: "Auth module exported from library root"
  - source: "src/main.rs"
    pattern: "use crate::auth"
    description: "Auth module imported in main"

UI Component

UI组件

For a React/Vue component (e.g.,

FeatureCard

yaml

truths:
  - "npm test -- FeatureCard"  # Component tests pass
  - "npm run build"  # Component compiles

artifacts:
  - "src/components/FeatureCard.tsx"
  - "src/components/FeatureCard.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export { FeatureCard }"
    description: "FeatureCard exported from components barrel"
  - source: "src/pages/Dashboard.tsx"
    pattern: "<FeatureCard"
    description: "FeatureCard rendered in Dashboard"
  - source: "src/pages/Dashboard.tsx"
    pattern: "import.*FeatureCard"
    description: "FeatureCard imported in parent component"

针对React/Vue组件（例如：

FeatureCard

）：

yaml

truths:
  - "npm test -- FeatureCard"  # 组件测试通过
  - "npm run build"  # 组件可编译

artifacts:
  - "src/components/FeatureCard.tsx"
  - "src/components/FeatureCard.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export { FeatureCard }"
    description: "FeatureCard exported from components barrel"
  - source: "src/pages/Dashboard.tsx"
    pattern: "<FeatureCard"
    description: "FeatureCard rendered in Dashboard"
  - source: "src/pages/Dashboard.tsx"
    pattern: "import.*FeatureCard"
    description: "FeatureCard imported in parent component"

Good vs Bad Examples

正反示例对比

Bad: Too Broad

反面示例：过于宽泛

yaml

truths:
  - "cargo test"  # Only proves tests pass, not that feature works
  - "cargo build"  # Only proves it compiles

artifacts:
  - "src/"  # Too broad, proves nothing

wiring: []  # Missing — no integration proof

Problem: These checks don't prove the feature is wired up or functional. Tests can pass even if the feature is never registered/mounted/imported.

yaml

truths:
  - "cargo test"  # 仅证明测试通过，无法证明功能可用
  - "cargo build"  # 仅证明可编译

artifacts:
  - "src/"  # 过于宽泛，无法证明任何内容

wiring: []  # 缺失——无集成证明

问题： 这些检查无法证明功能已完成接线或可正常工作。即使功能从未被注册/挂载/导入，测试也可能通过。

Good: Specific and Functional

正面示例：具体且功能性强

yaml

truths:
  - "loom verify stage-1 --suggest"  # Proves verify command works end-to-end
  - "loom verify --help | grep -q 'suggest'"  # Proves --suggest flag exists

artifacts:
  - "src/commands/verify.rs"  # Implementation file
  - "src/verify/checker.rs"  # Core logic file

wiring:
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify module exported from commands"
  - source: "src/commands/verify.rs"
    pattern: "run_verification"
    description: "Core verification function exists"

Why Better:

Truths prove the actual command works (not just tests)
Artifacts prove specific implementation files exist
Wiring proves the command is registered in the CLI and exposed correctly

yaml

truths:
  - "loom verify stage-1 --suggest"  # 证明verify命令可端到端工作
  - "loom verify --help | grep -q 'suggest'"  # 证明--suggest参数存在

artifacts:
  - "src/commands/verify.rs"  # 实现文件存在
  - "src/verify/checker.rs"  # 核心逻辑文件存在

wiring:
  - source: "src/main.rs"
    pattern: "Commands::Verify"
    description: "Verify command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod verify"
    description: "Verify module exported from commands"
  - source: "src/commands/verify.rs"
    pattern: "run_verification"
    description: "Core verification function exists"

优势：

Truths证明命令实际可用（而非仅测试通过）
Artifacts证明具体实现文件存在
Wiring证明命令已在CLI中注册并正确暴露

Refinement Questions

优化问题清单

Before finalizing your wiring verification, ask yourself:

在最终确定接线验证配置前，请自问：

Truths

What exact command/endpoint/import will the user invoke?
- Not "tests pass" but "the actual feature responds"
What output proves it's working (not just "no error")?
- Look for specific output, exit codes, or behaviors
Can I test the primary use case end-to-end?
- Don't just check
```
--help
```
  , actually run the feature

用户将调用的具体命令/端点/导入是什么？
- 不是“测试通过”，而是“实际功能可响应”
什么输出能证明功能正常工作（而非仅“无错误”）？
- 寻找特定输出、退出码或行为
我能否端到端测试主用例？
- 不要仅检查
```
--help
```
  ，要实际运行功能

Artifacts

What files MUST exist for the feature to function?
- Not just directories or test files, but actual implementation
Are these paths relative to
working_dir
?
- Double-check the stage's
```
working_dir
```
  field
Do these files contain real code (not stubs/TODOs)?
- Loom can check file size or grep for implementation patterns

功能正常运行必须存在哪些文件？
- 不只是目录或测试文件，而是实际实现文件
这些路径是否相对于
working_dir
？
- 仔细检查阶段的
```
working_dir
```
  字段
这些文件是否包含真实代码（而非占位符/TODO）？
- Loom可以检查文件大小或搜索实现模式

Wiring

Where does the feature connect to the existing codebase?
- Commands → CLI parser, Endpoints → router, Modules → parent import
What code pattern proves the connection exists?
- Look for imports, registrations, mount calls, enum variants
Is the pattern specific enough to avoid false positives?
- ```
mod verify
```
  is better than just
```
verify
```
  (could match comments)

功能与现有代码库的连接点在哪里？
- 命令→CLI解析器，端点→路由，模块→父级导入
什么代码模式能证明连接存在？
- 寻找导入、注册、挂载调用、枚举变体
模式是否足够具体以避免误报？
- ```
mod verify
```
  比单纯的
```
verify
```
  更好（后者可能匹配注释）

Working Directory and Path Resolution

工作目录与路径解析

CRITICAL: All verification paths are relative to the stage's

working_dir

field.

yaml

undefined

关键提示： 所有验证路径均相对于阶段的

working_dir

字段。

yaml

undefined

Stage configuration

阶段配置

id: my-stage working_dir: "loom" # Commands execute from .worktrees/my-stage/loom/

Verification paths resolve relative to working_dir

artifacts:
- "src/feature.rs" # Resolves to .worktrees/my-stage/loom/src/feature.rs
wiring:
- source: "src/main.rs" # Resolves to .worktrees/my-stage/loom/src/main.rs pattern: "mod feature" description: "Feature module imported"


**Formula:** `RESOLVED_PATH = WORKTREE_ROOT + working_dir + path`

**Example:** If:

- Worktree root: `.worktrees/my-stage/`
- `working_dir: "loom"`
- Artifact path: `"src/feature.rs"`

Then resolved path: `.worktrees/my-stage/loom/src/feature.rs`

**NO PATH TRAVERSAL:** Never use `../` in paths. All paths must be relative to `working_dir` or deeper.

id: my-stage working_dir: "loom" # 命令在.worktrees/my-stage/loom/目录下执行

验证路径相对于working_dir解析

artifacts:
- "src/feature.rs" # 解析为.worktrees/my-stage/loom/src/feature.rs
wiring:
- source: "src/main.rs" # 解析为.worktrees/my-stage/loom/src/main.rs pattern: "mod feature" description: "Feature module imported"


**公式：** `解析后路径 = 工作树根目录 + working_dir + 路径`

**示例：** 若：

- 工作树根目录：`.worktrees/my-stage/`
- `working_dir: "loom"`
- 产物路径：`"src/feature.rs"`

则解析后路径：`.worktrees/my-stage/loom/src/feature.rs`

**禁止路径遍历：** 切勿在路径中使用`../`。所有路径必须相对于`working_dir`或其下层级。

Copy-Paste YAML Templates

可直接复制的YAML模板

CLI Command Template

CLI命令模板

yaml

truths:
  - "myapp command --help"
  - "myapp command arg1 arg2"  # Primary use case

artifacts:
  - "src/commands/command.rs"

wiring:
  - source: "src/main.rs"
    pattern: "Commands::CommandName"
    description: "Command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod command"
    description: "Command module exported"

yaml

truths:
  - "myapp command --help"
  - "myapp command arg1 arg2"  # 主用例

artifacts:
  - "src/commands/command.rs"

wiring:
  - source: "src/main.rs"
    pattern: "Commands::CommandName"
    description: "Command variant in CLI enum"
  - source: "src/commands/mod.rs"
    pattern: "pub mod command"
    description: "Command module exported"

API Endpoint Template

API端点模板

yaml

truths:
  - "curl -f -X GET http://localhost:PORT/api/endpoint"
  - "curl -f http://localhost:PORT/api/endpoint | grep -q 'expected_field'"

artifacts:
  - "src/handlers/endpoint.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "get(\"/endpoint\", handler)"
    description: "Endpoint route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", routes)"
    description: "API routes mounted"

yaml

truths:
  - "curl -f -X GET http://localhost:PORT/api/endpoint"
  - "curl -f http://localhost:PORT/api/endpoint | grep -q 'expected_field'"

artifacts:
  - "src/handlers/endpoint.rs"
  - "src/routes/api.rs"

wiring:
  - source: "src/routes/api.rs"
    pattern: "get(\"/endpoint\", handler)"
    description: "Endpoint route registered"
  - source: "src/main.rs"
    pattern: "mount(\"/api\", routes)"
    description: "API routes mounted"

Module Template

模块模板

yaml

truths:
  - "cargo test module::"
  - "cargo check"

artifacts:
  - "src/module/mod.rs"
  - "src/module/core.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod module"
    description: "Module exported from library"
  - source: "src/main.rs"
    pattern: "use crate::module"
    description: "Module imported in main"

yaml

truths:
  - "cargo test module::"
  - "cargo check"

artifacts:
  - "src/module/mod.rs"
  - "src/module/core.rs"

wiring:
  - source: "src/lib.rs"
    pattern: "pub mod module"
    description: "Module exported from library"
  - source: "src/main.rs"
    pattern: "use crate::module"
    description: "Module imported in main"

UI Component Template

UI组件模板

yaml

truths:
  - "npm test -- ComponentName"
  - "npm run build"

artifacts:
  - "src/components/ComponentName.tsx"
  - "src/components/ComponentName.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export.*ComponentName"
    description: "Component exported from barrel"
  - source: "src/pages/Parent.tsx"
    pattern: "<ComponentName"
    description: "Component rendered in parent"

yaml

truths:
  - "npm test -- ComponentName"
  - "npm run build"

artifacts:
  - "src/components/ComponentName.tsx"
  - "src/components/ComponentName.test.tsx"

wiring:
  - source: "src/components/index.ts"
    pattern: "export.*ComponentName"
    description: "Component exported from barrel"
  - source: "src/pages/Parent.tsx"
    pattern: "<ComponentName"
    description: "Component rendered in parent"

Integration with Loom Verify Command

与Loom Verify命令的集成

The

loom verify <stage-id>

command executes these checks:

Truths: Runs each shell command, expects exit 0
Artifacts: Checks files exist and are non-empty (> 100 bytes by default)
Wiring: Greps for patterns in source files, expects at least one match

Use

loom verify <stage-id> --suggest

to get fix suggestions when checks fail.

loom verify <stage-id>

命令会执行以下检查：

Truths： 运行每个shell命令，期望返回退出码0
Artifacts： 检查文件是否存在且非空（默认要求大于100字节）
Wiring： 在源文件中搜索指定模式，期望至少匹配一次

当检查失败时，使用

loom verify <stage-id> --suggest

获取修复建议。

Final Checklist

最终检查清单

Before finalizing your wiring verification:

At least one
```
truth
```
proves the feature works end-to-end (not just tests)
All
```
artifacts
```
are specific implementation files (not directories or test files)
All
```
wiring
```
entries have specific patterns (not generic strings like "feature")
All paths are relative to
```
working_dir
```
(no
```
../
```
traversal)
No triple backticks inside YAML
```
description
```
fields
Patterns are specific enough to avoid false matches in comments
Truth commands use
```
-q
```
flag for grep (silent mode, only exit code matters)

在最终确定接线验证配置前：

至少有一个
```
truth
```
证明功能可端到端工作（而非仅测试通过）
所有
```
artifacts
```
均为具体实现文件（而非目录或测试文件）
所有
```
wiring
```
条目均使用具体模式（而非“feature”这类通用字符串）
所有路径均相对于
```
working_dir
```
（无
```
../
```
路径遍历）
YAML的
```
description
```
字段中无三重反引号
模式足够具体以避免匹配注释中的内容
Truth命令在使用grep时添加
```
-q
```
参数（静默模式，仅关注退出码）

Common Pitfalls

常见陷阱

Tests Pass ≠ Feature Works

Bad:
```
truths: ["cargo test"]
```
Good:
```
truths: ["loom verify stage-1"]
```

Generic Patterns Match Too Much
- Bad:
```
pattern: "verify"
```
  (matches comments, strings)
- Good:
```
pattern: "Commands::Verify"
```
  (specific enum variant)
Paths Wrong for working_dir
- Bad:
```
working_dir: "."
```
  with artifact
```
"loom/src/file.rs"
```
  (creates double path)
- Good:
```
working_dir: "loom"
```
  with artifact
```
"src/file.rs"
```
  (resolves correctly)
No Functional Verification
- Bad: Only checking files exist and tests pass
- Good: Actually running the command/endpoint/import and checking output
YAML Syntax Errors
- Bad: Using triple backticks in description field
- Good: Using plain indented text for code examples

Remember: Wiring verification is your last line of defense against "works in isolation, broken in integration" failures. Make it count.

测试通过 ≠ 功能可用
- 错误示例：
```
truths: ["cargo test"]
```
- 正确示例：
```
truths: ["loom verify stage-1"]
```
通用模式匹配范围过广
- 错误示例：
```
pattern: "verify"
```
  （可能匹配注释、字符串）
- 正确示例：
```
pattern: "Commands::Verify"
```
  （特定枚举变体）
路径与working_dir不匹配
- 错误示例：
```
working_dir: "."
```
  搭配产物路径
```
"loom/src/file.rs"
```
  （会生成重复路径）
- 正确示例：
```
working_dir: "loom"
```
  搭配产物路径
```
"src/file.rs"
```
  （解析正确）
无功能性验证
- 错误示例：仅检查文件存在和测试通过
- 正确示例：实际运行命令/端点/导入并检查输出
YAML语法错误
- 错误示例：在description字段中使用三重反引号
- 正确示例：使用普通缩进文本展示代码示例

谨记： 接线验证是你抵御“孤立环境可用、集成环境失效”这类问题的最后防线。请务必重视。

wiring-test

Original

Translation

Wiring Test Skill

接线验证Skill

Overview

概述

When to Use

使用场景

Wiring YAML Format Reference

接线YAML格式参考

Templates by Feature Type

按功能类型分类的模板

CLI Command

CLI命令

API Endpoint

API端点

Module/Library

模块/库

UI Component

UI组件

Good vs Bad Examples

正反示例对比

Bad: Too Broad

反面示例：过于宽泛

Good: Specific and Functional

正面示例：具体且功能性强

Refinement Questions

优化问题清单

Truths

Truths

Artifacts

Artifacts

Wiring

Wiring

Working Directory and Path Resolution

工作目录与路径解析

Stage configuration

阶段配置

Verification paths resolve relative to working_dir

验证路径相对于working_dir解析

Copy-Paste YAML Templates

可直接复制的YAML模板

CLI Command Template

CLI命令模板

API Endpoint Template

API端点模板

Module Template

模块模板

UI Component Template

UI组件模板

Integration with Loom Verify Command

与Loom Verify命令的集成

Final Checklist

最终检查清单

Common Pitfalls

常见陷阱