desktop-team-doc 0.1.0

package/content/docs/instructions/workflows/git-branch-convention.md

@@ -0,0 +1,246 @@
+# Desktop Team Git Branch Convention
+
+*Last Updated: 2025-10-16*
+
+This document defines the Git branching strategy and naming conventions for Desktop Team repositories, based on Git Flow methodology.
+
+## Branch 分支命名方式與用途
+
+### 主要區別與分類
+
+|  | master | dev | feature | release | hotfix |
+| --- | --- | --- | --- | --- | --- |
+| branch off from | n/a | n/a | develop | develop | master |
+| merge into | n/a | n/a | develop | develop<br />master | develop<br />master |
+| creator | maintainer | maintainer | `developer`<br />(主要都是這個) | maintainer | maintainer |
+| duration | infinity | infinity | short | extremely short | short |
+| characteristic | production-ready state | - next release features ready<br />- nightly build | next release features developing | - release meta-data update<br />- minor bug fix | product emergency only |
+
+---
+
+## `master` Branch
+
+### 特性
+
+- 總是在 **production-ready** 的狀態
+- 總是 tag release number
+- Only maintainers can merge into this branch
+
+---
+
+## `dev` Branch
+
+### 特性
+
+- 總是在下一個 release 最新的開發狀態
+- 當所有 feature 實作告一個段落，準備要 release，則開 `release` branch 最後 merge 回 `master` 和 `dev`
+- Used for nightly builds and demo builds
+
+---
+
+## `feature` / `refactor` / `bugfix` / `poc` / `chore` / `test` Branches
+
+**Branch off from**: `dev`
+
+**Merge into**: `dev`
+
+### Branch Types
+
+- **`feature`**: Develop new features or enhance/modify existing ones
+- **`refactor`**: Code refactoring without changing behavior
+- **`chore`**: Non-coding changes like scripts, metadata, file restructuring, or submodule updates
+- **`bugfix`**: Fix bugs or errors, usually linked to a ticket
+- **`poc`**: Proof-of-concept implementation, typically linked to a PoC ticket
+- **`test`**: For testing purposes
+
+### 使用時機
+
+- **下一個 release 的 feature**
+- 不是下一個 release 的 feature/refactor/bugfix 也可以開，但是先不要 merge 回 `dev`
+- 實驗、測試、重構、架構調整
+
+### Naming Convention
+
+```bash
+## 常用格式
+feature/{jira_number}-{feature_title}
+refactor/{jira_number}-{feature_title}
+bugfix/{jira_number}-{feature_title}
+
+## 可使用逗號分隔多張 ticket
+feature/BO-500,512,3,55-title
+feature/BO-230,543,32,23-title
+refactor/BO-445,454,32,23-title
+refactor/BO-507,508,321,223-title
+
+## 常用範例
+feature/BFD-123-new-guitar-engine
+refactor/BFD-456-optimize-audio-buffer
+bugfix/BFD-789-fix-preset-loading
+
+## 其他類型
+poc/grpc-client
+test/cab-stereo-out
+chore/system-log
+```
+
+### Demo Branch 注意事項
+
+> **關於 for demo 的 branch?**
+>
+> 原本想設計 `feature/demo-release-2.5.2` 這樣的 branch off
+> 但是基於 git flow 的流程，建議直接從 dev 做 nightly build 或 demo build 即可
+
+---
+
+## `release` Branch
+
+**Branch off from**: `develop`
+
+**Merge into**: `develop` `master`
+
+### 使用時機
+
+- Release 狀態已經準備好 (i.e., feature 都已完成)，即可 branch off
+
+> 💡 **此 branch 會存在到直到 release 出去**
+
+- 最終小修改、小 bug 修復或程式碼細節調整
+  - 小 bug fix 可在此 branch，反而不是在 develop branch
+  - **不可在此 branch 實作大 feature**
+- 加入 release 資訊 (meta-data: version number, build dates 等等)
+
+### Naming Convention
+
+```bash
+release/{version_number}
+
+## 範例
+release/2.5.0
+release/3.0.1
+```
+
+---
+
+## `hotfix` Branch
+
+**Branch off from**: `master`
+
+**Merge into**: `develop` `master`
+
+### 使用時機
+
+- 不在計劃內的 release
+- 緊急修復 production 環境的重大問題
+
+### Naming Convention
+
+```bash
+hotfix/{version_number}
+
+## 範例
+hotfix/2.5.1
+hotfix/3.0.2
+```
+
+### 特殊情況
+
+如果當前有一個 **release branch** 開著：
+
+- 若遇到 release 前有一個重大問題要馬上修復，必須搶先在 release branch 前發布
+- Hotfix branch 要 merge 進 **release branch** (不是 develop branch)
+- 若 develop 很需要這個 bugfix，也可以直接 merge 進 develop，不必等 merge 過 bugfix 的 release branch merge 回來
+
+---
+
+## Branch Lifecycle Summary
+
+### Typical Feature Development Flow
+
+```
+1. Create feature branch from dev
+   git checkout dev
+   git checkout -b feature/BFD-123-new-feature
+
+2. Develop and commit changes
+   git add .
+   git commit -m "impl BFD-123: add new feature"
+
+3. Push to remote
+   git push -u origin feature/BFD-123-new-feature
+
+4. Create pull request to dev
+5. After approval, merge into dev
+6. Delete feature branch
+```
+
+### Release Flow
+
+```
+1. Create release branch from dev
+   git checkout dev
+   git checkout -b release/2.5.0
+
+2. Update version metadata and fix minor bugs
+3. Merge into master
+4. Tag release on master
+   git tag -a v2.5.0 -m "Release 2.5.0"
+
+5. Merge back into dev
+6. Delete release branch
+```
+
+### Hotfix Flow
+
+```
+1. Create hotfix branch from master
+   git checkout master
+   git checkout -b hotfix/2.5.1
+
+2. Fix critical bug
+3. Merge into master
+4. Tag hotfix release
+   git tag -a v2.5.1 -m "Hotfix 2.5.1"
+
+5. Merge into dev (or release branch if exists)
+6. Delete hotfix branch
+```
+
+---
+
+## Best Practices
+
+1. **Always branch from the correct source**
+   - Features: from `dev`
+   - Releases: from `dev`
+   - Hotfixes: from `master`
+
+2. **Use descriptive branch names**
+   - Include JIRA ticket number when applicable
+   - Use kebab-case for titles
+   - Be concise but clear
+
+3. **Keep branches short-lived**
+   - Feature branches should be merged within 1-2 sprints
+   - Avoid long-running feature branches
+
+4. **Delete merged branches**
+   - Clean up branches after they're merged
+   - Keeps repository organized
+
+5. **Never commit directly to master or dev**
+   - Always use pull requests
+   - Ensure code review process
+
+---
+
+## Related Documentation
+
+- [Git Commit Convention](./git-commit.md) - Commit message format and standards
+- [Code Review Process](./code-review.md) - Review workflow for pull requests
+- [JIRA Workflow](./jira-process.md) - Linking branches to JIRA tickets
+
+---
+
+**Maintained by**: Desktop Team
+**Based on**: [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) by Vincent Driessen

