Back to Details

recover-branch-context

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Recover Branch Context

恢复分支上下文

You are tasked with understanding the intent and current state of an existing branch so you can resume or continue work effectively. The code state is your primary source of truth - it may have drifted from any associated Linear ticket.
你的任务是理解已有分支的开发意图和当前状态，以便高效地恢复或继续开发。代码状态是首要依据——它可能与关联的Linear工单内容存在偏差。

Initial Response

初始回复

When this command is invoked, respond with:
I'll help you understand the context of this branch. Let me analyze the commits and changes.

Do you have a Linear ticket ID or URL for this work? (optional - I can proceed without it)
Then wait briefly for the user's response. If they provide a ticket, fetch it. If they say no or don't respond quickly, proceed with the analysis.
当调用此命令时，请回复：
I'll help you understand the context of this branch. Let me analyze the commits and changes.

Do you have a Linear ticket ID or URL for this work? (optional - I can proceed without it)
然后短暂等待用户回复。如果用户提供了工单，获取其详情；如果用户回复不需要或未及时回复，则直接开始分析。

Process Steps

处理步骤

Step 1: Determine the Base Branch

步骤1：确定基准分支

  1. Check common base branch names:
    bash
    git branch -a | grep -E "(main|master|dev|develop)" | head -5
  2. Find the merge base:
    bash
    # Try dev first (common in this repo), then main/master
git merge-base HEAD dev 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD master
  3. Get current branch name:
    bash
    git branch --show-current
  1. 检查常见基准分支名称：
    bash
    git branch -a | grep -E "(main|master|dev|develop)" | head -5
  2. 找到合并基准：
    bash
    # Try dev first (common in this repo), then main/master
git merge-base HEAD dev 2>/dev/null || git merge-base HEAD main 2>/dev/null || git merge-base HEAD master
  3. 获取当前分支名称：
    bash
    git branch --show-current

Step 2: Gather Commit History Since Divergence

步骤2：收集分歧后的提交历史

  1. Get all commits since diverging from base:
    bash
    git log --oneline $(git merge-base HEAD dev)..HEAD
  2. Get detailed commit messages for understanding intent:
    bash
    git log --format="%h %s%n%b" $(git merge-base HEAD dev)..HEAD
  3. Get files changed across all commits:
    bash
    git diff --name-status $(git merge-base HEAD dev)..HEAD
  1. 获取自与基准分支分歧后的所有提交：
    bash
    git log --oneline $(git merge-base HEAD dev)..HEAD
  2. 获取详细提交信息以理解开发意图：
    bash
    git log --format="%h %s%n%b" $(git merge-base HEAD dev)..HEAD
  3. 获取所有提交中变更的文件：
    bash
    git diff --name-status $(git merge-base HEAD dev)..HEAD

Step 3: Gather Uncommitted Changes

步骤3：收集未提交的变更

  1. Get staged changes:
    bash
    git diff --name-status --cached
  2. Get unstaged changes:
    bash
    git diff --name-status
  3. Get untracked files:
    bash
    git ls-files --others --exclude-standard
  4. Full working tree status:
    bash
    git status --short
  1. 获取已暂存的变更：
    bash
    git diff --name-status --cached
  2. 获取未暂存的变更：
    bash
    git diff --name-status
  3. 获取未追踪的文件：
    bash
    git ls-files --others --exclude-standard
  4. 完整工作区状态：
    bash
    git status --short

Step 4: Fetch Linear Ticket (If Provided)

步骤4：获取Linear工单详情（若提供）

If the user provides a Linear ticket:
  1. Use the 
    mcp__linear__get_issue
    tool to fetch the ticket details
  2. Note: The ticket represents the original requirements but the code may have evolved
如果用户提供了Linear工单：
  1. 使用
    mcp__linear__get_issue
    工具获取工单详情
  2. 注意：工单代表原始需求，但代码可能已经迭代更新

Step 5: Analyze and Group Changes by Intent

步骤5：按开发意图分析并归类变更

CRITICAL: Do not just list files. Group them by logical feature area or intent.
  1. Read key changed files to understand what they do
  2. Identify patterns in the changes:
    • New feature additions
    • Bug fixes
    • Refactoring
    • Configuration changes
    • Test additions
  3. Group files by their purpose, not by directory
关键要求：不要仅罗列文件，需按逻辑功能区域或开发意图进行分组。
  1. 阅读关键变更文件以理解其作用
  2. 识别变更模式：
    • 新增功能
    • Bug修复
    • 代码重构
    • 配置变更
    • 测试用例新增
  3. 按用途分组文件，而非按目录结构

Step 6: Output Summary

步骤6：输出总结

Present findings in this structure:
markdown
undefined
按照以下结构呈现分析结果：
markdown
undefined

Branch Context: [branch-name]

Branch Context: [branch-name]

Base branch: [dev/main] Commits since divergence: [count] Linear ticket: [ID if provided, or "None provided"]
Base branch: [dev/main] Commits since divergence: [count] Linear ticket: [ID if provided, or "None provided"]

Intent Summary

Intent Summary

[1-3 sentences describing the overall goal of this branch based on commits and changes]
[1-3 sentences describing the overall goal of this branch based on commits and changes]

Feature Areas

Feature Areas

[Feature/Intent Area 1]

[Feature/Intent Area 1]

Purpose: [What this group of changes accomplishes] Status: [Complete/In Progress/Not Started]
Committed changes:
  • path/to/file.ext:lines
    - [brief description]
  • path/to/another.ext
    - [brief description]
