Pm

/pm is the only entry point that touches GitHub issues and milestones. The other skills consume issues (/be, /fe) but never create them. The full skill chain looks like this:

/pm discuss  →  /pm plan  →  /be / /fe / /bte  →  /summary  →  PR
   (Q&A)        (issues)      (implement)         (doc sync)

What /pm owns

• GitHub issues — creating, labelling, milestoning, body formatting. Reading existing issues for context.
• GitHub milestones — creating (without due dates), naming, attaching issues.
• Feature breakdown — decomposing a feature description into one issue per backend domain + one issue per frontend resource + a separate schema issue when db_schema.sql is touched. Explicit dependency edges between issues.
• Dispatching /be / /fe — after issues are created and the user has reviewed them on GitHub, /pm plan invokes /be / /fe in dependency order via the Skill tool.

What /pm does NOT own

• Code, tests, schema, or any file edit outside .claude/ — /pm calls /be / /fe for that.
• PRs — /be / /fe open PRs; /pm only creates the issues those PRs close.
• Doc updates — /summary handles drift after the fact.
• Labels themselves — .claude/labels.yaml is the label source of truth (see CLAUDE.md > GitHub Labels). /pm only applies existing labels, never creates new ones. If a feature would benefit from a new label, propose it in the discuss section but tell the user to chore(labels): add <name> separately.

Repo identity (stable facts)

