intent-critique

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intent Critique

设计质量的批判性审查。不检查格式，只检查"是否该这么设计"。

Critical review of design quality. Does not check formatting, only checks "whether this design is appropriate".

核心问题

Core Questions

每次 critique 回答一个问题：这个设计能更简单吗？

Each critique answers one question: Can this design be simpler?

检查维度

Review Dimensions

维度	信号	问题
Over-engineering	复杂的配置系统、插件架构、多层抽象	"这个复杂度是当前需求驱动的吗？"
YAGNI	"未来可能需要"、"预留扩展点"、"支持多种..."	"删掉这个，MVP 还能工作吗？"
过早抽象	只有一个实现的接口、只用一次的工具函数	"现在真的需要这层抽象吗？"
边界问题	模块间大量数据传递、循环依赖、职责模糊	"这个边界切在这里自然吗？"
隐藏复杂度	看似简单但实现困难的描述	"这句话背后的实现复杂度是什么？"

Dimension	Signal	Question
Over-engineering	Complex configuration systems, plugin architectures, multi-layer abstractions	"Is this complexity driven by current requirements?"
YAGNI	"May need in the future", "Reserved extension points", "Supports multiple..."	"Can we remove this and still have a working MVP?"
Premature Abstraction	Interfaces with only one implementation, utility functions used only once	"Is this abstraction really needed right now?"
Boundary Issues	Large amount of data transfer between modules, circular dependencies, ambiguous responsibilities	"Is this boundary naturally defined here?"
Hidden Complexity	Seemingly simple descriptions with difficult implementations	"What is the implementation complexity behind this statement?"

工作流程

Workflow

/intent-critique [path]
        ↓
┌───────────────────┐
│  读取 Intent 文件  │
│  理解设计意图      │
└─────────┬─────────┘
          ↓
┌───────────────────┐
│  逐维度分析        │
│  识别可疑设计      │
└─────────┬─────────┘
          ↓
┌───────────────────────────────────────┐
│  对每个发现，与用户讨论：              │
│                                       │
│  展示问题 + 简化建议                   │
│  AskUserQuestion:                     │
│  - 接受简化                           │
│  - 保留原设计（说明理由）              │
│  - 跳过此项                           │
└─────────┬─────────────────────────────┘
          ↓
┌───────────────────┐
│  汇总 critique     │
│  可选更新 Intent   │
└───────────────────┘

/intent-critique [path]
        ↓
┌───────────────────┐
│  Read Intent file  │
│  Understand design intent      │
└─────────┬─────────┘
          ↓
┌───────────────────┐
│  Analyze dimension by dimension        │
│  Identify suspicious designs      │
└─────────┬─────────┘
          ↓
┌───────────────────────────────────────┐
│  For each finding, discuss with user:              │
│                                       │
│  Present issue + simplification suggestion                   │
│  AskUserQuestion:                     │
│  - Accept simplification                           │
│  - Keep original design (explain reason)              │
│  - Skip this item                           │
└─────────┬─────────────────────────────┘
          ↓
┌───────────────────┐
│  Summarize critique     │
│  Optional: Update Intent   │
└───────────────────┘

使用方法

Usage

bash

undefined

bash

undefined

审查指定 Intent

Review specified Intent

/intent-critique src/core/intent/INTENT.md

审查当前目录

Review current directory

/intent-critique

只分析不修改

Analyze only without modification

/intent-critique --dry-run

undefined

/intent-critique --dry-run

undefined

执行步骤

Execution Steps

1. 读取并理解 Intent

1. Read and Understand Intent

先完整阅读 Intent，理解：

要解决什么问题
核心设计决策
主要组件和边界

First read the Intent in full to understand:

What problem is being solved
Core design decisions
Main components and boundaries

2. 逐维度扫描

2. Scan Dimension by Dimension

Over-engineering 信号

Over-engineering Signals

markdown

检查是否存在：
- 可配置的部分 > 3 个
- 插件/扩展机制
- 多于 2 层的抽象
- "支持多种 X"的描述
- 复杂的状态机

markdown

Check for:
- More than 3 configurable parts
- Plugin/extension mechanisms
- More than 2 layers of abstraction
- Descriptions like "supports multiple X"
- Complex state machines

YAGNI 信号

YAGNI Signals

markdown

检查是否存在：
- "未来可能..."
- "预留..."
- "方便以后..."
- 只在"高级场景"使用的功能
- 没有具体 use case 的抽象

markdown

Check for:
- "May need in the future..."
- "Reserved for..."
- "Convenient for future..."
- Features only used in "advanced scenarios"
- Abstractions without specific use cases

过早抽象信号

Premature Abstraction Signals

markdown

检查是否存在：
- 只有一个实现的接口/协议
- 只用一次的公共函数
- 只有一个子类的基类
- 不必要的工厂/策略模式

markdown

Check for:
- Interfaces/protocols with only one implementation
- Public functions used only once
- Base classes with only one subclass
- Unnecessary factory/strategy patterns

边界问题信号

Boundary Issue Signals

markdown

检查是否存在：
- 模块间传递 > 5 个参数
- A 依赖 B，B 也依赖 A
- 一个改动需要同时改多个模块
- 职责描述模糊或重叠

markdown

