# Tone and Structure Guide

Use this reference when rewriting HTML, README, cover notes, or summary pages into a formal delivery package.

If the package is Chinese-first and you want a directly reusable template set, read `references/chinese-workflow-templates.md` together with this file.

## 1. Recommended tone

Aim for:
- neutral
- formal
- readable by a recipient who did not join internal discussions
- explicit about what is included and what claims are supported

Prefer:
- “正式报告”
- “结果说明”
- “总览页”
- “材料清单”
- “分析代码”
- “分析数据”
- “建议阅读顺序”
- “当前结论边界”

Avoid:
- “对外正式交接页”
- “外部正式交接包”
- “handoff” / “formal handoff”
- “teacher package”
- “老师您好” / “老师追问”
- “内部讨论” / “内部对接” / “blocked items”
- “基于 OCR 脱敏整理”
- “素材清洗后”
- “本页不复用原始截图 / 昵称 / 日期 / 短链”
- “以下模板基于 OCR 提炼后的公开经验整理”
- “已移除作者名、日期、原始链接与平台痕迹”
- team nicknames, chat slang, or operational meta-commentary
- local absolute paths such as `/Users/...` and `file:///...`

## 2. Role labels

For Chinese packages, default to:
- `需求方：<name>`
- `分析提供方：<name>`

For English packages, default to:
- `Requesting party: <name>`
- `Analysis provider: <name>`

Place these labels in at least one of:
- `README.md`
- `index.html` hero / metadata area
- the main report page near the top

## 3. README skeleton

```markdown
# <package title>

- 需求方：<name>
- 分析提供方：<name>

## 建议阅读顺序
1. 先打开 `index.html`。
2. 再看主报告页 / 补充说明页。
3. 如需复核材料来源，查看 `analysis_code/` 与 `analysis_data/`。

## 包内主要页面
- `index.html`
- `<main-report>.html`
- `<supporting-note>.html`

## 代码与数据
- `analysis_code/`：本次材料直接对应的分析代码。
- `analysis_data/`：本次材料直接对应的分析输入数据或受限数据清单。

## 当前必须坚持的结论边界
- 写清正式主结果是什么。
- 写清哪些补充结果不能被升级表述。
- 写清哪些词不能使用，例如 external validation、causal proof、final endpoint confirmation 等。

## 主要清单
- `<key-table-1>.csv`
- `<key-table-2>.csv`
- `analysis_code/`
- `analysis_data/`
- `assets/`
```

## 4. HTML page naming and framing

Recommended page names:
- `index.html`
- `01_<topic>_formal_report.html`
- `02_<topic>_note.html`
- `03_<topic>_protocol_note.html`

Recommended framing sentences:
- “本页是正式报告的总入口。”
- “本页用于正式结果说明。”
- “本页整理了当前可直接引用的结果、边界与材料清单。”
- “本页补充说明方法边界与结果解读，不改变正式主结果锚点。”

Avoid self-referential framing such as:
- “本页用于对外正式交接”
- “这是交接版页面”
- “给老师看的页面”
- “下面是内部对接说明”

## 5. Boundary-writing rule

Always keep the packaging layer separate from the scientific claim layer.

Write explicitly:
- what the main result is
- what the supporting / sensitivity / robustness layer is
- what the package does **not** prove

Useful sentence patterns:
- “正式主结果仍是……”
- “补充分析用于说明稳健性 / 边界，不改变正式主结果锚点。”
- “该结果属于内部验证 / 补充验证，不应写成 external validation。”
- “该材料支持的是更完整的解释链，不支持更强的因果或泛化宣称。”

## 6. Code and data wording

Preferred wording:
- “本目录纳入本次报告包直接对应的主要分析代码。”
- “本目录纳入本次报告包直接对应的主要分析输入数据。”
- “如原始数据受限，请在 README 中写明受限原因与替代清单。”

Avoid vague wording:
- “相关代码都在这里”
- “大概需要的数据在里面”
- “完整版以后再补”

## 7. Last-pass language sweep

Before shipping, scan for these categories:
- handoff / teacher / internal wording
- OCR / 脱敏 / 素材清洗 / 截图整理 / 已移除作者名等过程暴露措辞
- unsupported claim upgrades
- unexplained abbreviations
- local machine paths
- stale filenames or page titles after renaming
