---
name: design-walkthrough
description: F1 Design Walkthrough — structured 6-section audit of a mockup or code deliverable against PRD, sibling visual contract, rule compliance, anti-patterns, and data feasibility. Triggered by "design walkthrough", "走查这个设计", or "audit this design".
---

# Design Walkthrough Agent (F1)

> **触发词**：`design walkthrough` / `走查这个设计` / `audit this design`
> **Inputs**：design deliverable（mockup node-id / code path）+ PRD + discovery output（若有）+ 适用规则集
> **Tools**：Figma MCP（Path A）/ Read / Bash
> **Output**：结构化 walkthrough report（见下方格式）

---

## 使用方法

```
design walkthrough <node-id or file path>
PRD: <link or inline>
Rules: <mockup / code / both>
```

---

## Step 0: Page Type 分类（必做，决定 rule set + section 触发）

| Page Type | 判断条件 | 额外规则 | Data Audit |
|---|---|---|---|
| **Business Dashboard** | 含 chart / KPI metric / financial / derived value | — | 默认触发 |
| **Monitoring / Operator Console** | 含 session status / real-time control / alert | M3 / M4 / M7 | 含 derived value 时触发 |
| **Settings / Form** | 含 input / form / config panel | — | 跳过 |
| **Navigation / Landing** | 顶层导航 / 空态 / 入口页 | — | 跳过 |

---

## Walkthrough Report 格式

```markdown
# Design Walkthrough Report — <Deliverable Name>

**Date**: YYYY-MM-DD
**Deliverable**: <node-id / file path>
**Page type**: <Business Dashboard / Monitoring / Settings / Navigation>
**PRD reference**: <link>
**Rules applied**: design-process.md + domain-tvu.md + <path-specific conventions>

---

## 1. Sibling Visual Contract 一致性（M21 check）

- Sibling probed: <page node-id>
- Contract: Color <token>, Chart <type>, Typography <spec>, Icon <style>, Density <values>, Header <structure>
- Findings:
  - ✅ / ❌ <element>: <assessment>

## 2. PRD + User Story 覆盖率

> 多 US 场景：分两个 sub-table；单 US 场景：合并为一张表。

| 需求 / User Story | Deliverable 对应 | 覆盖状态 |
|---|---|---|
| <PRD requirement / "As X I want Y"> | <element> | ✅ covered / ⚠️ partial / ❌ missing |

Coverage: X / Y items (Z%)

## 3. Rule Compliance

> 只显示 page type 适用的 rule rows。

| Rule | Check | Status | Evidence |
|---|---|---|---|
| M14 Reference adaptation | Probe 参考输入 context 维度 | ✅ / ❌ | <detail> |
| M16 Default evaluation | 所有 source component defaults 被评估 | ✅ / ❌ | <detail> |
| M21 Sibling contract | probe 数值已做 | ✅ / ❌ | <detail> |
| M22 Design intent | user ask 被 acknowledged | ✅ / ❌ | <detail> |
| M11 Self-audit | probe 数值 vs reference | ✅ / ❌ | <detail> |
| M6 Reusable pattern | 是否发现新 reusable pattern | ✅ none / 🟡 found: <name> | <detail> |
| M3 Status colors（Monitoring only）| 红=Live / 绿=Active 遵守 | ✅ / N/A | <detail> |
| M4 Dark theme（Monitoring only）| monitoring 页面 dark only | ✅ / N/A | <detail> |
| M7 Control surface（Monitoring only）| actions > identifiers > status | ✅ / N/A | <detail> |

## 4. Anti-pattern Scan（meta-rules.md）

| Anti-pattern | Found? | Location |
|---|---|---|
| 规则正文枚举特例 | ❌ / ✅ found | <detail> |
| 参考输入当 spec | ❌ / ✅ found | <detail> |
| 未评估 default 直接交付 | ❌ / ✅ found | <detail> |

## 5. 数据可行性 Audit

> Business Dashboard：默认触发。Monitoring / Operator Console：含 derived value 时触发。Settings / Navigation：跳过。

| Metric / Value | 数据来源 | 可行性 | Notes |
|---|---|---|---|
| <metric name> | <source> | ✅ real / ⚠️ estimated / ❌ undefined | |

## 6. Recommended Next Actions

| Priority | Action | Owner |
|---|---|---|
| 🔴 High | <action>（auto-fix candidate） | AI |
| 🟡 Medium | <action>（需用户决策） | User → AI |
| 🟢 Low | <action>（defer 候选） | User |

---

**Walkthrough complete.** Issues found: <N> high / <N> medium / <N> low.
```

---

## Agent 执行协议

1. **Step 0**: 判断 page type → 确定 rule set + Data Audit 触发条件
2. **Read design deliverable**: 用 `get_design_context`（Path A）或 `Read`（Path B）
3. **Probe sibling**（US-3 场景）: 取 sibling visual contract M21 probe 6 维度
4. **PRD + US coverage**: 对照 PRD 逐条检查；单 US 合并进同一张表
5. **Rule compliance**: 按 page type 子集逐条 check，加 M6 新 pattern 扫描
6. **Anti-pattern scan**: 对照 meta-rules.md § 3
7. **Data audit**（按 Step 0 触发条件决定是否执行）: 验证 derived metric 数据来源
8. **Output report**: 按上方格式，N/A 的 section 省略

**不做**：不修改 deliverable，不生成新 deliverable，不产新规则——只输出 report。