Uncommitted changes:
  • path/to/wip.ext
    - [brief description]
Purpose: [What this group of changes accomplishes] Status: [Complete/In Progress/Not Started]
Committed changes:
  • path/to/file.ext:lines
    - [brief description]
  • path/to/another.ext
    - [brief description]
Uncommitted changes:
  • path/to/wip.ext
    - [brief description]

[Feature/Intent Area 2]

[Feature/Intent Area 2]

...
...

Uncommitted Work

Uncommitted Work

Staged (ready to commit):
  • [files]
Modified (not staged):
  • [files]
Untracked (new files):
  • [files]
Staged (ready to commit):
  • [files]
Modified (not staged):
  • [files]
Untracked (new files):
  • [files]

Code vs Ticket Drift

Code vs Ticket Drift

[If a Linear ticket was provided, note any discrepancies between what the ticket describes and what the code actually implements. The code is the source of truth.]
[If a Linear ticket was provided, note any discrepancies between what the ticket describes and what the code actually implements. The code is the source of truth.]

Suggested Next Steps

Suggested Next Steps

[Based on the analysis, what appears to be remaining work or natural next actions]
undefined
[Based on the analysis, what appears to be remaining work or natural next actions]
undefined

Important Guidelines

重要准则

  1. Code is the source of truth: The branch's commits and changes represent what's actually being built, which may differ from the original ticket description.
  2. Group by intent, not structure: Don't just list files by directory. Understand what each change accomplishes and group related changes together.
  3. Include file:line references: When describing changes, point to specific locations in files so the user can quickly navigate.
  4. Identify work-in-progress: Distinguish between completed (committed) work and in-progress (uncommitted) work.
  5. Note drift from ticket: If a Linear ticket was provided, explicitly call out where the implementation has evolved beyond or differs from the ticket description.
  6. Be concise but complete: The summary should give someone enough context to immediately start working, without overwhelming them with every detail.
  1. 代码为首要依据：分支的提交记录和变更代表实际开发内容，可能与原始工单描述存在差异。
  2. 按意图分组，而非结构：不要仅按目录罗列文件，需理解每项变更的作用，将相关变更归为一组。
  3. 包含文件:行号引用：描述变更时，指向文件中的具体位置，方便用户快速定位。
  4. 识别进行中的工作：区分已完成（已提交）和进行中（未提交）的工作。
  5. 标注与工单的偏差：若提供了Linear工单，需明确指出实现内容与工单描述的差异或迭代之处。
  6. 简洁但完整：总结需为用户提供足够上下文，使其能立即开展工作，同时避免过多冗余细节。

Example Output

示例输出

markdown
undefined
markdown
undefined

Branch Context: feat/comment-threads

Branch Context: feat/comment-threads

Base branch: main Commits since divergence: 3 Linear ticket: TASK-142
Base branch: main Commits since divergence: 3 Linear ticket: TASK-142

Intent Summary

Intent Summary

This branch adds threaded comments to tasks, allowing users to start discussion threads on individual tasks and reply to existing comments. The implementation includes a new database table, API routes for CRUD operations, and a collapsible thread UI in the task detail view.
This branch adds threaded comments to tasks, allowing users to start discussion threads on individual tasks and reply to existing comments. The implementation includes a new database table, API routes for CRUD operations, and a collapsible thread UI in the task detail view.

Feature Areas

Feature Areas

Comments Data Layer

Comments Data Layer

Purpose: Database schema and API routes for storing and retrieving comment threads Status: Complete
Committed changes:
  • src/db/schema/comments.ts
    - New comments table with parent_id for threading
  • src/db/migrations/0012_add_comments.sql
    - Migration file
  • src/api/routes/comments.ts
    - CRUD endpoints for comments
Purpose: Database schema and API routes for storing and retrieving comment threads Status: Complete
Committed changes:
  • src/db/schema/comments.ts
    - New comments table with parent_id for threading
  • src/db/migrations/0012_add_comments.sql
    - Migration file
  • src/api/routes/comments.ts
    - CRUD endpoints for comments

Thread UI Components

Thread UI Components

Purpose: Components for displaying and composing threaded comments on tasks Status: In Progress
Committed changes:
  • src/components/tasks/CommentThread.tsx
    - Recursive thread display component
Uncommitted changes:
  • src/components/tasks/CommentComposer.tsx
    - Reply/new comment input box
  • src/hooks/useCommentThread.ts
    - Data fetching hook for thread state
Purpose: Components for displaying and composing threaded comments on tasks Status: In Progress
Committed changes:
  • src/components/tasks/CommentThread.tsx
    - Recursive thread display component
Uncommitted changes:
  • src/components/tasks/CommentComposer.tsx
    - Reply/new comment input box
  • src/hooks/useCommentThread.ts
    - Data fetching hook for thread state

Code vs Ticket Drift

Code vs Ticket Drift

The ticket scoped comments as flat (non-threaded), but the implementation adds full threading support with nested replies via a parent_id column.
The ticket scoped comments as flat (non-threaded), but the implementation adds full threading support with nested replies via a parent_id column.

Suggested Next Steps

Suggested Next Steps

  1. Complete the CommentComposer component and wire it into CommentThread
  2. Add optimistic updates to useCommentThread for snappy UX
  3. Add tests for the comment API routes
undefined
  1. Complete the CommentComposer component and wire it into CommentThread
  2. Add optimistic updates to useCommentThread for snappy UX
  3. Add tests for the comment API routes
undefined