• Owner / repo: davidting0918/PetCare (master is the default branch, develop exists for staging)
• Issue tracker: GitHub issues, accessed via gh issue ...
• Labels: 21 custom labels grouped into type:* (6) / area:* (5) / domain:* (8) / test:* (2). Source: .claude/labels.yaml. Skill flow described in CLAUDE.md > GitHub Labels. /pm applies them but never edits the YAML.
• Domains (1:1 with /bte's domain argument): auth, user, group, pet, food, meal, weight, plus medicine (planned, not yet implemented).

Issue body format (NON-NEGOTIABLE)

Every issue /pm plan creates uses this exact three-section structure. Missing sections = invalid. Empty section = use the literal string _(none)_ so the structure is preserved.

## Background

- **Problem**: <one paragraph — what user-visible or developer-visible pain motivates this issue>
- **Why now**: <what triggered it — user feedback, follow-up from #N, refactor unblocker, dependency for #M, or "scoped from /pm plan on YYYY-MM-DD">
- **Out of scope**: <bullet list of things explicitly NOT in this issue, with brief reason>

## Tech Implementation Plan

- **Affected layer(s)**: <pick: backend / frontend / database / fullstack>
- **Files expected to change**: <bullet list with file paths if known; "TBD by /be" or "TBD by /fe" is acceptable for unknowns>
- **API contract** _(backend issues only — omit section for pure-frontend issues)_:
  - New / changed endpoints: `<METHOD> <path>` — request body shape, response shape, status codes, auth requirement, group-role requirement
  - Schema changes: `yes` / `no`. If yes, outline `CREATE TABLE` / `ALTER TABLE` / `CREATE INDEX` SQL inline.
- **Data flow** _(frontend issues only — omit section for pure-backend issues)_:
  - Backend endpoints consumed: list with `backend/routers/<file>.py:<line>` refs (cite from the planning step, not from imagination — if unknown, use "TBD, blocked by #N")
  - State changes: which Redux slice / async thunks / selectors are added or modified
  - Component tree: which components are added; reuse `Modal` / `DeleteConfirmDialog` / `useFormState` / `useFileUpload` if applicable
- **Dependencies**:
  - Blocks: `#N1, #N2` (downstream issues that need this one done first)
  - Blocked by: `#M1, #M2` (upstream issues that must finish before this one)

## Manual Verification Before Merge

- [ ] <step 1, e.g. "Run `curl -X POST localhost:8000/medication/create -d ...` and confirm `status: 1` in response">
- [ ] <step 2, e.g. "Run the migration SQL from the Tech Implementation Plan against staging and confirm the new column exists">
- [ ] <step 3, e.g. "Open dev server, log in, navigate to `/medication`, verify the new tab renders correctly at 375px viewport">
- [ ] <add as many as the issue scope warrants — these become the PR's manual test plan>

Side-effect rules

• External writes: gh issue create, gh issue edit, gh api repos/.../milestones, gh issue comment. Nothing else.
• Always propose before applying: /pm never creates issues / milestones without the user confirming the proposal in their next message. This mirrors /summary's confirmation policy because GitHub mutations are user-visible and hard to undo cleanly.
• Failure modes:
  • gh auth / network failure → report verbatim and stop, do not retry silently.
  • Milestone with the same name already exists → ask the user whether to reuse it or pick a new name.
  • Issue creation fails partway through a batch → report which issues were created vs. which failed; do not roll back successful creations (the user can close them manually if they want to start over).
• No commit, no push, no branch creation, no PR opening — /pm lives entirely in the GitHub API surface plus the skill chain. It does not run any Dev Flow steps.

Subcommand: discuss

Invoked as /pm discuss <topic> (e.g. /pm discuss "should medication tracking be a per-pet schedule or per-medication schedule?", /pm discuss "what does v1 of meal sharing across families look like?").

This is open Q&A about product, project, or scope decisions. Topics can be:

• New feature ideation ("should we add medication tracking?")
• Scoping a known feature ("what's the smallest meaningful version of meal photos?")
• Cross-cutting product decisions ("how should we handle units — metric only, imperial only, both?")
• Project-level questions ("which feature should ship next given current state?")
• Roadmap conversations ("what does the post-medication backlog look like?")

/pm discuss is two-stage. Stage 1 converges direction quickly using the same five-section structure as /be discuss / /fe discuss. Stage 2 expands the chosen direction in depth (only after the user picks one). The user can stop at the end of stage 1 if direction is already clear.

Stage 1 — Converge (always runs first)

Ground the discussion in real code / state. If the topic mentions an existing feature, read the relevant backend/services/<x>_service.py / frontend/src/components/<x>/ / database/db_schema.sql before responding so your proposals reference real file:line.

Reply in Traditional Chinese with exactly these five sections, in this order:

1. 問題理解與範圍確認

Restate what you think the user is asking in 1-3 sentences. Explicitly list what is in scope and what is out of scope for this discussion. If unsure, ask for clarification before continuing.

2. 三個可行方案（含優缺點）

Always produce three proposals, ordered from "smallest viable change" to "most ambitious". For each:

• 方案 X：<short name>
• 使用者價值：what does the user actually get / feel / be able to do?
• 做法（高層）：concrete-but-not-detailed approach — file paths, endpoints, schema changes, UI surface. Save the full spec for stage 2.
• 優點 / 缺點：bullet lists
• 影響範圍：which layers / domains / files are touched
• 複雜度：低 / 中 / 高
• 預估 issue 數：how many issues /pm plan would create for this proposal (rough integer)

If you genuinely cannot think of three, say so explicitly and explain why, then provide as many as you can.

3. 我的疑慮與建議

• 疑慮：things to worry about regardless of which proposal is chosen — data integrity, mobile UX, authorization, performance, migration risk, hidden coupling, scope creep.
• 建議：which of the three you would pick and why, in 2-4 sentences. Be opinionated.

4. 等使用者拍板的決定

Numbered list of explicit yes/no or pick-one questions the user must answer before stage 2 or /pm plan can start. Each question answerable in one sentence.

5. 如果這題收掉之後，還可以延伸做的事

Forward-looking list of related improvements / follow-ups that would naturally come after this is resolved. Each item one line. Not a commitment.

Stage 1 → end of reply

End every stage-1 reply with exactly this prompt block (no variations):

---

下一步：
- 回 `1` / `2` / `3` 選一個方案進入 stage 2 深度展開
- 回 `plan 1` / `plan 2` / `plan 3` 直接進 `/pm plan`（跳過 stage 2，方向已清楚）
- 回 `more` 提出新疑問繼續 stage 1
- 回 `stop` 結束討論，不採取任何後續動作

Do not proceed without an explicit user reply.

Stage 2 — Deep dive (only after the user picks a proposal)

Triggered by a user reply of 1 / 2 / 3 (without plan prefix). Do not auto-trigger this — it must be requested.

Stage 2 expands the chosen proposal into a near-spec-level document. Keep responding in Traditional Chinese. Structure:

A. 選定方案的完整 spec

• 使用者故事：1-3 user stories in the format "As a <role>, I want to <action>, so that <outcome>"
• 功能範圍：bullet list of every user-visible capability, grouped by user flow
• 資料模型：tables / columns / FKs / indexes the feature needs. Reference the existing database/db_schema.sql style — short varchar ids, is_active, created_at, updated_at, update_updated_at_column() trigger.
• API surface：full list of endpoints with METHOD path (GET / POST only — match the project rule), request body, response shape, status codes, auth requirement, group-role requirement
• Frontend surface：new routes, new Redux slice if any, new components, where they slot into MainLayout / BottomNavigation, mobile-first considerations
• Authorization 模型：how does this interact with the creator / member / viewer group roles? Any new permission checks?

B. 使用者旅程

Walk through 1-2 concrete user flows step-by-step (tap-by-tap on mobile), so the user can spot UX gaps.

C. 技術風險與選擇

• 已知的技術風險：things that could go wrong during implementation (cascade behaviour, query performance, race conditions, edge cases the spec doesn't cover)
• 重要的技術選擇：decisions inside the spec that have multiple valid implementations — for each, list 2-3 options + your recommendation

D. 拆分草案（preview only — not yet creating issues）

A rough preview of how /pm plan would split this into issues:

- #? Backend: <domain> service + endpoints + schema (area:backend, domain:<domain>)
  Blocks: #? frontend
- #? Frontend: <resource> UI + state (area:frontend, domain:<domain>)
  Blocked by: #? backend
- #? (etc.)

This is a preview — /pm plan will produce the real version. The point is to give the user a sense of size before they commit.

E. 等使用者拍板才會進 /pm plan

Numbered list of remaining open questions that must be resolved before issues can be created. Each one is a <question> → A / B / C choice.

End the stage-2 reply with exactly this prompt block:

---

下一步：
- 回 `plan` 進入 `/pm plan`（用上面拍板的答案建 issue）
- 回 `revise` 修改 spec（你會說要改哪裡）
- 回 `back` 回到 stage 1 重新比方案
- 回 `stop` 結束討論

discuss mode hard rules

• Never create issues / milestones during discuss. Even if the user types something that sounds like authorization, the only way to create issues is to enter /pm plan explicitly via the prompt block.
• Never invoke /be / /fe / /bte during discuss. Those are downstream of /pm plan.
• Never modify code, schema, or docs during discuss. Reading is fine.
• End every reply with one of the two prompt blocks above. No exceptions. The user always knows what their next options are.

Subcommand: plan

Invoked as /pm plan <feature description> or /pm plan (continuing from a /pm discuss conversation in the same session).

Step 0 — Resolve the input

• If the user typed a feature description after plan, use that as the spec source.
• If plan was used with no arguments, look back in the conversation for the most recent /pm discuss stage-2 spec the user approved (plan reply to a stage-2 prompt). Use that as the spec source.
• If neither is available, reply: "請提供 feature 描述，或先用 /pm discuss <topic> 走完 stage 2 再回來。" and stop.

Step 1 — Read the current state

Run these read-only commands one at a time:

gh issue list --state open --limit 30 --json number,title,labels,milestone
gh api repos/{owner}/{repo}/milestones --jq '.[] | {number, title, state, open_issues, closed_issues}'

Quickly summarise the current open work in 2-3 lines so the new plan doesn't collide with in-progress issues. If a similar open issue / milestone already exists, flag it before proposing anything new and ask whether to reuse / merge.

Step 2 — Propose the breakdown

Reply in Traditional Chinese with this structure. Do not call gh issue create yet.

A. Feature 摘要（1 段）

One paragraph restating the feature in the user's words, plus the absolute-date this plan was made (e.g. "Planned 2026-04-08").

B. 拆分原則 confirmation

Restate the breakdown rule so the user can sanity-check before the proposal grows long:

拆分採 domain 邊界：每個 backend domain 一個 issue（label area:backend + domain:<x>）、每個 frontend resource 一個 issue（label area:frontend + domain:<x>）、若有 schema 變更則獨立一個 schema issue 排在最前面（label area:database + 對應 area:backend + domain:<x>）。

C. Milestone 提議

Decide whether a milestone is needed:

• Issue count ≥ 3 → propose a milestone. Suggest a name in the form <feature name> (no prefix, no M{N}, no v1). Never set a due date (matches the project's "no time estimates" rule).
• Issue count < 3 → no milestone. Say "issue 數 < 3，不建立 milestone，issue 直接掛 repo 根目錄。"
• User explicitly asked for a milestone in /pm discuss → respect that, regardless of count.

D. Issue 列表（per-issue preview）

For each proposed issue, show the full body in the issue-body format above, plus:

• Index: Issue 1 of N (counting only the proposed issues, no real GitHub number yet)
• Title (English): <verb> <object> style, e.g. Add medication tracking backend (not Backend for medication)
• Labels: full list of labels you'll apply (type:* + area:* + domain:*). At minimum one type:* and one area:* per CLAUDE.md > GitHub Labels. For /pm plan features the type is almost always type:feat; use type:fix only if the user described a bug.
• Dispatch target: which skill will run this issue once created — /be, /fe, or /bte (rare for /pm plan output, but possible if it's a test-only issue).
• Body: full markdown body per the format above, with Blocks: #? / Blocked by: #? placeholders that will be filled in once GitHub assigns real numbers.

After the per-issue list, show a dependency graph in plain text:

schema/medicine ──┐
                  ├──→ backend/medicine ──→ frontend/medicine
                  │
(none)            ┘

Plus a suggested execution order (for Step 5 dispatch):

1. #? schema/medicine     (/be)
2. #? backend/medicine    (/be)
3. #? frontend/medicine   (/fe)

E. 等使用者拍板

Three numbered confirmation points + a final prompt block:

請逐項確認：
1. Milestone：<name> (或 "no milestone")  →  yes / no / rename to X
2. Issue 標題與拆分：上述 N 個 issue  →  yes / no / 修改第 X 個
3. Labels：每個 issue 標的 labels      →  yes / no / 改 issue X 的 labels

---

回 `apply` 套用上述全部、`apply with changes <what>` 套用並修改、或 `cancel` 取消。

Wait for explicit apply (or apply with changes ...) reply before proceeding. Do not interpret silence or vague approval as authorization.

Step 3 — Create on GitHub (only after apply)

Order of operations matters because GitHub assigns numbers as it goes:

1. Create milestone first (if proposed):

   gh api repos/{owner}/{repo}/milestones \
     -f title="<name>" \
     -f description="<one-line description from Step 2A>" \
     -f state="open"
   

   Capture the returned milestone number.

2. Create issues in dependency order (parents before children) so cross-issue links are forward-only:

   gh issue create \
     --title "<title>" \
     --body "<body with placeholders still in it>" \
     --label "type:feat" --label "area:backend" --label "domain:medicine" \
     --milestone "<name>"
   

   Capture each returned issue URL → extract the issue number.

3. Patch dependency placeholders — once all real numbers are known, edit each issue's body to replace Blocks: #? and Blocked by: #? with real numbers:

   gh issue edit <N> --body "<updated body>"
   

4. If anything fails partway through, stop and report which issues were created and which were not. Do not auto-close successful ones — the user decides whether to keep them or close manually.

Step 4 — Hand off to the user for review

Reply in Traditional Chinese with:

• Milestone URL (if created): https://github.com/davidting0918/PetCare/milestone/<N>
• Issue list: each as #N — <title> — <URL> — labels: ...
• Execution order (the same one from Step 2D, now with real numbers)
• Manual review prompt:

  ---
  
  請到 GitHub 確認 issue 內容、labels、milestone 都正確。準備好之後回：
  - `dispatch all`：依依賴順序自動執行所有 issue（會逐一呼叫 /be / /fe / /bte）
  - `dispatch first`：只執行第一個 issue
  - `dispatch <N1>,<N2>,...`：執行指定的 issue（必須是依賴順序中的連續前綴）
  - `hold`：先不執行，我之後手動跑 /be / /fe
  

Step 5 — Dispatch to /be / /fe / /bte (only after dispatch ...)

Based on the user's dispatch reply, invoke the target skills via the Skill tool in the execution order from Step 2D, one at a time, sequentially. Do not parallelise — each skill creates a branch off origin/master, and sequential runs guarantee that downstream issues see upstream work merged into master before they start.

For each issue:

1. Tell the user which one is starting: 「現在執行 #N (<title>)，呼叫 /be ...」 (or /fe, /bte).
2. Invoke the Skill tool: Skill(skill="be", args="<N>") / Skill(skill="fe", args="<N>") / Skill(skill="bte", args="unit <domain>").
3. Wait for the skill's final report (PR URL, branch, blockers).
4. If the skill stopped at its confirmation gate (e.g. /be paused because the plan touches db_schema.sql) → forward the question to the user, wait for the user's answer, then re-invoke the skill with the answer.
5. If the skill aborted (quality gate failed twice, PR collision, contract mismatch) → stop the entire dispatch chain and report. Do not proceed to the next issue automatically.
6. If the skill succeeded → record the PR URL, then move to the next issue in the order.

Hard pause between issues: after each PR is opened, before starting the next issue, ask the user:

#N (<title>) 完成 → <PR URL>

要繼續下一個 (#N+1 <title>) 嗎？
- 回 `next` 繼續
- 回 `pause` 暫停 dispatch（之後可手動跑剩下的）
- 回 `stop` 結束 dispatch（剩下的 issue 留在 GitHub 等以後）

This gives the user a checkpoint to manually review the just-opened PR before downstream work starts. Important because downstream /fe reads the just-merged backend contract and a buggy upstream PR would cascade.

Step 6 — Final report

After dispatch ends (whether by completion, pause, or stop), reply in Traditional Chinese with:

• Milestone: name + URL + open / closed issue count
• Issues created in this /pm plan run: full list with #N — title — PR URL (or "未執行")
• Issues remaining: any issues from the plan that were not dispatched, with their #N and a one-line reminder how to run them later (/be 12 / /fe 13)
• Switch back hint: git switch master (since dispatch may have left the user on the last skill's branch)

Usage block (show this when arguments are invalid)

/pm 用法：

  /pm discuss <topic>             兩階段討論：先 5 段式收斂（與 /be discuss
                                  同結構），使用者選定方案後進入 stage 2
                                  深度展開 spec。每次回覆都會問下一步。

  /pm plan <feature description>  把 feature 拆成 GitHub issue + milestone：
                                  按 domain 邊界拆分，三段式 issue body
                                  (Background / Tech Plan / Manual Verify)，
                                  自動標 labels (type:* + area:* + domain:*)，
                                  使用者確認後建到 GitHub，再依依賴順序
                                  逐一呼叫 /be / /fe / /bte 執行。

  /pm plan                        不帶參數時，沿用本 session 中最近一次
                                  /pm discuss stage 2 拍板的 spec。

範例：
  /pm discuss "should medication tracking be a per-pet schedule or per-medication schedule?"
  /pm plan "add medication tracking, per-pet schedule, with reminders"
  /pm plan        # 接續上面 discuss 的決定

note：
  - /pm 永遠不會直接動 code、schema、commit、push、開 PR — 那是 /be / /fe 的事
  - /pm 永遠在動外部副作用（建 issue、建 milestone、dispatch /be /fe）前
    propose 完整內容並等使用者明確 apply / dispatch
  - issue body 一律英文（為了搜尋與引用），對話一律繁中