---
description: Resolve GitHub Issue with TaskMaster
---

# Resolve GitHub Issue with TaskMaster

Systematically resolve GitHub Issues by TaskMaster subtask units and create PR.

**Important**: This command integrates TaskMaster with GitHub Issues.
- **GitHub Issue number**: `#1`, `#2` format (numbers created by GitHub)
- **TaskMaster Task ID**: `task 1`, `task 1.1` format (based on tasks.json)

Follow project guidelines in `@CLAUDE.md`.

---

## Arguments

`$ARGUMENTS` accepts one of the following:
- GitHub Issue number (e.g., `1`, `#1`)
- TaskMaster Task ID (e.g., `task 1`, `task:1`)

---

## Workflow

### 1. Parse Arguments and Map IDs

```
Input analysis:
- "#1" or "1" -> Interpret as GitHub Issue number
- "task 1" or "task:1" -> Interpret as TaskMaster Task ID
```

**If GitHub Issue number:**

```bash
# Step 1: Get Issue information
gh issue view $ISSUE_NUMBER --json number,title,body,state

# Step 2: Extract TaskMaster Task ID from body
BODY=$(gh issue view $ISSUE_NUMBER --json body --jq '.body')
echo "$BODY" | grep -oP "Task Master reference: task \K[0-9]+"

# Expected output: 1 (number only)
```

**If extraction fails (no Task Master reference):**
```
-> Issue may not have been created by sync-to-github
-> Request direct TaskMaster Task ID input from user
-> AskUserQuestion: "What is the TaskMaster Task ID for this Issue?"
```

**If TaskMaster Task ID:**
```bash
# Verify task in tasks.json
task-master show $TASK_ID

# Find corresponding GitHub Issue (reverse mapping)
gh issue list --search "in:body \"Task Master reference: task $TASK_ID\"" --json number,title
```

**If GitHub Issue not found (Important):**
```
-> sync-to-github may not have been executed
-> NEVER create a new GitHub Issue arbitrarily
-> Confirm with user via AskUserQuestion:
  1. "Run sync-to-github first?" (proceed after Issue sync)
  2. "Create branch only without Issue?" (use task-N branch)
  3. "Abort?"
-> Proceed based on user selection
```

### 2. Verify Task Information

```bash
# Check task details in TaskMaster
task-master show $TASK_ID

# Example output:
# Task 1: Next.js 15 project initial setup
# Status: pending
# Dependencies: none
# Subtasks: (none)
```

**Verification checklist:**
- [ ] Task status is `pending` or `in-progress`
- [ ] All dependency tasks are complete (check dependencies via `task-master show`)

### 2.5. Verify Plan File Alignment (If Exists)

Check if Issue body or Milestone description references a plan file:

```bash
# Extract plan file path from issue body
gh issue view $ISSUE_NUMBER --json body --jq '.body' | grep -oP '(?:Plan|plan|See|see)[:\s]+[`"]?([^\s`"]+\.md)'
```

**If plan file found:**
1. Read the plan file and understand the implementation approach
2. Verify alignment:
   - [ ] Plan objectives match Issue requirements
   - [ ] Plan scope covers all Issue checkboxes
   - [ ] No conflicting approaches between plan and issue
3. If misaligned:
   - Use AskUserQuestion to clarify which to follow
   - Options: "Follow plan", "Follow issue", "Abort for revision"

**If no plan file, continue to Step 3.**

### 3. Expand Subtasks (If Needed)

```bash
# Execute only if no subtasks exist
task-master expand --id=$TASK_ID --research
```

**After expansion verification:**
```bash
task-master show $TASK_ID
# Subtasks:
#   - 1.1: Create project (pending)
#   - 1.2: Initialize Shadcn/ui (pending)
#   - 1.3: Install dependencies (pending)
#   ...
```

### 4. Create Branch

```bash
# Create new branch from main or master
git checkout main && git pull origin main
git checkout -b issue-$ISSUE_NUMBER
```

**Branch naming convention:**
- `issue-1` (for GitHub Issue #1 work)
- `issue-1-subtask-1.2` (for specific subtask only, optional)

### 5. Process Subtasks Sequentially

**Determine processing order:**
```bash
# Check subtask list and dependencies
task-master show $TASK_ID
```

**Processing loop for each subtask:**

```
[Start Subtask 1.1]
1. task-master set-status --id=1.1 --status=in-progress
2. Implement code according to subtask content
3. Verify after implementation (build, lint, test)
4. task-master set-status --id=1.1 --status=done
5. task-master update-subtask --id=1.1 --prompt="Implementation complete: [brief description]"

