# FR-047 手冊可讀性/白話化 polish — Session 交接（2026-07-06）

| 項目 | 值 |
|------|-----|
| 角色 | **不是寫新 spec**（47 頁全完成）。是 FR-047 手冊的**編輯/潤飾者**：user 看 render 出來的 HTML → 指出可讀性/格式問題 → 你 scope 後修 |
| Branch | `main`（全程不切）｜**所有 commit 未 push，push 永遠等 user 明示** |
| 建議模型 | **Sonnet**（措辭/格式潤飾夠用、省）；遇到要查 code/DB 核事實或業務判斷才切 Opus |
| Build | `python3 scripts/deliverables/render_html.py "docs/specs/v1.8.0"`（改完必跑，看 ✅） |

## 這個 session 做了什麼（都已 commit）

一連串「讀者導向」的手冊改造，commit 由舊到新：
- `bf3d4775`/`c3e5c545` 側邊欄改領域分組（＝repo 目錄）+ 首頁「產品選單→spec」對照表 + 各群「功能群總覽」子群
- `0988db03` 解除 `docs/specs/*/html/` 的 gitignore（HTML 站改入版控，**但 html/ 內容還沒 commit**，見下）
- `4657f98c` 讀者/生產內容分離：README 只留讀者物、界線規則寫進生產側
- `13b7d818` 8 個 _overview 加「角色是誰」白話介紹 + user story
- `06368ef5` 白話化第一輪：清頁面 spec 內洩漏的生產/內部術語（tracker/FR-047 連結、intro 句的 `ui_routes.enable=1` 等）
- `7024218c`/`fd4a54a8` 稽核輪次狀態機圖 + 兩張轉換表白話化（`啟動稽核 launch-audit` 這種：白話動詞前置、API action 名保留）
- `06d7cffe` **角色速覽提前到 §1**（45 頁；§2 開頭那份保留，兩處重複、不改章節編號）
- `405f7db0`/`6e4de2f8` **§6 API 格式**：Request/Response 行內 JSON 全改成 ```json 區塊（22 處/13 檔，6 隻平行 agent + 手動）；欄位註記（必/選填/預設/OneOf）用 JSON5 `//` 保留

**規則都寫進 `.claude/skills/writing-feature-specs/`**（往後新頁自動遵守）：讀者vs生產界線、角色速覽提前§1、API 格式鐵則（json 區塊 + 欄位表別擠散文）。

## 還沒做（已記在 tracker.md「最後定版前待辦」段，user 拍板留最後一次多 agent 批次做）

1. **章節連結化 ~1004 處**：①表格「詳述」欄裸文字 §N/UC-XX-NN（774 處）②已是連結但只連檔案開頭沒連精確錨點（230 處）。做法：**用 build 好的 HTML 反查 pandoc 真實錨點 id**（別自己重刻 slugify），每頁一隻 agent 回填 md → 統一 build。
2. **§6 API 格式收尾**：Response 散文串只 project-dashboard 有（已修）；Request JSON 已全轉。若還有零星漏網一併掃。

## 這次驗證有效的工作法（沿用）

user 看 HTML 指問題 → **先 grep 量範圍**（別憑感覺）→ pilot 修 1 處給 user 確認方向 → 確認後才批次（獨立的 per-file 工作派平行 agent，prompt 要寫「只改目標、不動其他技術事實、不 spawn agent、不跑 render_html」）→ 收回後**主導統一驗證**：build ✅ + code-fence 成對 + grep 殘留 0 + 抽讀 2~3 檔忠實度。大改動前先量「跨檔章節號引用」會不會被打斷（曾有 231 處 `_overview §N`）。

## 工作區/流程 caveat（重要）

- **工作區有別的 session 的 WIP，不是你的**：`docs/specs/v1.8.0/evidence/assets/img/`（截圖 session 新圖）、`docs/features/FR-046-.../tracker.md`（M）、`docs/features/ddd-layer-audit/`、`docs/交付文件/*.docx`——**commit 前顯式 `git add <檔名>`、禁 `-am`/`add -A`**，別把這些掃進來。
- **html/ 已解除 ignore 但內容還沒 commit**：等 source md 收斂（含截圖 session）再連 source 一起 commit，避免 build 領先未提交的 md。18M/98 檔，churn 大。
- **FR-046 gate 仍卡著**：Task 11 對帳全綠（`4449ac8e`）等 user 回「對帳 OK」才跑 Task 12/13。非本線工作。
- 收尾類（SUMMARY/memory/Notion/歸檔）一律等 user 明令，不自動做。

## 座標

- 主戰情：`docs/features/FR-047-2607-feature-spec-handbook/tracker.md`（含「最後定版前待辦」段）
- SOP/規則：`.claude/skills/writing-feature-specs/`（SKILL.md + references/page-spec-template.md）
- 事實 dump：`scripts/deliverables/out/{db_schema,routes}.json`
- 合格範本：`docs/specs/v1.8.0/project-management/project-planning.md`