package/content/docs/instructions/workflows/git-commit.md

@@ -0,0 +1,95 @@
+# Git Commit Message Convention
+
+This document outlines the standard format for git commit messages to be used by the Desktop Team. Following these conventions ensures consistency and clarity in our version control history.
+
+## Commit Message Structure
+
+```
+<header>
+
+<body>
+
+<footer>
+```
+
+Where:
+
+- **Header**: Must be a single line, limited to 80 characters
+- **Body**: Optional, provides detailed description of the commit
+- **Footer**: Optional, references related issues
+
+## Header Format
+
+```
+<type> BFD-<issue-number>: <subject>
+```
+
+### Type Options
+
+- **impl**: Implementation of a task (most common type)
+- **fix**: Bug fix (can also be used for bugfix pull request titles)
+- **test**: Adding tests
+- **doc**: Documentation updates
+- **style**: Code formatting changes (no logic changes)
+- **chore**: Build process or auxiliary tool changes
+- **refactor**: Code refactoring (no new features or bug fixes)
+- **remove**: Removal of legacy or unnecessary code
+
+## Examples
+
+### Complete Example
+
+```
+impl BFD-123: lock and disable amp room while connecting to device
+
+For some reasons:
+- this is special case for device connected
+- second reason is xxxx
+- bla bla bla
+
+ref: #3456 #4488
+```
+
+### Project-Specific Examples
+
+```
+impl BO-45: adaptive ui scaling native command
+fix BFD-56: ir loader naming issue
+```
+
+## Guidelines
+
+1. The header should be concise but descriptive
+2. Always include the issue number from the tracking system
+3. Use the appropriate type prefix to indicate the nature of the change
+4. The body should explain the "why" behind the changes when necessary
+5. Reference related issues in the footer with "ref: #issue-number"
+
+Following these conventions helps with:
+
+- Automated changelog generation
+- Filtering commits by type
+- Providing immediate context for code changes
+- Maintaining a clean and useful git history
+
+## Automation with Roo Code
+
+When working with Roo Code, you can use the prompt "git commit current change for me" to automatically:
+
+1. Stage all current changes (`git add .`)
+2. Generate a commit message following this convention
+3. Commit the changes with the generated message
+
+The assistant will:
+
+- Ask for the issue number (e.g., BFD-123)
+- Determine the appropriate type based on the changes
+- Generate a concise subject line describing the changes
+- Optionally add a body with more details if needed
+- Create a properly formatted commit message
+- Execute the git commit command
+
+### Example Interaction
+
+```
+User: git commit current change for me

package/content/docs/instructions/workflows/jira-process.md

@@ -0,0 +1,173 @@
+# Jira Ticket Branch & Solution Planner
+
+## Trigger
+
+This rule is triggered when a developer provides a Jira ticket URL under the following conditions:
+
+1.  Current mode is "Code" or "Architect".
+    AND
+2.  Jira ticket URL is new or re-introduced with work intent.
+    AND
+3.  One of:
+    a. URL at session start in these modes.
+    b. URL with intent phrases (e.g., "implement", "start work on BIASONE-XXXX").
+    c. URL in response to "what task?"
+
+## Action
+
+Process:
+
+1.  **Acknowledge & Confirm Intent:**
+    a. Agent: "Jira ticket: [URL] in [Code/Architect] mode. Should I start implementing it?"
+    b. If 'yes'/start work: Proceed to step 2.
+    c. If 'no'/info only: Offer MCP fetch for ticket details (no branch creation). Workflow ends.
+
+2.  **Fetch Jira Details & Initial Info:**
+    a. Extract `[jira_number]` from URL (e.g., "BIASONE-1328").
+    b. Agent: "Ticket: `[jira_number]`."
+    c. If Jira MCP available:
+        - Agent: "Fetching details (summary, description, comments, type, status) from Jira for planning."
+        - Use Jira MCP for full info. Store details.
+        - Agent: "Details fetched."
+    d. **Verify Jira Ticket Status (if fetched via MCP) & Offer Transition:**
+        i.  If Jira MCP was used to fetch details:
+            1. If `[current_status]` is "DONE", "RESOLVED", "WILL NOT BE FIXED", "CLOSED":
+                - Agent: "Ticket `[jira_number]` is `[current_status]`. Proceed anyway?"
+                - If 'no': Workflow ends.
+            2. Else if `[current_status]` is NOT "IN PROGRESS" (e.g., "TO DO"):
+                - Agent: "Ticket `[jira_number]` is `[current_status]`. Move to 'In Progress'?"
+                - If 'yes' & MCP available: Attempt `jira_transition_issue`. Report outcome.
+                - If 'yes' & MCP unavailable: Agent: "Please update status in Jira manually."
+    e. If Jira MCP NOT available/fails (or user opted out of MCP fetch):
+        - Agent: "Cannot access Jira / Manual mode. Provide ticket title/summary, description, recent comments, issue type (Bug, Story, Task)? (Assuming status is appropriate for work)."
+        - Store user-provided details.
+    f. If user provided details preemptively or prefers manual: Use available/solicit per 2.e. (Status assumed appropriate).
+    g. Determine branch `[type]` from issue type (Bug → bugfix, Story/Feature → feature, Task → chore, Tech Task → refactor).
+    h. If issue type unclear: Agent: "Issue type for branch? ('bugfix', 'feature', 'chore', 'refactor')." Use response for `[type]`.
+
+3.  **Determine Target Repositories & Scope:**
+    a. Deduce `[deduced_target_scope]` from Jira details (summary, description, labels like 'frontend', 'native').
+        - Logic: "UI"/"Frontend" → "frontend". "DSP"/"C++" → "native". Both → "both". Submodule names → those.
+    b. Agent: "Ticket suggests changes affect `[deduced_target_scope_description]` (e.g., 'frontend UI', 'native DSP', 'both', 'DSP_Lib submodule'). Correct? Or specify:
+        1. Native (BIAS_ONE)
+        2. Frontend/UI (BIAS_ONE_GUI)
+        3. Both
+        4. Other submodule(s) (name?)"
+    c. Identify final `[target_scope]` from user response.
+    d. Determine `[repository_contexts]` (list of `name` and `local_path`):
+        - "native": `[{name: "BIAS_ONE", path: "[path_to_BIAS_ONE]"}]`
+        - "frontend": `[{name: "BIAS_ONE_GUI", path: "[path_to_BIAS_ONE_GUI]"}]`
+        - "both": `[{name: "BIAS_ONE", path: "[path_to_BIAS_ONE]"}, {name: "BIAS_ONE_GUI", path: "[path_to_BIAS_ONE_GUI]"}]`
+        - "other_submodule(s)": Entries for each, e.g., `[{name: "DSP_Lib", path: "[path_to_DSP_Lib]"}]`.
+        (Note: Obtain/confirm local paths via pre-config or user query for `execute_command` `cwd`.)
+    e. Agent: "For `[comma_separated_list_of_repo_names_from_contexts]`: checking existing branches, then creating new if needed."
+    f. Perform steps 4 & 5 for each `[repo_context]`. Indicate current repository.
+
+4.  **For each `[repo_context]` (Prepare Repository & Check Existing/Propose New Branch):**
+    a. **Check Git Status & Stash if Needed:**
+        i. Agent: "`[repo_context.name]`: Checking git status."
+        ii. `git status` (in `[repo_context.path]`).
+        iii. If there are uncommitted changes:
+            - Agent: "Found uncommitted changes. Stashing them to preserve your work."
+            - `git stash -u` (to include untracked files).
+            - Store stash reference for later restoration.
+        iv. Note current branch for potential restoration at end of session.
+    
+    b. **Checkout and Update Target Branch:**
+        i. Determine target branch (default: "dev", unless user specifies otherwise).
+        ii. Agent: "Switching to `[target_branch]` and pulling latest changes."
+        iii. `git checkout [target_branch]` (in `[repo_context.path]`).
+        iv. `git pull` to ensure target branch is up to date.
+        v. If pull fails: Report issue and ask user how to proceed.
+    
+    c. Agent: "`[repo_context.name]` (at `[repo_context.path]`): Checking for existing local branch for `[jira_number]`."
+    d. `git branch --list '*[jira_number]*'` (in `[repo_context.path]`).
+    e. If matching local branches found:
+        i.  Agent: "`[repo_context.name]`: Found existing local branch(es): `[list_of_branches]`. Use one (I'll switch), or create new?"
+        ii. If user chooses `[chosen_branch]`:
+            - Agent: "`[repo_context.name]`: Switching to `[chosen_branch]`."
+            - `git checkout [chosen_branch]` (in `[repo_context.path]`).
+            - Agent: "Switched to `[chosen_branch]` in `[repo_context.name]`."
+            - Mark `[repo_context]` 'branch_selected'.
+            - If last `[repo_context]`, proceed to Step 6. Else, next `[repo_context]`.
+        iii.If user wants new branch despite existing, or none found: Continue to 4f.
+    f. If no existing branch used for `[repo_context.name]`:
+        i.  Derive `[feature_title]` from ticket summary (kebab-case, once globally).
+            `// Example: "[GA / UI] Support User Event" -> "ga-ui-support-user-event"`
+        ii. `[branch_name_proposal] = [type]/[jira_number]-[feature_title]` (generic for all repos).
+        iii.Confidence Check & Confirm for `[repo_context.name]`:
+            - If low-confidence `[feature_title]` (short/generic summary):
+                Agent: "`[repo_context.name]`: Proposed branch `[branch_name_proposal]`. OK, or suggest different title part for this repo?"
+            - Else (high confidence):
+                Agent: "`[repo_context.name]`: Propose branch `[branch_name_proposal]`. Create in this repo?"
+        iv. If user confirms (or modifies `[feature_title]` for this repo):
+            - Store `[confirmed_branch_name_for_repo_context]`.
+            - Proceed to Step 5 for this `[repo_context]`.
+        v.  If user modifies `[type]` or `[feature_title]` (clarify if `[feature_title]` change is global or per-repo):
+            - Agent: "`[repo_context.name]` (and others?): Preferred `[type]` and `[title_part]`?"
+            - Update `[type]` / `[feature_title]`. Recalculate `[branch_name_proposal]`.
+            - Agent: "New proposal: `[branch_name_proposal]`. Create in `[repo_context.name]`?"
+            - If confirmed, store and proceed to Step 5.
+        vi. If user declines branch creation for `[repo_context.name]`:
+            - Agent: "OK, no branch in `[repo_context.name]` for now."
+            - Mark `[repo_context]` 'branch_creation_declined'.
+            - If last `[repo_context]` & no branches handled: Conclude or offer solution planning without branches. If some handled, Step 6. Else, next `[repo_context]`.
+
+5.  **For each `[repo_context]` (Create Branch, if confirmed):**
+    a. Agent: "`[repo_context.name]`: Creating `[confirmed_branch_name_for_repo_context]`..."
+    b. `git checkout -b [confirmed_branch_name_for_repo_context]` (in `[repo_context.path]`).
+    c. Agent: "Branch `[confirmed_branch_name_for_repo_context]` created & active in `[repo_context.name]`."
+    d. Mark `[repo_context]` 'branch_created'.
+    e. If last `[repo_context]` needing creation & all processed: Step 6. Else, loop for Step 4/5 continues.
+
+6.  **Gather Knowledge Base Info (For each `[repo_context]` with active branch):**
+    a. Agent: "Checking for knowledge base files (`.knowledge/index.md` per [Knowledge Base Management](../knowledge-base-management.md)) in repos with new/selected branches."
+    b. For each `[repo_context]` with active ticket branch:
+        i. Agent: "Checking knowledge base in `[repo_context.name]` (`[repo_context.path]`)."
+        ii. `list_files` in `[repo_context.path]` (non-recursive) for `.knowledge/index.md`.
+        iii.If found:
+            - Agent: "`[repo_context.name]`: Found `[list_of_found_items]`. Reading for solution plan."
+            - `read_file` for each. Store/summarize as `[knowledge_base_info_for_repo_context]`.
+        iv. Else:
+            - Agent: "`[repo_context.name]`: No standard knowledge base files found. Proceeding with ticket/code."
+    c. Agent: "Knowledge base review complete."
+
+7.  **Plan Solution (after all repo branches & knowledge bases handled):**
+    a. Agent: "Ticket details, branch(es), and knowledge base info gathered. Let's plan solution."
+    b. Plan solution using ticket requirements (Step 2) & `[knowledge_base_info_for_repo_context]` for all relevant repos.
+    c. Present plan to user for review and confirmation.
+
+8.  **Implement Solution:**
+    a. Upon user confirmation of the solution plan:
+        i. Agent: "Plan confirmed. I will now proceed with the implementation."
+        ii. (Agent executes the planned implementation steps. This phase involves actual coding, configuration changes, etc., based on the agreed plan.)
+        iii. Agent: "Implementation based on the plan is complete."
+
+9.  **Post-Implementation Knowledge Base Update:**
+    a. Agent: "Now that the implementation is complete, I will check if the Knowledge Base needs to be updated to reflect the changes made, as per [`./dev-guidelines/knowledge-base.md#54-end-of-task-review`](./dev-guidelines/knowledge-base.md#5.4.-End-of-Task-Review)."
+    b. If a KB exists in any `[repo_context]` where changes were made:
+        i. Agent reviews the changes and determines if KB updates are necessary.
+        ii. If updates are needed: Agent performs the KB updates.
+        iii. Agent: "Knowledge Base update check complete. [Details of any updates made, or 'No updates were necessary']."
+
+10. **Offer Pull Request Generation:**
+    a. Agent: "The implementation and KB updates (if any) are complete. Would you like me to generate a Pull Request for these changes? I will use the process outlined in [Pull Request Generation](./pull-request-generation.md)."
+    b. If user confirms 'yes': Initiate the PR generation workflow.
+    c. If user confirms 'no': Agent: "Okay, I will not generate a PR at this time. The task is complete."
+
+11. **Restore Stashed Changes (if applicable):**
+    a. If stash was created in Step 4a:
+        i. Agent: "Would you like me to restore your previously stashed changes?"
+        ii. If user confirms 'yes':
+            - `git stash pop` (in each `[repo_context.path]` where stash was created).
+            - Report any conflicts if they occur.
+        iii. If user confirms 'no': Agent: "Stashed changes preserved. You can restore them later with 'git stash pop'."
+
+## Agent Behavior Guidelines
+
+- In Code/Architect modes, for new Jira URL + work intent: **Always confirm before branch creation.**
+- Offer to fetch full Jira details (summary, desc, comments, type) early (Step 2) via MCP if available. Use for branch naming & solution planning. Allow manual provision if MCP unavailable/user prefers.
+- Before new branch (Step 4), check existing local branches for ticket (Step 3b). Offer to use if found/appropriate.
+- If creating new branch: Propose name. If low confidence (generic summary), ask user to confirm/modify. Else, state intent & ask for confirmation.
+- Accommodate user requests to skip detail fetching or provide manually.
+- If user declines branch creation, respect decision & conclude that part.