[Start Subtask 1.2]
... repeat ...
```

**Key principles:**
- Only one subtask `in-progress` at a time
- Process subtasks with dependencies after preceding subtasks complete
- Update status immediately upon each subtask completion

### 6. Complete Main Task

When all subtasks are `done`:

```bash
# Complete main task
task-master set-status --id=$TASK_ID --status=done

# Final verification
task-master show $TASK_ID
```

### 7. Commit and Push

```bash
# Review changes
git status
git diff

# Commit (include task info)
git add .
git commit -m "feat: [Task $TASK_ID] Task title

- subtask 1.1: completion details
- subtask 1.2: completion details
...

Task Master reference: task $TASK_ID
Closes #$ISSUE_NUMBER"

# Push
git push -u origin issue-$ISSUE_NUMBER
```

### 8. Create PR

```bash
gh pr create \
  --title "[Task $TASK_ID] Task title" \
  --body "$(cat <<'EOF'
## Overview
Resolves GitHub Issue #$ISSUE_NUMBER

## TaskMaster Task Info
- **Task ID**: $TASK_ID
- **Task Title**: [task title]

## Completed Subtasks
- [x] subtask 1.1: [description]
- [x] subtask 1.2: [description]
- [x] subtask 1.3: [description]

## Changes
- [summary of major changes]

## Testing
- [ ] Build successful
- [ ] Lint passed
- [ ] Feature testing complete

## Related Issues
Closes #$ISSUE_NUMBER

---
Task Master reference: task $TASK_ID
EOF
)"
```

### 9. Update GitHub Issue

```bash
# Add progress comment to Issue
gh issue comment $ISSUE_NUMBER --body "PR #[PR_NUMBER] created. Requesting code review.

**Completed work:**
$(task-master show $TASK_ID | grep -A 100 'Subtasks:')"
```

---

## ID Mapping Reference

| Type | Format | Example | Description |
|------|--------|---------|-------------|
| GitHub Issue | `#N` | `#1`, `#12` | Auto-assigned by GitHub |
| TaskMaster Main Task | `task N` | `task 1`, `task 12` | id field in tasks.json |
| TaskMaster Subtask | `task N.M` | `task 1.1`, `task 1.2` | maintask.subtask |

**Mapping rule:**
- When `sync-to-github` runs, Issue body includes `Task Master reference: task N`
- This links GitHub Issue <-> TaskMaster Task

---

## Work Guidelines

> See [Work Guidelines](../guidelines/work-guidelines.md)

---

## Verification and Completion Criteria

**Important**: You must verify actual behavior before marking checkboxes as complete.

### Verification Principles
1. **Actual execution required**: Directly run to confirm code/config actually works
2. **Provide evidence**: Show actual output or results that prove completion
3. **No guessing**: Clearly state "unverified" or "assumed" for unconfirmed items
4. **Distinguish partial completion**: Clearly differentiate code written but not tested

### Prohibited
- Reporting "expected to work" without execution
- Asserting "will appear in logs" without checking logs
- Reporting assumptions as facts

---

## Cautions

1. **Avoid ID confusion**
   - GitHub Issue `#1` and TaskMaster `task 1` may differ
   - Always verify "Task Master reference" in Issue body

2. **Follow subtask order**
   - Process subtasks with dependencies in order
   - Check dependencies via `task-master show`

3. **Update status immediately**
   - Run `set-status --status=done` immediately upon subtask completion
   - Progress should be reflected in tasks.json in real-time

4. **Include references in commit messages**
   - Include `Task Master reference: task N`
   - Include `Closes #N` or `Fixes #N`

---

## Error Handling

**Dependency not complete:**
```
Error: Task 1's dependency task 0 is not complete.
-> Complete prerequisite task first
```

**Subtask expand failed:**
```
Error: expand failed
-> Try task-master expand --id=$TASK_ID --force
```

**Build/test failed:**
```
-> Keep that subtask as in-progress
-> Resolve issue and continue
-> task-master update-subtask --id=N.M --prompt="Issue: [description]"
```
