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：确定基准分支

Check common base branch names:

bash

git branch -a | grep -E "(main|master|dev|develop)" | head -5

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

Get current branch name:
bash
```
git branch --show-current
```

检查常见基准分支名称：

bash

git branch -a | grep -E "(main|master|dev|develop)" | head -5

找到合并基准：

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

获取当前分支名称：
bash
```
git branch --show-current
```

Step 2: Gather Commit History Since Divergence

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

Get all commits since diverging from base:

bash

git log --oneline $(git merge-base HEAD dev)..HEAD

Get detailed commit messages for understanding intent:

bash

git log --format="%h %s%n%b" $(git merge-base HEAD dev)..HEAD

Get files changed across all commits:

bash

git diff --name-status $(git merge-base HEAD dev)..HEAD

获取自与基准分支分歧后的所有提交：
bash
```
git log --oneline $(git merge-base HEAD dev)..HEAD
```

获取详细提交信息以理解开发意图：

bash

git log --format="%h %s%n%b" $(git merge-base HEAD dev)..HEAD

获取所有提交中变更的文件：

bash

git diff --name-status $(git merge-base HEAD dev)..HEAD

Step 3: Gather Uncommitted Changes

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

Get staged changes:
bash
```
git diff --name-status --cached
```
Get unstaged changes:
bash
```
git diff --name-status
```

Get untracked files:

bash

git ls-files --others --exclude-standard

Full working tree status:
bash
```
git status --short
```

获取已暂存的变更：
bash
```
git diff --name-status --cached
```
获取未暂存的变更：
bash
```
git diff --name-status
```

获取未追踪的文件：

bash

git ls-files --others --exclude-standard

完整工作区状态：
bash
```
git status --short
```

Step 4: Fetch Linear Ticket (If Provided)

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

If the user provides a Linear ticket:

Use the
```
mcp__linear__get_issue
```
tool to fetch the ticket details
Note: The ticket represents the original requirements but the code may have evolved

如果用户提供了Linear工单：

使用
```
mcp__linear__get_issue
```
工具获取工单详情
注意：工单代表原始需求，但代码可能已经迭代更新

Step 5: Analyze and Group Changes by Intent

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

CRITICAL: Do not just list files. Group them by logical feature area or intent.

Read key changed files to understand what they do
Identify patterns in the changes:
- New feature additions
- Bug fixes
- Refactoring
- Configuration changes
- Test additions
Group files by their purpose, not by directory

关键要求：不要仅罗列文件，需按逻辑功能区域或开发意图进行分组。

阅读关键变更文件以理解其作用
识别变更模式：
- 新增功能
- Bug修复
- 代码重构
- 配置变更
- 测试用例新增
按用途分组文件，而非按目录结构

Step 6: Output Summary

步骤6：输出总结

Present findings in this structure:

markdown

undefined

按照以下结构呈现分析结果：

markdown

undefined

Branch Context: [branch-name]

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

Intent Summary

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

Feature Areas

[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]

...

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

[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

[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

重要准则

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.
Group by intent, not structure: Don't just list files by directory. Understand what each change accomplishes and group related changes together.
Include file:line references: When describing changes, point to specific locations in files so the user can quickly navigate.
Identify work-in-progress: Distinguish between completed (committed) work and in-progress (uncommitted) work.
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.
Be concise but complete: The summary should give someone enough context to immediately start working, without overwhelming them with every detail.

代码为首要依据：分支的提交记录和变更代表实际开发内容，可能与原始工单描述存在差异。
按意图分组，而非结构：不要仅按目录罗列文件，需理解每项变更的作用，将相关变更归为一组。
包含文件:行号引用：描述变更时，指向文件中的具体位置，方便用户快速定位。
识别进行中的工作：区分已完成（已提交）和进行中（未提交）的工作。
标注与工单的偏差：若提供了Linear工单，需明确指出实现内容与工单描述的差异或迭代之处。
简洁但完整：总结需为用户提供足够上下文，使其能立即开展工作，同时避免过多冗余细节。

Example Output

示例输出

markdown

undefined

markdown

undefined

Branch Context: feat/comment-threads

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

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.

Feature Areas

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

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

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

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

undefined

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

undefined