Long Doc Governance

---
name: long-doc-governance
description: 长文档治理 skill。当 post-change-check 报 [CRITICAL] 长文档警告，或用户主动要求"拆文档"、"文档太长"时触发。核心机制：增量治理（不主动拆现有文档，仅在对超长文档做实质修改时治理）、微改豁免、拆分预算退路。触发词："拆文档"、"文档太长"、"split doc"、"文档拆分"。
---

# 长文档治理

## 1. 何时触发

三种入口（任一成立即触发本 skill）：

1. **增量触发**：本轮任务要对某文档做"实质修改"，且该文档行数 ≥ 强制阈值（见下方阈值表）
2. **主动调用**：用户说"帮我拆 XXX"、"这个文档太长了"
3. **检测报告**：`post-change-check` 输出了 `[CRITICAL]` 行且本轮有实质修改

**不触发**：归档目录（默认匹配路径含「归档」的目录，项目可在配置里改）下的文档；`AGENTS.md` / `SKILL.md` 不受管控。

---

## 2. 实质修改 vs 微改

**实质修改（触发治理）**
- 新增章节或 H2/H3 标题
- 新增接口、字段、业务规则
- 改设计描述或状态流转
- 重写段落（语义增量 > 20 行）

**微改（豁免）**
- 错别字、纯排版调整
- 链接修复、版本号 bump
- 纯措辞润色（< 20 行改动）

**自检方式**：`git diff --stat` 看增删行数；语义增量 > 20 行 或 新增 H2/H3 → 实质修改。

**反例（不能当微改）**：重写一段 50 行的设计描述；把一个功能从一处搬到另一处；新增接口参数说明。

---

## 3. 阈值表

只对 `docs/` 下业务文档生效；`AGENTS.md` / `SKILL.md` 不扫描。

| 类型 | 覆盖范围 | 警告阈值 | 强制阈值 |
|---|---|---|---|
| 接口协议 / 测试 / Schema | `*接口*`、`*数据库*`、`*schema*`、`04-测试/` 等路径模式（由项目自定义） | 600 行 | 1000 行 |
| 设计文档 / 总控 | `01-需求/`、`02-页面设计/`、`03-技术设计/`、`00-任务总控/`（非归档）、goal 章程、任务总控、技术方案 | 800 行 | 1500 行 |

扫描命令：`bash <本 skill 目录>/scripts/doc-length-check.sh --format human --scope <file>`（脚本随本 skill 附带，默认阈值在同目录 `doc-length-config.default.json`，项目可用 `.agents/doc-length-config.json` 覆盖）

---

## 4. 拆分预算评估

拆分前先估算工作量：

```
预估时间 ≈ 目标文档行数 / 200 × 5 分钟
```

若 `预估时间 > 主任务工作量 × 1.5` → **停下来问用户三选一**，不要自作主张：

> 「`<文件名>` 共 X 行，拆分预估约 Y 分钟，主任务约 Z 分钟。建议：
> A. 先拆再做（一次付清）
> B. 单独排一个拆分任务，本次先改完
> C. 本次例外，在任务级设计文档（轻量设计方案/任务总控）写明原因」

---

## 5. 拆分操作流程

### 步骤一：分析结构

```bash
grep -n "^## " <file>    # 列出所有 H2 标题与行号
wc -l <file>             # 总行数
```

识别业务边界（按功能模块，不按行数）。

### 步骤二：规划子文件

目标：每个子文件 < 警告阈值 × 70%。

拆分模板：

```
原文件: 03-01-前后端接口协议.md
↓
03-01-前后端接口协议/
  ├── 00-总览与公共约定.md   ← 鉴权、错误码、分页、命名约定
  ├── 01-用户模块.md
  ├── 02-订单模块.md
  └── 03-第三方集成.md
```

### 步骤三：执行拆分

- 原文件改名并移入新目录，保留索引（`00-总览` 列各子文件链接）
- 子文件路径遵守层级编号规则（`NN-名称.md`）

### 步骤四：修复引用

```bash
# 全仓搜旧路径引用（.md / .java / .ts 均查）
grep -rn "旧文件名" . --include="*.md" --include="*.java" --include="*.ts"
```

逐个修复为新路径，确保 anchor 锚点仍然存在。

### 步骤五：验证

```bash
# 若项目存在文档层级检查门禁脚本（如 .agents/hooks/pre-commit-check.sh）则运行；没有则人工核对
bash .agents/hooks/pre-commit-check.sh
```

确认层级编号检查通过。

### 步骤六：提交

```
重构: 长文档治理 — 03-01-前后端接口协议 拆分为 03-01/ 子目录
```