Help us improve
Share bugs, ideas, or general feedback.
From popkit-research
Merges research branches from Claude Code Web sessions into main, moves docs to .claude/research/, creates GitHub issues, and cleans up branches. Use for claude/research-* branches or manual mobile processing.
npx claudepluginhub jrc1883/popkit-ai --plugin popkit-researchHow this skill is triggered โ by the user, by Claude, or both
Slash command
/popkit-research:pop-research-mergeThe summary Claude sees in its skill listing โ used to decide when to auto-load this skill
Handles the complete workflow for processing research branches created during Claude Code Web sessions:
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
Handles the complete workflow for processing research branches created during Claude Code Web sessions:
Trigger: Called by pop-next-action skill when research branches detected, or directly via /popkit:research merge.
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
Use the research_branch_detector.py utility:
from popkit_shared.utils.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))
For each branch, show a preview before prompting:
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]}...")
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
Branch Protection Check (Issue #142):
Before merging, MUST check current branch:
# Get current branch
current_branch=$(git branch --show-current 2>/dev/null)
# Protected branches: main, master, develop, production
PROTECTED_BRANCHES=("main" "master" "develop" "production")
# Check if on protected branch
is_protected=false
for branch in "${PROTECTED_BRANCHES[@]}"; do
if [ "$current_branch" = "$branch" ]; then
is_protected=true
break
fi
done
# If on protected branch, BLOCK and recommend feature branch
if [ "$is_protected" = true ]; then
echo "โ ERROR: Cannot merge research directly into protected branch '$current_branch'"
echo ""
echo "Protected branch policy requires feature branch workflow."
echo ""
echo "Recommended steps:"
echo " 1. Create feature branch:"
echo " git checkout -b feat/research-merge-[topic]"
echo ""
echo " 2. Re-run research merge (will merge into feature branch)"
echo ""
echo " 3. Push and create PR:"
echo " git push -u origin feat/research-merge-[topic]"
echo " gh pr create --title 'docs: merge [topic] research'"
echo ""
echo "See CLAUDE.md 'Git Workflow Principles' for details."
exit 1
fi
If on feature branch, proceed with merge:
Based on user choice:
# 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 .claude/research/)
mkdir -p .claude/research
# Move any root-level research docs
git mv RESEARCH*.md .claude/research/ 2>/dev/null || true
git mv *_RESEARCH.md .claude/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]
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?"
No action - branch remains for future processing.
# Confirm deletion
# "Are you sure? This research will be permanently lost."
git push origin --delete claude/research-[topic]-[session-id]
After processing all branches:
## 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
[Research] {Topic Title}
Examples:
[Research] Claude Code v2.0.65 Features Integration[Research] Audio Feedback Hooks Architecture## Summary
{Executive summary from research doc}
## Source
- **Branch:** `{full_branch_name}`
- **Created:** {created_ago}
- **Files:** {file_count} changed
## Documentation
- `.claude/research/{doc_name}.md`
## Implementation Tasks
- [ ] {Task 1 from research}
- [ ] {Task 2 from research}
---
_Auto-generated from research branch by PopKit_
Automatically apply:
research - Marks as research outputdocumentation - Contains documentationOptionally detect from content:
enhancement - If implementation tasks foundP1-high / P2-medium / P3-low - From priority metadata| 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 |
For best results, research docs should follow this format:
# 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]
| 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 |
/popkit:next - Primary entry point/popkit:routine morning - Can detect in morning checkpopkit_shared.utils.research_branch_detector - Detection utilityoutput-styles/research-summary.md - Output formatting