Check for:
- More than 5 parameters passed between modules
- A depends on B, and B also depends on A
- A single change requires modifying multiple modules
- Ambiguous or overlapping responsibility descriptions

3. 生成发现列表

3. Generate Findings List

对每个发现，准备：

位置：Intent 中的具体 section
问题：简短描述问题
简化建议：具体的替代方案
风险：简化可能带来的代价

For each finding, prepare:

Location: Specific section in the Intent
Issue: Brief description of the problem
Simplification Suggestion: Specific alternative solution
Risk: Potential cost of simplification

4. 交互式讨论

4. Interactive Discussion

对每个发现使用 AskUserQuestion：

发现 1/N: Over-engineering

Section: ## 插件系统
问题: 定义了完整的插件加载、生命周期、沙箱机制，但目前只有 2 个内置功能。

简化建议: 删除插件系统，直接硬编码这 2 个功能。
未来需要时再加。

风险: 如果很快需要第三方插件，要重新设计。

---
AskUserQuestion:
- question: "是否接受这个简化？"
- options:
  - "接受简化" - 删除插件系统设计
  - "保留原设计" - 请说明具体场景
  - "跳过" - 暂不决定

Use AskUserQuestion for each finding:

Finding 1/N: Over-engineering

Section: ## Plugin System
Issue: Defined a complete plugin loading, lifecycle, and sandbox mechanism, but currently only has 2 built-in features.

Simplification Suggestion: Remove the plugin system and directly hardcode these 2 features. Add it back when needed in the future.

Risk: If third-party plugins are needed soon, the design will need to be reworked.

---
AskUserQuestion:
- question: "Accept this simplification?"
- options:
  - "Accept simplification" - Remove plugin system design
  - "Keep original design" - Please specify the scenario
  - "Skip" - Make no decision for now

5. 汇总报告

5. Summarize Report

markdown

undefined

markdown

undefined

Intent Critique Report

文件: src/core/intent/INTENT.md

File: src/core/intent/INTENT.md

统计

Statistics

发现问题: 5
接受简化: 3
保留原设计: 1
跳过: 1

Issues found: 5
Simplifications accepted: 3
Original designs kept: 1
Skipped items: 1

已接受的简化

Accepted Simplifications

1. 删除插件系统

1. Remove Plugin System

原设计: 完整插件架构
简化为: 硬编码 2 个功能
影响 sections: ## 插件系统, ## 架构

Original design: Complete plugin architecture
Simplified to: Hardcode 2 features
Affected sections: ## Plugin System, ## Architecture

2. 合并配置层

2. Merge Configuration Layers

...

保留的设计

Kept Designs

1. 多数据源支持

1. Multi-data Source Support

原因: 用户明确表示 v1.1 需要
建议: 在 Intent 中标注具体 timeline

Reason: User clearly stated it's needed in v1.1
Suggestion: Mark the specific timeline in the Intent

跳过的项目

Skipped Items

...

下一步

Next Steps

更新 Intent 文件（如果选择自动更新）
运行 /intent-validate 检查格式
运行 /intent-review 重新审批受影响的 sections

undefined

Update Intent file (if auto-update is selected)
Run /intent-validate to check formatting
Run /intent-review to re-approve affected sections

undefined

6. 可选：更新 Intent

6. Optional: Update Intent

如果用户同意，自动更新 Intent：

删除被简化掉的 sections
添加简化说明到变更记录
将受影响的 sections 标记回
```
draft
```

If the user agrees, automatically update the Intent:

Remove sections that were simplified
Add simplification notes to the change log
Mark affected sections back to
```
draft
```

讨论技巧

Discussion Techniques

提问方式

Questioning Methods

好的提问:

"删掉 X，系统还能工作吗？"
"有没有具体场景需要 X？"
"X 的复杂度值得吗？"

避免:

预设答案
过于理论化的讨论
同时问多个不相关的问题

Good Questions:

"Can the system still work if we remove X?"
"Is there a specific scenario that requires X?"
"Is the complexity of X worth it?"

Avoid:

Presupposing answers
Overly theoretical discussions
Asking multiple unrelated questions at once

接受"保留"的时机

When to Accept "Keep"

当用户提供：

具体的使用场景
明确的时间线（"下月就要"）
外部约束（"合作方要求"）

记录理由，建议在 Intent 中也注明。

Accept "keep" when the user provides:

Specific usage scenarios
Clear timeline (e.g., "needed next month")
External constraints (e.g., "required by partner")

Record the reason and suggest noting it in the Intent as well.

与其他工具配合

Collaboration with Other Tools

intent-interview → intent-validate → intent-critique → intent-review
                                          ↑
                                     可独立调用
                                     任何时候想反思设计时

intent-interview → intent-validate → intent-critique → intent-review
                                          ↑
                                     Can be called independently
                                     Anytime you want to reflect on the design

不做什么

What Not to Do

❌ 不检查格式（intent-validate 的职责）
❌ 不检查一致性（intent-sync 的职责）
❌ 不标记审批状态（intent-review 的职责）
❌ 不自动做决定（必须与用户讨论）

❌ Do not check formatting (responsibility of intent-validate)
❌ Do not check consistency (responsibility of intent-sync)
❌ Do not mark approval status (responsibility of intent-review)
❌ Do not make decisions automatically (must discuss with user)