describe-pr

/maigo:describe-pr

幫忙寫 PR 的 title 跟 description——拿你 branch 已經有的 commits / diff， 產出符合「user-impact title + Why / What / Test Plan」結構的草稿。 你 review / 修改後再用 gh pr create 或 GitHub UI 開 PR。

這條命令是燈一個人的舞台：orchestrator 先把 git 那些料抓齊（燈沒有 Bash）， 交給燈把它寫成一份 reviewer 讀得懂的 PR narrative。

使用

/maigo:describe-pr                    # 預設 base = main，當前 HEAD
/maigo:describe-pr --base develop     # 指定 base branch
/maigo:describe-pr --base origin/main # 指定 remote base

流程

1. Orchestrator 前置——抓料

燈沒有 Bash，git 相關的料由 orchestrator 先抓齊：

1. 決定 base：

   • 有 --base <ref> → 用該值
   • 無 → 預設 main；若 main 不存在則試 master，再不行 → 印錯誤「找不到 base branch，請用 --base 指定」並結束（非 0 退出）。

2. 抓 git context：

   • git rev-parse --abbrev-ref HEAD（當前 branch 名；若 == base → 印「目前 HEAD 就在 base 上，沒有可描述的變更」並結束）
   • git log <base>..HEAD --pretty=format:'%h %s%n%b' --no-merges（無 commit → 印「<base>..HEAD 沒有 commit，沒東西可描述」並結束）
   • git diff <base>...HEAD --stat
   • git diff <base>...HEAD（過大時取前 2000 行 + 結尾標註「diff truncated」）

3. 偵測 commit-style：

   • 讀 pyproject.toml（找 [tool.commitizen]）/ .cz.toml / .cz.json / cz.yaml / commitlint.config.js / .commitlintrc*
   • 命中 → 標記 commit_style = conventional；否則 commit_style = freeform
   • 此偵測只供 skill 參考既有 commit message 風格用——PR title 本身永不套 conventional commits 格式

4. 偵測 PR template：

   • 依序找：.github/PULL_REQUEST_TEMPLATE.md → .github/pull_request_template.md → .github/PULL_REQUEST_TEMPLATE/ 目錄內第一個 .md 檔
   • 找到 → 讀取 template 內容，作為描述框架傳給燈（取代預設 Why / What / Test Plan 結構）
   • 找不到 → 用 skill 預設結構

把 1–4 的結果整理成一份 bundle，連同「不 hallucinate」守則一起寫進啟動燈的 Task prompt。

2. 燈 (Tomori) — 把料寫成 PR 草稿。「……讓我先理清楚它想做什麼。」

orchestrator 用 Task tool 啟動燈，把前置 bundle 交給她。燈：

• 做啟動時的記憶載入（照 agents/Tomori.md），輸出開頭印 ## Loaded memory entries—— 若有相關 user / convention entry（例：PR 描述偏好、語言偏好）納入草稿考量
• 依 skills/github-title-description/SKILL.md 產出 PR title + description，遵循該 skill 的 Output format（## Suggested PR title + ## Suggested PR description）
• describe-pr 模式不寫 plan.md、不寫任何檔——直接把草稿回給 orchestrator