Skip to content
Back to skills

Research Merge

ASecurity

Processes research branches from Claude Code Web sessions - merges content, moves docs to docs/research/, and creates GitHub issues. Use when /popkit:next detects research branches or when manually processing research from mobile sessions. Do NOT use for regular feature branches - only for branches matching claude/research-* or containing research documentation.

  • 470 stars
  • 0 votes
  • 0 copies
  • 3 views
  • Added February 8, 2026
devopspythongobashgitdocumentation

Works with

  • claude code
  • cli

Security analysis

A100/100

Pro scans all 5 files and shows the line behind each finding

Scanned February 12, 2026

npx -y skills add aiskillstore/marketplace --skill research-merge --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Research Merge?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Research Merge
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/aiskillstore-research-merge/badge)](https://www.skillsdirectory.com/skills/aiskillstore-research-merge)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: research-merge
description: "Processes research branches from Claude Code Web sessions - merges content, moves docs to docs/research/, and creates GitHub issues. Use when /popkit:next detects research branches or when manually processing research from mobile sessions. Do NOT use for regular feature branches - only for branches matching claude/research-* or containing research documentation."
---

# Research Branch Merge

## Overview

Handles the complete workflow for processing research branches created during Claude Code Web sessions:

1. Detect research branches
2. Preview content for user approval
3. Squash-merge to main branch
4. Move docs to standardized location
5. Create GitHub issue from findings
6. Clean up remote branch

**Trigger:** Called by `pop-next-action` skill when research branches detected, or directly via `/popkit:research merge`.

## User Interaction Pattern

**ALWAYS use AskUserQuestion** for merge decisions:

```
Use AskUserQuestion tool with:
- question: "Found research branch: [topic]. How should we process it?"
- header: "Research"
- options:
  - label: "Merge and create issue"
    description: "Squash-merge, move docs, create GitHub issue, delete branch"
  - label: "Merge only"
    description: "Squash-merge content without creating issue"
  - label: "Skip for now"
    description: "Leave branch for later processing"
  - label: "Delete branch"
    description: "Discard research (cannot be undone)"
- multiSelect: false
```

## Processing Workflow

### Step 1: Detect Research Branches

Use the `research_branch_detector.py` utility:

```python
import sys
# No longer needed - install popkit-shared instead
from research_branch_detector import (
    fetch_remotes,
    get_research_branches,
    format_branch_table,
    get_branch_content_preview,
    parse_research_doc,
    generate_issue_body
)

# Fetch and detect
fetch_remotes()
branches = get_research_branches()

if not branches:
    print("No research branches detected.")
    return

# Show table
print("## Research Branches Detected\n")
print(format_branch_table(branches))
```

### Step 2: Preview Content

For each branch, show a preview before prompting:

```python
for branch in branches:
    print(f"\n### {branch.short_name}")
    print(f"**Topic:** {branch.topic}")
    print(f"**Created:** {branch.created_ago}")
    print(f"**Commits:** {branch.commit_count} ahead of master")

    if branch.doc_paths:
        print(f"\n**Documentation:**")
        for path in branch.doc_paths:
            print(f"- `{path}`")

        # Show summary preview
        previews = get_branch_content_preview(branch, max_lines=20)
        for path, content in previews.items():
            parsed = parse_research_doc(content)
            if parsed.get("summary"):
                print(f"\n**Summary:** {parsed['summary'][:200]}...")
```

### Step 3: User Decision

Use AskUserQuestion for each branch:

```
Use AskUserQuestion tool with:
- question: f"Process '{branch.topic}' research? ({branch.commit_count} commits, {len(branch.doc_paths)} docs)"
- header: "Merge"
- options:
  - label: "Merge + Issue"
    description: "Full processing: merge, organize docs, create issue"
  - label: "Merge Only"
    description: "Just merge the content"
  - label: "Skip"
    description: "Process later"
  - label: "Delete"
    description: "Discard this research"
- multiSelect: false
```

### Step 4: Execute Merge

Based on user choice:

#### Option A: Merge + Issue (Full Processing)

```bash
# 1. Ensure clean working directory
git status --porcelain
# If dirty, prompt user to commit or stash first

# 2. Squash merge the research branch
git merge --squash origin/claude/research-[topic]-[session-id]

# 3. Organize docs (if not already in docs/research/)
mkdir -p docs/research
# Move any root-level research docs
git mv RESEARCH*.md docs/research/ 2>/dev/null || true
git mv *_RESEARCH.md docs/research/ 2>/dev/null || true

# 4. Commit with standard message
git commit -m "docs(research): merge [topic] research from web session

Merged from: [branch-name]
Created: [created-ago]

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

# 5. Create GitHub issue
gh issue create --title "[Research] [Topic Title]" --body "[generated-body]" --label "research,documentation"

# 6. Delete remote branch
git push origin --delete claude/research-[topic]-[session-id]
```

#### Option B: Merge Only

```bash
git merge --squash origin/claude/research-[topic]-[session-id]
git commit -m "docs(research): merge [topic] research

Merged from: [branch-name]

🤖 Generated with [Claude Code](https://claude.ai/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

# Optionally delete branch
# Ask: "Delete the remote branch?"
```

#### Option C: Skip

No action - branch remains for future processing.

#### Option D: Delete

```bash
# Confirm deletion
# "Are you sure? This research will be permanently lost."

git push origin --delete claude/research-[topic]-[session-id]
```

### Step 5: Summary Report

After processing all branches:

```markdown
## Research Processing Complete

| Branch | Action | Result |
|--------|--------|--------|
| research-claude-code | Merged + Issue | Issue #182 created |
| research-audio-hooks | Skipped | - |
| research-old-test | Deleted | - |

**Next Steps:**
- Review created issues
- Run `/popkit:next` to see updated recommendations
```

## Issue Generation

### Title Format

```
[Research] {Topic Title}
```

Examples:
- `[Research] Claude Code v2.0.65 Features Integration`
- `[Research] Audio Feedback Hooks Architecture`

### Body Format

```markdown
## Summary

{Executive summary from research doc}

## Source

- **Branch:** `{full_branch_name}`
- **Created:** {created_ago}
- **Files:** {file_count} changed

## Documentation

- `docs/research/{doc_name}.md`

## Implementation Tasks

- [ ] {Task 1 from research}
- [ ] {Task 2 from research}

---
*Auto-generated from research branch by PopKit*
```

### Labels

Automatically apply:
- `research` - Marks as research output
- `documentation` - Contains documentation

Optionally detect from content:
- `enhancement` - If implementation tasks found
- `P1-high` / `P2-medium` / `P3-low` - From priority metadata

## Error Handling

| Situation | Response |
|-----------|----------|
| Dirty working directory | Prompt to commit/stash first |
| Merge conflicts | Show conflicts, offer manual resolution |
| gh CLI unavailable | Skip issue creation, note in output |
| No doc files | Merge anyway, create minimal issue |
| Branch already merged | Skip, note in output |

## Research Document Standard

For best results, research docs should follow this format:

```markdown
# Research: [Topic Name]

**Research Date:** YYYY-MM-DD
**Status:** Research Document
**Priority:** P1-high | P2-medium | P3-low

## Executive Summary

[Brief summary of findings - becomes issue body]

## Key Findings

[Main research content]

## Implementation Tasks

- [ ] Task 1 [becomes checklist in issue]
- [ ] Task 2
- [ ] Task 3

## References

[Links and sources]
```

## Integration Points

| Component | Role |
|-----------|------|
| `pop-next-action` | Calls this skill when branches detected |
| `research_branch_detector.py` | Core detection logic |
| `/popkit:next` | Entry point for auto-detection |
| `/popkit:routine morning` | Can include in morning routine |
| GitHub Issues | Output destination for findings |

## Related

- `/popkit:next` - Primary entry point
- `/popkit:routine morning` - Can detect in morning check
- `hooks/utils/research_branch_detector.py` - Detection utility
- `output-styles/research-summary.md` - Output formatting

Files in this skill

  • SKILL.md7.5 KB
  • scripts/detect_conflicts.py7.5 KB
  • scripts/merge_findings.py8 KB
  • skill-report.json9.2 KB
  • workflows/merge-workflow.json3.8 KB

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.