Back to Details

before-after

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Before/After Verification Skill

Before/After验证Skill

Overview

概述

Before/after verification is a technique for proving that a stage actually changed system behavior. Instead of just checking that the final state is valid, you capture what was true BEFORE implementation and what should be true AFTER implementation. The pair proves your stage caused the change.
This matters because without before/after thinking, you can't distinguish:
  • "The feature already worked" from "My stage made it work"
  • "The bug was already fixed" from "My fix resolved it"
  • "The endpoint existed" from "I created the endpoint"
Before/after验证是一种用于证明某个阶段确实改变了系统行为的技术。它不只是检查最终状态是否有效，还会记录实现之前的真实状态，以及实现之后应达到的状态。这组状态对能够证明是你的阶段带来了系统变化。
这一点至关重要，因为如果没有前后对比的思路，你将无法区分：
  • “功能本来就可用”和“我的阶段让它可用”
  • “Bug本来就已修复”和“我的修复解决了Bug”
  • “端点本来就存在”和“我创建了这个端点”

The Delta-Proof Concept

Delta-Proof概念

A delta-proof is verification that proves a state transition occurred.
Delta-proof是一种能够证明状态转换发生的验证方式。

The Pattern

模式

  1. Before State: Capture system behavior BEFORE implementation
    • For new features: Expected to FAIL (feature doesn't exist yet)
    • For bug fixes: Expected to SUCCEED (bug reproducer demonstrates the problem)
  2. After State: Capture system behavior AFTER implementation
    • For new features: Expected to SUCCEED (feature now exists)
    • For bug fixes: Expected to FAIL (bug reproducer no longer triggers the bug)
  3. The Pair: Together, before + after prove the implementation caused the change
  1. 前置状态：捕获实现前的系统行为
    • 针对新功能：预期执行失败（功能尚未存在）
    • 针对Bug修复：预期执行成功（Bug复现用例能触发问题）
  2. 后置状态：捕获实现后的系统行为
    • 针对新功能：预期执行成功（功能已存在）
    • 针对Bug修复：预期执行失败（Bug复现用例无法再触发问题）
  3. 状态对：前置+后置状态共同证明是实现带来了变化

Why This Matters

重要性

Without delta-proof thinking, verification can be misleading:
Bad Example:
yaml
undefined
如果没有Delta-Proof的思路，验证结果可能会产生误导：
反例：
yaml
undefined

Stage: Add user authentication

阶段：添加用户认证

truths:
  • "cargo test" # All tests pass

Problem: Tests might have passed before this stage. This doesn't prove authentication was added.

**Good Example:**

```yaml
truths:
  • "cargo test" # 所有测试通过

问题：这些测试可能在该阶段执行前就已经通过了，无法证明认证功能是本次添加的。

**正例：**

```yaml

Stage: Add user authentication

阶段：添加用户认证

description: | Implement JWT-based user authentication.
BEFORE: curl -f localhost:8080/api/protected returns 200 (no auth required) AFTER: curl -f localhost:8080/api/protected returns 401 (auth now required) AFTER: curl -f -H "Authorization: Bearer <token>" localhost:8080/api/protected returns 200
truths:
  • "curl -sf localhost:8080/api/protected | grep -q 401"
  • "curl -sf -H 'Authorization: Bearer fake' localhost:8080/api/protected && exit 1 || exit 0"
wiring:
  • source: "src/middleware/auth.rs" pattern: "pub fn require_auth" description: "Authentication middleware registered"

This proves authentication was ADDED by this stage (not already present).
description: | 实现基于JWT的用户认证。
前置：curl -f localhost:8080/api/protected 返回200（无需认证） 后置：curl -f localhost:8080/api/protected 返回401（现在需要认证） 后置：curl -f -H "Authorization: Bearer <token>" localhost:8080/api/protected 返回200
truths:
  • "curl -sf localhost:8080/api/protected | grep -q 401"
  • "curl -sf -H 'Authorization: Bearer fake' localhost:8080/api/protected && exit 1 || exit 0"
wiring:
  • source: "src/middleware/auth.rs" pattern: "pub fn require_auth" description: "认证中间件已注册"

这能够证明认证功能是**本次阶段新增**的（而非本来就存在）。

When to Use Before/After Thinking

何时使用前后对比思路

Use delta-proof verification when:
  1. Adding new features — Prove the feature didn't exist before
  2. Fixing bugs — Prove the bug existed before and is gone after
  3. Changing behavior — Prove old behavior is replaced by new behavior
  4. Creating endpoints/commands — Prove they're newly available
  5. Refactoring with behavior change — Prove the behavior actually changed
Do NOT use when:
  • Verification is straightforward (just checking files exist)
  • The stage is knowledge-only (no implementation)
  • You're just checking code quality (linting, formatting)
在以下场景中使用Delta-Proof验证：
  1. 新增功能——证明功能在之前不存在
  2. 修复Bug——证明Bug之前存在，修复后已消失
  3. 变更行为——证明旧行为已被新行为替代
  4. 创建端点/命令——证明它们是新增可用的
  5. 涉及行为变更的重构——证明行为确实发生了变化
请勿在以下场景使用：
  • 验证逻辑简单直接（仅检查文件是否存在）
  • 阶段仅涉及知识传递（无实现工作）
  • 仅检查代码质量（如代码检查、格式化）

Templates for Common Scenarios

常见场景模板

Scenario 1: New CLI Command

场景1：新增CLI命令

When adding a new CLI command, prove it didn't exist before.
Before State: Command doesn't exist (help fails or command not found) After State: Command exists (help succeeds, basic invocation works)
yaml
- id: add-verify-command
  name: "Add loom verify command"
  stage_type: standard
  working_dir: "loom"
  description: |
    Implement the `loom verify <stage-id>` CLI command.

    DELTA PROOF:
    - BEFORE: `loom verify --help` fails (command not registered)
    - AFTER: `loom verify --help` succeeds
    - AFTER: `loom verify test-stage` runs verification logic

  truths:
    - "loom verify --help"
    - "loom verify nonexistent-stage 2>&1 | grep -q 'Stage not found'"

  wiring:
    - source: "src/main.rs"
      pattern: "verify"
      description: "Verify command registered in CLI"
    - source: "src/commands/verify.rs"
      pattern: "pub fn execute"
      description: "Verify command implementation exists"

  artifacts:
    - "src/commands/verify.rs"
添加新CLI命令时，证明该命令之前不存在。
前置状态：命令不存在（帮助查询失败或提示命令未找到） 后置状态：命令存在（帮助查询成功，基础调用可正常执行）
yaml
- id: add-verify-command
  name: "Add loom verify command"
  stage_type: standard
  working_dir: "loom"
  description: |
    Implement the `loom verify <stage-id>` CLI command.

    DELTA PROOF:
    - BEFORE: `loom verify --help` fails (command not registered)
    - AFTER: `loom verify --help` succeeds
    - AFTER: `loom verify test-stage` runs verification logic

  truths:
    - "loom verify --help"
    - "loom verify nonexistent-stage 2>&1 | grep -q 'Stage not found'"

  wiring:
    - source: "src/main.rs"
      pattern: "verify"
      description: "Verify command registered in CLI"
    - source: "src/commands/verify.rs"
      pattern: "pub fn execute"
      description: "Verify command implementation exists"

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

Scenario 2: New API Endpoint

场景2：新增API端点

When adding an API endpoint, prove it returns 404 before and data after.
Before State: Endpoint returns 404 (not registered) After State: Endpoint returns expected status/data
yaml
- id: add-status-endpoint
  name: "Add /api/status endpoint"
  stage_type: standard
  working_dir: "."
  description: |
    Implement GET /api/status endpoint returning system health.

    DELTA PROOF:
    - BEFORE: curl localhost:8080/api/status returns 404
    - AFTER: curl localhost:8080/api/status returns 200 with JSON health data

  truths:
    - "curl -sf localhost:8080/api/status | jq -e '.healthy'"
    - "curl -sf -o /dev/null -w '%{http_code}' localhost:8080/api/status | grep -q 200"

  wiring:
    - source: "src/routes/mod.rs"
      pattern: "/api/status"
      description: "Status endpoint registered in router"
    - source: "src/handlers/status.rs"
      pattern: "pub async fn status_handler"
      description: "Status handler implementation"

  artifacts:
    - "src/handlers/status.rs"
添加API端点时，证明之前返回404，之后返回数据。
前置状态：端点返回404（未注册） 后置状态：端点返回预期状态码/数据
yaml
- id: add-status-endpoint
  name: "Add /api/status endpoint"
  stage_type: standard
  working_dir: "."
  description: |
    Implement GET /api/status endpoint returning system health.

    DELTA PROOF:
    - BEFORE: curl localhost:8080/api/status returns 404
    - AFTER: curl localhost:8080/api/status returns 200 with JSON health data

  truths:
    - "curl -sf localhost:8080/api/status | jq -e '.healthy'"
    - "curl -sf -o /dev/null -w '%{http_code}' localhost:8080/api/status | grep -q 200"

  wiring:
    - source: "src/routes/mod.rs"
      pattern: "/api/status"
      description: "Status endpoint registered in router"
    - source: "src/handlers/status.rs"
      pattern: "pub async fn status_handler"
      description: "Status handler implementation"

  artifacts:
    - "src/handlers/status.rs"

Scenario 3: New Module/Library

场景3：新增模块/库

When adding a new module, prove imports fail before and succeed after.
Before State: Import/use fails (module doesn't exist) After State: Import/use succeeds
yaml
- id: add-retry-module
  name: "Add retry module"
  stage_type: standard
  working_dir: "loom"
  description: |
    Create retry module with exponential backoff.

    DELTA PROOF:
    - BEFORE: `use crate::retry::RetryPolicy;` would fail (module doesn't exist)
    - AFTER: Module compiles, exports are available

  truths:
    - "cargo check"
    - "cargo test --lib retry"

  wiring:
    - source: "src/lib.rs"
      pattern: "pub mod retry"
      description: "Retry module exported from lib.rs"
    - source: "src/orchestrator/core/orchestrator.rs"
      pattern: "use crate::retry"
      description: "Retry module imported in orchestrator"

  artifacts:
    - "src/retry.rs"
    - "tests/retry_tests.rs"
添加新模块时，证明之前导入失败，之后导入成功。
前置状态：导入/使用失败（模块不存在） 后置状态：导入/使用成功
yaml
- id: add-retry-module
  name: "Add retry module"
  stage_type: standard
  working_dir: "loom"
  description: |
    Create retry module with exponential backoff.

    DELTA PROOF:
    - BEFORE: `use crate::retry::RetryPolicy;` would fail (module doesn't exist)
    - AFTER: Module compiles, exports are available

  truths:
    - "cargo check"
    - "cargo test --lib retry"

  wiring:
    - source: "src/lib.rs"
      pattern: "pub mod retry"
      description: "Retry module exported from lib.rs"
    - source: "src/orchestrator/core/orchestrator.rs"
      pattern: "use crate::retry"
      description: "Retry module imported in orchestrator"

  artifacts:
    - "src/retry.rs"
    - "tests/retry_tests.rs"

Scenario 4: Bug Fix (COUNTERINTUITIVE)

场景4：Bug修复（反直觉）

When fixing a bug, prove the bug reproducer SUCCEEDS before (bug exists) and FAILS after (bug fixed).
Before State: Bug reproducer succeeds (demonstrates the bug) After State: Bug reproducer fails (bug no longer triggers)
This is counterintuitive but correct: the reproducer "working" means the bug is present.
yaml
- id: fix-crash-on-empty-plan
  name: "Fix crash when plan has no stages"
  stage_type: standard
  working_dir: "loom"
  description: |
    Fix crash when initializing empty plan.

    DELTA PROOF (NOTE: Before/after are inverted for bugs):
    - BEFORE: Empty plan causes panic (bug reproducer succeeds at finding the bug)
    - AFTER: Empty plan returns error gracefully (bug reproducer fails to find the bug)

    Verification approach:
    1. Create test case that reproduces the crash
    2. Test should PASS after fix (catches the crash gracefully)
    3. The bug is proven fixed when the panic no longer occurs

  truths:
    - "cargo test test_empty_plan_no_crash"
    - "cargo test --lib plan::parser"

  wiring:
    - source: "src/plan/parser.rs"
      pattern: "if stages.is_empty()"
      description: "Empty stage list check added"
    - source: "src/plan/parser.rs"
      pattern: 'Err.*"Plan must contain at least one stage"'
      description: "Error returned instead of panic"

  artifacts:
    - "tests/empty_plan_tests.rs"
Important: For bug fixes, the test SHOULD FAIL before the fix (reproducing the bug) and PASS after the fix. The wiring verification proves the defensive code was added.
修复Bug时，证明Bug复现用例在之前执行成功（Bug存在），之后执行失败（Bug已修复）。
前置状态：Bug复现用例执行成功（证明Bug存在） 后置状态：Bug复现用例执行失败（无法再触发Bug）
这一点反直觉但正确：复现用例“执行成功”意味着Bug仍然存在。
yaml
- id: fix-crash-on-empty-plan
  name: "Fix crash when plan has no stages"
  stage_type: standard
  working_dir: "loom"
  description: |
    Fix crash when initializing empty plan.

    DELTA PROOF (NOTE: Before/after are inverted for bugs):
    - BEFORE: Empty plan causes panic (bug reproducer succeeds at finding the bug)
    - AFTER: Empty plan returns error gracefully (bug reproducer fails to find the bug)

    Verification approach:
    1. Create test case that reproduces the crash
    2. Test should PASS after fix (catches the crash gracefully)
    3. The bug is proven fixed when the panic no longer occurs

  truths:
    - "cargo test test_empty_plan_no_crash"
    - "cargo test --lib plan::parser"

  wiring:
    - source: "src/plan/parser.rs"
      pattern: "if stages.is_empty()"
      description: "Empty stage list check added"
    - source: "src/plan/parser.rs"
      pattern: 'Err.*"Plan must contain at least one stage"'
      description: "Error returned instead of panic"

  artifacts:
    - "tests/empty_plan_tests.rs"
重要提示：对于Bug修复，测试在修复前应该失败（复现Bug），修复后应该通过。Wiring验证能够证明已添加防御性代码。

Common Pitfalls

常见误区

1. Testing the Wrong Thing

1. 测试错误的内容

Bad:
yaml
undefined
反例：
yaml
undefined

Adding a new user registration endpoint

Adding a new user registration endpoint

truths:
  • "cargo test" # Too broad - doesn't prove endpoint exists

**Good:**

```yaml
truths:
  - "curl -sf -X POST localhost:8080/api/register -d '{\"email\":\"test@example.com\"}' | jq -e '.user_id'"
truths:
  • "cargo test" # Too broad - doesn't prove endpoint exists

**正例：**

```yaml
truths:
  - "curl -sf -X POST localhost:8080/api/register -d '{\"email\":\"test@example.com\"}' | jq -e '.user_id'"

2. Not Capturing Enough State

2. 未捕获足够的状态

Bad:
yaml
undefined
反例：
yaml
undefined

Adding command output

Adding command output

truths:
  • "loom status" # Just checks it runs

**Good:**

```yaml
truths:
  - "loom status | grep -q 'Active Plan:'"
  - "loom status | grep -q 'Executing:'"
truths:
  • "loom status" # Just checks it runs

**正例：**

```yaml
truths:
  - "loom status | grep -q 'Active Plan:'"
  - "loom status | grep -q 'Executing:'"

3. Forgetting This Is About Implementation

3. 忘记核心是实现变更

Before/after is about what YOUR STAGE changes, not about test setup.
Bad thinking: "Before the test runs, I need to set up data. After the test runs, I clean up." Good thinking: "Before my stage, feature X doesn't exist. After my stage, feature X works."
前后对比的核心是你的阶段带来的变化，而非测试环境的准备工作。
错误思路：“测试运行前我需要准备数据，测试运行后我需要清理数据。” 正确思路：“我的阶段执行前，功能X不存在；我的阶段执行后，功能X可用。”

4. Using Before/After When Simple Truths Suffice

4. 在简单验证场景过度使用

Overkill:
yaml
undefined
过度复杂：
yaml
undefined

Just adding a config file

Just adding a config file

description: | BEFORE: config.toml doesn't exist AFTER: config.toml exists
truths:
  • "test -f config.toml"

Better:

```yaml
artifacts:
  - "config.toml"
Reserve before/after thinking for behavioral changes, not simple file additions.
description: | BEFORE: config.toml doesn't exist AFTER: config.toml exists
truths:
  • "test -f config.toml"

更优方案：

```yaml
artifacts:
  - "config.toml"
将前后对比思路保留给涉及行为变更的场景，而非简单的文件添加。

5. Bug Fix Direction Confusion

5. Bug修复方向混淆

Wrong:
yaml
undefined
错误示例：
yaml
undefined

Fix infinite loop bug

Fix infinite loop bug

description: | BEFORE: Test passes AFTER: Test fails demonstrating the bug

**Correct:**

```yaml
description: | BEFORE: Test passes AFTER: Test fails demonstrating the bug

**正确示例：**

```yaml

Fix infinite loop bug

Fix infinite loop bug

description: | BEFORE: Code enters infinite loop (bug exists) AFTER: Code completes successfully (bug fixed)
truths:
  • "timeout 5s cargo test test_no_infinite_loop"
undefined
description: | BEFORE: Code enters infinite loop (bug exists) AFTER: Code completes successfully (bug fixed)
truths:
  • "timeout 5s cargo test test_no_infinite_loop"
undefined

YAML Structure Reference

YAML结构参考

Loom has explicit 
before_stage
and 
after_stage
fields that accept TruthCheck definitions. These run at specific points in the stage lifecycle:
  • before_stage
    : Runs BEFORE the agent starts working (verifies pre-conditions in a fresh worktree)
  • after_stage
    : Runs when the agent calls 
    loom stage complete
    (verifies post-conditions)
Loom提供了明确的
before_stage
和
after_stage
字段，可接受TruthCheck定义。这些字段会在阶段生命周期的特定节点运行：
  • before_stage
    ：在Agent开始工作之前运行（在全新工作目录中验证前置条件）
  • after_stage
    ：在Agent调用
    loom stage complete
    时运行（验证后置条件）

1. Before/After Stage Fields (Explicit Delta Proof)

1. Before/After阶段字段（显式Delta-Proof）

yaml
before_stage:
  - command: "cargo test test_feature"
    exit_code: 1
    description: "Feature test fails before implementation"

after_stage:
  - command: "cargo test test_feature"
    exit_code: 0
    description: "Feature test passes after implementation"
Each entry is a TruthCheck with fields: 
command
(required), 
exit_code
(default 0), 
description
, 
stdout_contains
, 
stdout_not_contains
, 
stderr_empty
.
yaml
before_stage:
  - command: "cargo test test_feature"
    exit_code: 1
    description: "Feature test fails before implementation"

after_stage:
  - command: "cargo test test_feature"
    exit_code: 0
    description: "Feature test passes after implementation"
每个条目都是一个TruthCheck，包含字段：
command
（必填）、
exit_code
（默认0）、
description
、
stdout_contains
、
stdout_not_contains
、
stderr_empty
。

2. Truths (Capture the After State)

2. Truths（捕获后置状态）

yaml
truths:
  - "command that proves feature works"
  - "test that validates behavior"
Truths run AFTER implementation and should succeed.
yaml
truths:
  - "command that proves feature works"
  - "test that validates behavior"
Truths在实现完成后运行，且应执行成功。

3. Wiring (Prove Integration Points)

3. Wiring（证明集成点）

yaml
wiring:
  - source: "src/main.rs"
    pattern: "register_feature"
    description: "Feature registered in main entry point"
yaml
wiring:
  - source: "src/main.rs"
    pattern: "register_feature"
    description: "Feature registered in main entry point"

4. Artifacts (Prove Files Exist)

4. Artifacts（证明文件存在）

yaml
artifacts:
  - "src/feature/implementation.rs"
  - "tests/feature_tests.rs"
yaml
artifacts:
  - "src/feature/implementation.rs"
  - "tests/feature_tests.rs"

5. Stage Description (Document the Delta)

5. 阶段描述（记录增量变化）

Also document delta-proof thinking in the stage description for human readers:
yaml
description: |
  Implement feature X.

  DELTA PROOF:
  - BEFORE: <what's true before this stage>
  - AFTER: <what should be true after this stage>

  [Implementation details...]
同时在阶段描述中记录Delta-Proof思路，方便人类阅读：
yaml
description: |
  Implement feature X.

  DELTA PROOF:
  - BEFORE: <what's true before this stage>
  - AFTER: <what should be true after this stage>

  [Implementation details...]

Complete Example

完整示例

yaml
- id: add-metrics-endpoint
  name: "Add /metrics endpoint"
  stage_type: standard
  working_dir: "."
  description: |
    Add Prometheus-compatible /metrics endpoint.

    DELTA PROOF:
    - BEFORE: curl localhost:8080/metrics returns 404
    - AFTER: curl localhost:8080/metrics returns Prometheus format
    - AFTER: Metrics include request_count, response_time

    Implementation:
    - Create metrics middleware
    - Register /metrics endpoint
    - Export request_count and response_time gauges

  dependencies: ["add-middleware-support"]

  before_stage:
    - command: "curl -sf localhost:8080/metrics"
      exit_code: 1
      description: "Metrics endpoint does not exist yet"

  after_stage:
    - command: "curl -sf localhost:8080/metrics | grep -q 'request_count'"
      exit_code: 0
      description: "Metrics endpoint returns request_count"
    - command: "curl -sf localhost:8080/metrics | grep -q 'response_time'"
      exit_code: 0
      description: "Metrics endpoint returns response_time"

  truths:
    - "curl -sf localhost:8080/metrics | grep -q 'request_count'"
    - "curl -sf localhost:8080/metrics | grep -q 'response_time'"
    - "curl -sf localhost:8080/metrics | grep -q 'TYPE request_count counter'"

  wiring:
    - source: "src/routes/mod.rs"
      pattern: "Router.*metrics"
      description: "Metrics endpoint registered"
    - source: "src/middleware/metrics.rs"
      pattern: "pub fn track_metrics"
      description: "Metrics middleware implemented"

  artifacts:
    - "src/middleware/metrics.rs"
    - "src/routes/metrics.rs"

  acceptance:
    - "cargo test"
    - "cargo clippy -- -D warnings"
yaml
- id: add-metrics-endpoint
  name: "Add /metrics endpoint"
  stage_type: standard
  working_dir: "."
  description: |
    Add Prometheus-compatible /metrics endpoint.

    DELTA PROOF:
    - BEFORE: curl localhost:8080/metrics returns 404
    - AFTER: curl localhost:8080/metrics returns Prometheus format
    - AFTER: Metrics include request_count, response_time

    Implementation:
    - Create metrics middleware
    - Register /metrics endpoint
    - Export request_count and response_time gauges

  dependencies: ["add-middleware-support"]

  before_stage:
    - command: "curl -sf localhost:8080/metrics"
      exit_code: 1
      description: "Metrics endpoint does not exist yet"

  after_stage:
    - command: "curl -sf localhost:8080/metrics | grep -q 'request_count'"
      exit_code: 0
      description: "Metrics endpoint returns request_count"
    - command: "curl -sf localhost:8080/metrics | grep -q 'response_time'"
      exit_code: 0
      description: "Metrics endpoint returns response_time"

  truths:
    - "curl -sf localhost:8080/metrics | grep -q 'request_count'"
    - "curl -sf localhost:8080/metrics | grep -q 'response_time'"
    - "curl -sf localhost:8080/metrics | grep -q 'TYPE request_count counter'"

  wiring:
    - source: "src/routes/mod.rs"
      pattern: "Router.*metrics"
      description: "Metrics endpoint registered"
    - source: "src/middleware/metrics.rs"
      pattern: "pub fn track_metrics"
      description: "Metrics middleware implemented"

  artifacts:
    - "src/middleware/metrics.rs"
    - "src/routes/metrics.rs"

  acceptance:
    - "cargo test"
    - "cargo clippy -- -D warnings"

Integration with Loom Plans

与Loom计划的集成

Planning Phase

规划阶段

When writing stage descriptions:
  1. Think: "What can the system do NOW?"
  2. Think: "What should the system do AFTER this stage?"
  3. Document the delta explicitly
  4. Write verification that captures the after state
编写阶段描述时：
  1. 思考：“系统现在能做什么？”
  2. 思考：“这个阶段执行后，系统应该能做什么？”
  3. 显式记录增量变化
  4. 编写能够捕获后置状态的验证逻辑

Stage Description Template

阶段描述模板

yaml
description: |
  [One-line summary of what this stage does]

  DELTA PROOF:
  - BEFORE: [State before this stage - expected to fail/pass]
  - AFTER: [State after this stage - expected to pass/fail]

  [Detailed implementation guidance]

  EXECUTION PLAN:
  [If using subagents, describe parallel work]
yaml
description: |
  [该阶段功能的一行总结]

  DELTA PROOF:
  - BEFORE: [阶段执行前的状态 - 预期失败/成功]
  - AFTER: [阶段执行后的状态 - 预期成功/失败]

  [详细实现指导]

  EXECUTION PLAN:
  [如果使用子Agent，描述并行工作内容]

Verification Strategy

验证策略

For each stage, choose verification mechanisms:
Verification TypeUse WhenProves
truths
Behavior is observable via shell commandsFeature works at runtime
wiring
Feature must integrate with existing codeCode is connected/registered
artifacts
New files must existFiles were created
acceptance
Standard checks (build, test, lint)Code compiles and tests pass
Use 
truths
and 
wiring
together for strong delta-proofs.
为每个阶段选择合适的验证机制：
验证类型使用场景证明内容
truths
行为可通过Shell命令观测功能在运行时可用
wiring
功能必须与现有代码集成代码已连接/注册
artifacts
必须新增文件文件已创建
acceptance
标准检查（构建、测试、代码检查）代码可编译且测试通过
结合使用
truths
和
wiring
可实现强Delta-Proof验证。

Example: Full Stage with Delta Proof

示例：带Delta-Proof的完整阶段

yaml
- id: add-stage-complete-command
  name: "Add loom stage complete command"
  stage_type: standard
  working_dir: "loom"

  description: |
    Implement `loom stage complete <stage-id>` command to mark stages as complete.

    DELTA PROOF:
    - BEFORE: `loom stage complete --help` fails (command doesn't exist)
    - AFTER: `loom stage complete --help` shows usage
    - AFTER: `loom stage complete test-stage` transitions stage to Completed state

    Implementation:
    - Add StageComplete command to CLI
    - Implement state transition logic
    - Add validation for stage existence
    - Update stage file with completion timestamp

  dependencies: ["knowledge-bootstrap"]

  truths:
    - "loom stage complete --help"
    - "loom stage list | grep -q complete"

  wiring:
    - source: "src/main.rs"
      pattern: "Commands::StageComplete"
      description: "StageComplete command registered in CLI"
    - source: "src/commands/stage.rs"
      pattern: "pub fn complete"
      description: "Stage complete implementation exists"
    - source: "src/models/stage/transitions.rs"
      pattern: "fn transition_to_completed"
      description: "State transition logic implemented"

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

  acceptance:
    - "cargo test"
    - "cargo test stage_complete"
    - "cargo clippy -- -D warnings"
yaml
- id: add-stage-complete-command
  name: "Add loom stage complete command"
  stage_type: standard
  working_dir: "loom"

  description: |
    Implement `loom stage complete <stage-id>` command to mark stages as complete.

    DELTA PROOF:
    - BEFORE: `loom stage complete --help` fails (command doesn't exist)
    - AFTER: `loom stage complete --help` shows usage
    - AFTER: `loom stage complete test-stage` transitions stage to Completed state

    Implementation:
    - Add StageComplete command to CLI
    - Implement state transition logic
    - Add validation for stage existence
    - Update stage file with completion timestamp

  dependencies: ["knowledge-bootstrap"]

  truths:
    - "loom stage complete --help"
    - "loom stage list | grep -q complete"

  wiring:
    - source: "src/main.rs"
      pattern: "Commands::StageComplete"
      description: "StageComplete command registered in CLI"
    - source: "src/commands/stage.rs"
      pattern: "pub fn complete"
      description: "Stage complete implementation exists"
    - source: "src/models/stage/transitions.rs"
      pattern: "fn transition_to_completed"
      description: "State transition logic implemented"

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

  acceptance:
    - "cargo test"
    - "cargo test stage_complete"
    - "cargo clippy -- -D warnings"

Working Directory and Paths

工作目录与路径

All verification paths are relative to 
working_dir
:
yaml
working_dir: "loom"  # Commands execute from loom/ directory

truths:
  - "cargo test"  # Runs in loom/ (where Cargo.toml lives)

artifacts:
  - "src/commands/verify.rs"  # Resolves to loom/src/commands/verify.rs

wiring:
  - source: "src/main.rs"  # Resolves to loom/src/main.rs
If 
working_dir: "."
, paths are relative to worktree root.
所有验证路径均相对于
working_dir
：
yaml
working_dir: "loom"  # Commands execute from loom/ directory

truths:
  - "cargo test"  # Runs in loom/ (where Cargo.toml lives)

artifacts:
  - "src/commands/verify.rs"  # Resolves to loom/src/commands/verify.rs

wiring:
  - source: "src/main.rs"  # Resolves to loom/src/main.rs
如果
working_dir: "."
，则路径相对于工作目录根目录。

Best Practices

最佳实践

  1. Document the delta in stage descriptions - make before/after explicit
  2. Use truths for runtime behavior - prove the feature works when invoked
  3. Use wiring for integration - prove the feature is connected
  4. Use artifacts sparingly - prefer truths/wiring over file existence
  5. Test the delta - run truths against the actual implementation
  6. Think from user perspective - what would a user try to prove it works?
  1. 在阶段描述中记录增量变化——明确标注前后状态
  2. 使用truths验证运行时行为——证明功能调用时可正常工作
  3. 使用wiring验证集成——证明功能已正确接入现有系统
  4. 谨慎使用artifacts——优先使用truths/wiring而非文件存在性检查
  5. 测试增量变化——针对实际实现运行truths验证
  6. 从用户角度思考——用户会通过什么方式证明功能可用？

Summary

总结

Before/after verification proves your stage changed the system:
  • New features: Before fails → After succeeds
  • Bug fixes: Before succeeds (bug exists) → After fails (bug gone)
  • Behavior changes: Before shows old behavior → After shows new behavior
Use 
before_stage
/
after_stage
for explicit automated delta-proof, 
truths
to capture the after state, 
wiring
to prove integration, and 
artifacts
to prove files exist.
Always think: "What can I measure that PROVES this stage made a difference?"
Before/after验证能够证明你的阶段确实改变了系统：
  • 新增功能：前置失败 → 后置成功
  • Bug修复：前置成功（Bug存在） → 后置失败（Bug消失）
  • 行为变更：前置显示旧行为 → 后置显示新行为
使用
before_stage
/
after_stage
实现显式自动化Delta-Proof，使用
truths
捕获后置状态，使用
wiring
证明集成，使用
artifacts
证明文件存在。
始终思考：“我可以通过什么可测量的指标证明这个阶段产生了实际变化？”