Intent Normalize

Intent Normalize

扫描现有项目，将 intent 和 planning 文件规范化到 IDD 标准。能自动修的直接修，不能修的打上状态让 TeamSwarm pickup。

设计原则

1. 格式先行 — 所有文件先有 frontmatter，让系统能识别
2. 能修则修 — 机械性问题直接修复（frontmatter、目录结构、命名）
3. 不能修则标记 — 内容问题打上状态，后续由 TeamSwarm 或人处理
4. 幂等 — 多次运行结果一致，已规范的文件不会被改动

工作流程

/​intent-normalize [path]
        ↓
┌───────────────────────────────────┐
│  1. 扫描 intent/ 和 planning/     │
│     发现所有 .md 和 .yaml 文件     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  2. 分析每个文件的合规状态         │
│     - 有无 frontmatter?           │
│     - 有无 Anchor?                │
│     - 目录结构是否完整?            │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  3. 自动修复机械问题               │
│     - 补 frontmatter              │
│     - 创建 records/ + INDEX.md    │
│     - 创建 _archive/, _data/      │
│     - 规范化文件命名               │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  4. 标记内容问题                   │
│     - 缺 Anchor → status: draft   │
│     - 超预算 → 标记 needs_critique │
│     - 无法分类 → status: draft     │
└─────────────┬─────────────────────┘
              ↓
┌───────────────────────────────────┐
│  5. 输出规范化报告                 │
└───────────────────────────────────┘

检查项与修复策略

自动修复（机械性，无需判断）

标记 pickup（需要内容判断）

needs 字段

needs 是 frontmatter 中的 pickup 信号，表示该文件需要后续处理：

---
status: active
needs: [anchor, critique]
---

TeamSwarm 扫描 needs 字段来自动调度后续 skill：

• needs: [anchor] → 安排 /​intent-interview 补充
• needs: [critique] → 安排 /​intent-critique 精简
• needs: [review] → 安排 /​intent-review
• needs: [assumes] → 安排人工补充依赖声明

处理完成后，对应的 needs 项被移除。needs 为空时可以删掉整个字段。

Planning 类型推断

自动从文件内容推断 type:：

执行细节

1. 扫描范围

默认扫描当前项目根目录下的：
- intent/           → 所有 INTENT.md 文件（递归，跳过 _archive/ 和 _data/）
- planning/         → 所有 .md 文件
- **/​intent/        → 模块级 intent 目录

2. Frontmatter 注入

对没有 frontmatter 的文件，在文件头部插入：

Intent 文件：

---
status: active
---

如果文件看起来已经实现（有对应的代码目录和测试），推断为：

---
status: implemented
---

Planning 文件：

---
type: research
---

3. 推断 status 的启发式规则

4. 幂等保证

• 已有正确 frontmatter 的文件不修改
• 已有 records/ 的不重建
• needs 字段只添加不覆盖（合并已有的）
• 每次运行结果相同

输出

规范化报告

# Intent Normalize Report

> 项目: my-project
> 扫描时间: 2026-02-06

## 统计

| 类型 | 扫描 | 已规范 | 自动修复 | 需 pickup |
|------|------|--------|----------|-----------|
| Intent 文件 | 15 | 8 | 5 | 2 |
| Planning 文件 | 7 | 2 | 4 | 1 |
| 目录结构 | — | — | 3 | — |

## 自动修复（已完成）

1. ✅ `intent/​kernel/​proc/​INTENT.md` — 添加 frontmatter `status: active`
2. ✅ `intent/​kernel/​afs/​INTENT.md` — 添加 frontmatter `status: implemented`
3. ✅ `planning/​v2-ideas.md` — 添加 frontmatter `type: idea`
4. ✅ `planning/​legacy-analysis.md` — 添加 frontmatter `type: analysis`
5. ✅ `intent/​kernel/​proc/​records/` — 创建目录 + INDEX.md
6. ✅ `intent/​_archive/` — 创建目录
7. ✅ `intent/​_data/` — 创建目录

## 需要 Pickup（已标记）

| 文件 | needs | 建议 |
|------|-------|------|
| `intent/​ash/​INTENT.md` | `[anchor, critique]` | 缺少 Anchor，612 行超预算 |
| `intent/​surfaces/​INTENT.md` | `[anchor]` | 缺少 Anchor |
| `planning/​random-notes.md` | — | 无法分类，默认 type: idea |

使用

基本用法

/​intent-normalize

扫描并规范化当前项目。

指定路径

/​intent-normalize intent/​kernel/

只规范化特定目录。

Dry run

/​intent-normalize --dry-run

只报告，不做任何修改。

与其他命令配合

/​intent-normalize       # 先规范化格式（本命令）
    ↓
TeamSwarm pickup        # 自动调度 needs 中的后续 skill
    ↓
/​intent-interview       # 处理 needs: [anchor]
/​intent-critique        # 处理 needs: [critique]
/​intent-review          # 处理 needs: [review]
    ↓
/​intent-check           # 最终合规检查