排程模組規格站 — 五階段可追溯性

workflow

6 min read

Spec Dashboard — 四步工作流詳解

本檔為 SKILL.md 引用的詳細工作流指南。每次重生看板前讀一次。

前置認知

  • 本 skill 唯讀所有來源檔，只寫 dashboard.md 一個檔。
  • 看板是衍生視圖：自動區每一格都回指既有欄位，讀不到就標 ?、不編造。
  • 手寫區（手寫區 START…END）神聖不可侵，重生時原樣回填。

步驟 1 — 盤點 feature

  1. 讀 spec-codes.md 的「SPEC_SHORT_NAME 對應表」，取得每個 feature 的：SHORT、中文、目錄、範圍（單一／跨 feature 共用）、狀態（active／tombstone）。這是 feature 清單的權威來源。 tombstone 的短名不列入看板。
  2. 掃 requirement/ 與 spec/ 目錄，確認對應表上的 feature 各有哪些實際檔案存在。
  3. 異常：
    • 對應表已登記但 requirement/、spec/ 皆無任何檔 → 仍列一列，目前階段標 S0（已登記未開工）。
    • 目錄裡有 feature 但對應表沒登記 → 列出來並提示使用者「先去 spec-codes.md 配發短名」，看板暫用目錄名。

步驟 2 — 判階段 + 簽核狀態

對每個 feature：

目前階段 = 存在的最高階產出檔

階段判定檔
S1 需求requirement/{f}/index.md
S2 FSspec/{f}/{f}.fp.md
S3 OOAspec/{f}/{f}.ooa.md
S4 Pseudospec/{f}/{f}.pseudo.md
S5 Code外部 repo —— 僅在 vault 已打 {feature}/spec-vN git tag 時才標，否則一律 —

目前階段 = 有檔存在的最高階。共用模型（如 domain-model）可能無 requirement，S1 欄標 — 共用。

stub 不算產出：判定檔若含哨兵 <!-- spec-stub -->（導覽占位、無實際內容，僅為讓上游 breadcrumb 連結可解析），視同不存在——目前階段取「非 stub 的最高階產出檔」。stub 對應的格子標 🚧stub（不是 ✅），todo 照該 feature 的真實階段擷取（例如 FGS 即使有 .fp/.ooa/.pseudo 三個 stub，目前階段仍為 S1）。

每格簽核狀態 = 讀該檔 breadcrumb「狀態：」欄

抓該檔開頭引用區（>）的「狀態：」行，依關鍵字對應：

breadcrumb 關鍵字看板後綴
已簽核簽核
草稿草稿（格內圖示用 🟡）
living docliving
紀錄區記錄區
  • 讀不到「狀態：」行 → 該格標 ✅?，並記下來於重生後提示。
  • 不要自己推斷簽核與否；只照 breadcrumb 寫的。

最近更新

取該 feature 名下所有檔（含 audit/{SHORT 或 dir}-*.md）中最新的日期。優先序：

  1. breadcrumb 或 audit 檔內明寫的日期（如「狀態：已簽核（2026-06-09…）」、audit 的「修改日期」）。
  2. 找不到內文日期 → 用檔案 mtime。

步驟 3 — 擷取 todo（只彙整、不新增判斷）

每個 feature 一條，簡短一行（含中文）。來源（有則取，無則略）：

  1. requirement（requirement/{f}/index.md）：
    • 「未解問題」狀態導航中仍為 ⬜ #未答 / 🟡 #部分釐清 的題號 → 列「尚有 ⬜qN、🟡qM」。
    • 「需求收斂結論」的「仍待 Stage X 拍板」清單 → 摘其要點。
  2. breadcrumb「（尚未建立）」：指出下一個缺口檔 → 「下一步 → 建 {f}.{下一階段}.md」。
  3. OOA「狀態」欄待決項：如 N1（…）留簽核前確認、N2/N3… → 列出待決標籤。
  4. 最新 audit：
    • 讀 audit/ 中該 feature 最新一份。
    • 若「統計」的 ❌ > 0 或「簽核擋判定：擋」 → todo 標 ⚠ {audit 檔名} 有 ❌×N（擋簽核）：{一句話摘矛盾}。
    • 若 audit 已全簽核（三條簽核欄皆打勾且無 ❌）→ 不標 audit 警示。

擷取原則：照搬既有欄位的措辭，不重新詮釋、不評論、不替使用者拍板。

步驟 4 — 保留手寫區 + 重生

  1. 抽手寫區：讀現有 dashboard.md，擷取 <!-- ===== 手寫區 START 與 <!-- ===== 手寫區 END ===== --> 之間（含兩標記行）的原始內容。
    • 檔不存在 → 用 output-template.md 的空手寫區。
    • 找不到成對標記、或只找到單邊 → 停下、不覆寫，提示使用者「手寫區標記疑似被破壞，請修復後再重生，以免吃掉手寫內容」。
  2. 組裝自動區：套 output-template.md，填入步驟 2–3 的階段總覽表與 todo 清單，更新頂部「最近重生：{今天日期}」。
  3. 回填手寫區：自動區之後接上步驟 4.1 抽出的手寫區，原樣不動。
  4. 覆寫 dashboard.md。
  5. 回報：簡述這次哪些格／todo 變了、有沒有讀不到的欄位（標 ? 的）、有沒有偵測到對應表未登記的目錄。不要把整份看板再倒一次。

不要做的事

不要為何
改任何 requirement／spec／audit 來源檔本 skill 唯讀來源、只寫看板
自己編一個簽核狀態讀不到就標 ?，交回使用者
動手寫區內容那是人的區，原樣保留
替 feature 判斷該不該推進、評論設計那是各 partner／consistency-audit／人的事
看到 audit ❌ 就去修下游只彙整呈現，不 cascade

Graph View