package/content/docs/instructions/workflows/jira-ticket-guide.md

@@ -0,0 +1,105 @@
+# Jira Ticket Template 與開票注意事項
+
+*Last Updated: 2025-10-16*
+
+## Reference
+
+[Jira Convention for BIAS](https://docs.google.com/presentation/d/1hPoDi6MaLyw89Op9p9x879R3KWFIAMK8kld9-cEpUS4/edit?usp=sharing)
+
+## 前言
+
+Ticket 撰寫主要心法：
+
+- 簡單、明確、項目夠小的任務；可被明確定義的任務與交付標準
+- 不摻雜多個工作項目在一張 ticket 內
+- 內容的精細度可設定成讓自己過兩三個月、或是忘了，回來看都可以看懂
+- Story 主 ticket 開出來後，若 RD 主要功能完成就可以把主 ticket 先收掉；demo meeting 或是開發過程中有「瑣碎的」、「未完成的」、「需要優化的」，可以另開 ticket 追蹤
+
+## Ticket 標題設計
+
+- 以中括號 `[]` 開頭，可填入 `UI`、`Native`、`DSP`，或其他特殊項目，並使用 ` / ` 分開（前後可以加空格，讓文字不要太擠）
+- 清楚描述要完成的 Story 或是遭遇到的 Bug
+- 因為 ticket 標題會直接被收錄在每一版的 Release Note，所以可以用如何在 Release Note 上清楚表達被完成的項目來思考標題的寫法
+
+### 標題範例
+
+```
+// Bug 範例
+[Native / DSP] 當讀取來自於 AI 功能的 Preset 為 Dual Path 格式其音量會異常大聲
+
+// Story 範例
+[UI] 優化 IO Slider，使其 +-12 dB 間可以透過 0.1dB 單位調整數值
+[UI / Native] 4 顆音箱整合（音箱新增: Supra Sonic, Crunchy Grid, Aggressive Grid, Tangerine AD）
+
+// Story/Developer 範例
+[Native / UI] Frontend 資源、Gear 清單、Preset 清單等 Resources 放到系統資料夾共用
+```
+
+Ticket 標題清楚的情況下，在 Release Note 看起來是這樣：
+
+![Release Note 範例](assets/jira-release-note.png)
+
+## 內容撰寫常見規則（必讀）
+
+- 請正確選擇 Ticket 類型，例如，Story、Bug、Developer，此時會出現 Template，請根據 Template 填入（不夠的項目可以再補上）
+- 如果 Story 有 UI 的或是如果 Bug 的 flow 較複雜，請附上 Figma 連結或是錄製截圖、影片以供參考
+- Story 請把需求條列清楚，有必要請加上截圖或影片輔助，甚至可以補上參考項目/競品
+- 內容如果跟自己領域不直接相關，需要請其他 team 協助，可以在 Slack 上先互相溝通，並把內容補齊再給 Scrum Master 確認
+- 需求若有明確 deadline 或開發時程，請一併附在描述內
+- 任何 ticket 不論是狀態改變或是內容修改，都請明確描述理由（請想成三個月後回來看，也看得懂的描述程度），例如把討論過程與結論附上，或是 tag 相關人士，並說明 ticket 狀態或是交付 action item
+- **請不要貼 Slack 對話連結**，如果真的很重要，請節錄對話內容，用引言方式放到回覆上或是描述上
+- 待確認問題請勿寫在描述上，請透過回覆或是引言，並 tag 相關人士回答
+
+### 描述範例
+
+描述寫清楚需求即可：
+
+![Ticket 描述範例](assets/jira-1.png)
+
+問題透過回覆並 tag 相關人士來詢問：
+
+![Tag 相關人士範例](assets/jira-tag.png)
+
+## Ticket 狀態
+
+### for Refinement
+
+- Ticket 一開出來會先是 `to be refined`，待完成 refine 後，可將狀態轉至 `refined`
+- `refined` 的 ticket，統一在 refinement meeting 討論，確認可以進開發則會轉成 `todo`
+
+### for Development
+
+- Ticket 一開始狀態會是 `todo`，開始開發後，可將狀態轉成 `in process`
+- 完成的 ticket 如果是在 run sprint 過程中的 ticket，可轉至 `done`；若不在 sprint 中的 ticket，例如，bug 或是 support ticket，可轉成 `to be verified`，將會自動轉給 QA 驗證
+
+### for QA
+
+- Ticket 一開始狀態會是 `to be verified`，待驗證後，會轉至 `verified`
+
+### for Tracking
+
+- Ticket 項目若 RD 無法被修正或是不支援，甚至是 PM 更改規格決定不做，可將 ticket 狀態設定成 `will not be fixed`
+
+## 回覆、留言、討論
+
+### 格式建議
+
+- 請寫清楚 action item 或 summary；若是提問請盡量條列，並 tag 需要協助釐清的對象，致使其回覆
+- 善用引言回覆（快捷鍵 Command + Shift + 9），將有問題的部分引言出來，再進行回覆
+
+### 引言回覆範例
+
+![引言回覆範例](assets/jira-comment.png)
+
+---
+
+## 相關資源
+
+- [Jira Process (自動化流程)](./jira-process.md) - Agent 自動處理 Jira ticket 的工作流程
+- [Git Commit Guidelines](./git-commit.md) - Git commit 訊息格式規範
+- [Code Review Process](./code-review.md) - Code review 流程與檢查清單
+
+---
+
+**Maintained by**: Desktop Team
+**Contact**: Scrum Master for Jira process questions