Skip to content

PR Context Cache

Owner Agent: Raana Consumers: /maigo:review step 1

Why this skill exists

/maigo:review 的第一步是 🐱 Raana 抓 context，保存到本次 review rubric 檔開頭的機讀 區段，讓後續角色讀同一份資料。PR 的 CI、留言、thread 狀態與 body 可在 diff 沒變時更新， 因此 PR 每次重新抓取；只有本地 branch／range 在同 source 且 diff sha 未變時還原快取。 rubric 檔路徑不再固定：省略 --rubric 時 script 會依 source 呼叫 scripts/artifact_path.py 算出 .maigo/review/<id>/rubric.md（分目錄前的扁平 .maigo/review-rubric-<id>.md 只在新路徑沒有 cache 時當唯讀退路，永遠不寫；歸屬規則見 artifact-ownership）。

怎麼跑

機械流程由 script 代勞（cache 偵測 / 驗證 / fetch / truncate / 寫檔一條龍）：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pr_context_cache.py" <source> \
    [--rubric PATH] [--base main]
  • <source>：GitHub PR URL / PR 編號（需要 gh CLI）、本地 branch 名、或 commit range
  • 在 maigo repo 自身工作時，直接 python3 scripts/pr_context_cache.py 即可
  • 省略 --rubric 是預設用法——script 自動算路徑；只有需要覆寫既有檔案時才傳 --rubric

stdout 第一行是 cache_hit: true|false，第二行 rubric: <path>，其後是 cache 區段全文—— 含 Source / PR number / Title / Reviewed head（本次 PR commit SHA）/ Body（截 500 行）/ Linked issues / CI status / Diff stat / Review threads（inline review thread，含 resolve 狀態）/ Review summaries（gh pr view --json reviews）/ Conversation comments（gh pr view --json comments） / Diff sha / Full diff（截 2000 行）。

Review threads / summaries / comments 只在 <source> 是 PR 時抓（branch / range diff 沒有對應的 GitHub review thread 可抓）。未解決（[OPEN]）的 thread 在輸出 裡會被特別標出——下結論前先檢查這些 thread 對照目前 diff 是否已經處理， 避免漏看 reviewer 留下但尚未收斂的架構意見（真實事故：只抓 diff + PR body + reviewDecision，漏看某 PR 上一位 reviewer 對 isinstance-based type-switch 設計 留下的 OPEN thread，直到使用者問「有沒有看 TP 說了什麼」才補回）。

行為摘要

  • PR → 每次抓取並保存目前的全部 context，cache_hit: false。以 gh pr view 回傳的 canonical URL／number 統一後續 diff、CI 與 threads 的目標；threads 不取目前 cwd 的 repo，diff stat 使用 additions／deletions／changedFiles metadata。每輪只抓一次 PR diff。
  • 本地 cache hit（branch／range、Source 相同且 diff sha256 未變）→ 印出快取區段。
  • 本地 cache miss 或 PR 刷新 → 寫回 rubric 開頭 <!-- pr-context-cache:start v1 --> … <!-- pr-context-cache:end --> 區段 （無檔案 → 建立；無區段 → prepend；有舊區段 → 整段取代）

PR 的舊扁平快取不當成即時資料；刷新後寫到新路徑，舊檔保持不變。Fetched at 是本次 snapshot 的時間，不能拿前一輪的時間宣稱已刷新。 它也不是最後 review 時間；review 完成後由 review_report.py publish 另記 reviewed_at， 並把這裡的 Reviewed head 寫入 report，供 board 判斷 PR 是否已更新。

Fallback

script 跑不起來（找不到路徑、無 gh CLI、git 失敗 → exit 1 + stderr；或路徑歸屬衝突 status: conflict → exit 3，見 artifact-ownership）→ Raana 回退手動抓：依 /maigo:review step 1 列的 gh pr view / gh pr diff / gh pr checks （或 git diff / git log）指令直接 fetch，不寫 cache。

What this skill does NOT cover

  • 讀 review rubric 檔其餘內容（rubric 本身由 Tomori 撰寫）
  • 評估 diff 是否有問題（那是 Soyo 的工作）
  • 決定要 review 哪個 target（caller 傳進來）
  • 非 review 流程的 PR context 抓取（如 /maigo:describe-pr 不走這個 skill）