# HWLAB Documentation Governance

This is the local HWLAB copy of the `docs-spec` rules. Use it when editing
`AGENTS.md`, `docs/reference/*.md`, or distilling process records into stable
reference material.

## AGENTS.md

- `AGENTS.md` is only the project-level top index for quickly locating
  commands, entry points, and documents.
- Documents with the same role as `AGENTS.md`, for example `CLAUDE.md`, should
  contain only `@AGENTS.md` so multiple top-level mouths do not drift.
- Each command in `AGENTS.md` keeps one main index entry; command details live
  in the linked reference document.
- Each sublist item describes one function point in one sentence. Do not
  expand implementation details, parameters, or background analysis there.

## docs/reference

- `docs/reference/` records only stable, reusable entry points, prerequisites,
  constraints, and decision criteria.
- Do not put one-time logs, timestamped execution records, changelog-style
  history, or easily stale status notes in `docs/reference/`.
- Each feature or command detail should have an independent reference document
  under `docs/reference/`; `AGENTS.md` links to it.
- When a feature needs detail, update the detailed reference first, then update
  `AGENTS.md` with a one-sentence summary and link.
- Knowledge updates follow these rules: add new stable knowledge, delete stale
  knowledge, fix wrong knowledge, and merge duplicates.
- Avoid duplicated authority. If content repeats across documents, choose one
  reference as the authority and point other documents to it.
- If a reference mentions a skill, explain how the skill relates to HWLAB code,
  hardware, directories, and acceptance criteria. Do not copy generic skill
  CLI usage unless the local HWLAB copy is required for continuity.

## Process Distillation

- Process documents are historical records, usually timestamped and volatile.
- Distillation means extracting only the stable conclusion into
  `docs/reference/`.
- Process records must not be edited or rewritten during distillation.
- Start with older process records and move forward; for large records, read in
  windows and update the reference as stable conclusions emerge.
- Newer stable conclusions override older conflicting conclusions.
- A reference may briefly outline important development turns, but it must not
  become a run log.

## HWLAB Application

- `docs/reference/README.md` is the long-term reference entry.
- `AGENTS.md` stays the short operational index.
- Process issue links such as `#7`, `#61`, `#78`, `#99`, `#108`, and `#109`
  are preserved as sources in references, not copied as full timelines.
- Current HWLAB rules about `16666/16667`, D601 workspace paths, M3 evidence,
  Cloud Workbench default route, and PR workflow live in the dedicated
  reference files.

## Local docs-spec Text

This local copy is kept so HWLAB documentation work remains governed even when
the external skill body is not available in a runner.

```markdown
---
name: docs-spec
description: 用于指导 docs 的文档规范，编辑 CLAUDE.md/AGENTS.md 或者 docs/reference/*.md 或者进行过程文档蒸馏时必须加载本 SKILL
---

- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和文档。
    - 其他和 `AGENTS.md` 具有同等作用的文档（例如 CLAUDE.md )中只写入一行 `@AGENTS.md` 将其引导到 `AGENTS.md`，避免多种口径互相不一致。
    - 每个命令在 `AGENTS.md` 中保留一条主索引，命令下面可以挂多个功能子列表。
    - 每个子列表只描述一个功能点，并使用一句话概括，不在此处展开实现细节、参数说明或背景分析。
- docs/reference 长期参考文档
    - `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准；不要写日期、一次性过程记录、实测流水账或容易过时的 changelog 式内容。
    - 每个子列表应独立对应一个 `docs/reference/` 下的参考文档；如果同一命令包含多个功能，则分别链接到各自文档。
    - 所有功能的详细说明统一写入 `docs/reference/` 下的独立 Markdown 文档，并在 `AGENTS.md` 中提供对应链接索引。
    - 当某项功能需要补充说明时，优先更新 `docs/reference/` 的详细文档，再回到 `AGENTS.md` 维护对应子列表的一句话摘要与链接。
    - 知识更新原则 - 增加新知识、删除过时知识、修改错误知识、合并重复知识
        - 避免重复 - 对于同文档重复的内容应当进行合并，对于跨文档重复的内容，应当选择或者新建一个文档作为唯一权威出处，其他文档交叉引用权威出处。
    - `docs/reference/` 中涉及 skill 的文档，必须突出该 skill 与当前项目代码、硬件、目录和判定标准的具体联系；通用安装、CLI 参数、子命令和完整用法直接交叉引用对应 skill 的 `SKILL.md`，不要在 reference 中重复抄写一份通用说明。
- 过程文档蒸馏
  - 过程文档指的是开发过程中的过程记录，通常带有时间戳，特征是时效性明显，容易过时，代表了系统的发展和转变过程。
  - 过程文档蒸馏指的是将过程文档蒸馏为长期参考文档。
  - 蒸馏原则
    - 从旧到新原则 - 先从旧的过程文档开始整理，然后逐渐处理新的。
      - 滑动窗口 - 对于大的过程文档文件，采用滑动窗口策略，读一定长度（例如 500 行）就更新一次长期参考文档，不要全部读完再更新。
    - 新的覆盖旧的 - 新的过程文档有更高的重要性，在新的和旧不一致时，应当以新的替换旧的。
    - 简述发展过程 - 在长期参考文档中用简短的篇幅描述总体的发展过程 OUTLINE。
      - 避免将发展过程写成流水账。
      - 越早期的发展过程越简略地写。
      - 重要的发展过程节点可以交叉引用过程文档。
  - 不要篡改过程文档 - 过程文档是一手的历史资料，禁止对过程文档进行篡改。
```