GitLab Researcher

Orchestrates autonomous research on GitLab issues using parallel read-only subagents, then posts structured findings as issue comments.

Workflow

Step 1: Determine Project & Issues

Project path: - If the user mentions a project, use it. - Otherwise, check if the current workspace is a Git repository. If it is, derive the GitLab project path from git remote -v (e.g., owner/repo-name). Use this as the default project. - If the workspace is not a Git repository, ask the user which GitLab project to research.

Issue selection:

User specifies issues — use those IIDs directly.
User describes a topic — use gitlab_search (scope: issues) to find matching issues.
General research sweep — list open issues with gitlab_list_issues(state="opened"), then prioritize by: age (older first), labels (bug > enhancement), weight, due date, and impact. Present top candidates to the user. Default: research all open issues.

Step 2: Gather Issue Details

For each selected issue: 1. Call gitlab_get_issue to read the full issue and all comments. 2. Note any existing research comments to avoid duplicating work.

Step 3: Launch Parallel Research Subagents

For each issue, spawn a read-only subagent. Launch all subagents in the same turn for parallel execution.

Subagent prompt format:

Research this GitLab issue thoroughly.

Issue Details:
- Project: {project_path}
- Issue IID: {issue_iid}
- Title: {title}
- Description: {description}
- Labels: {labels}
- Comments: {existing_comments}

Perform the following research:

1. UNDERSTAND THE PROBLEM: Read the issue description and all comments
   carefully. Identify the core problem, reproduction steps, and expected vs.
   actual behavior.

2. INVESTIGATE THE CODEBASE: Read the relevant source files to understand the
   current implementation. Identify the code paths involved, data flow, and
   dependencies.

3. ROOT CAUSE ANALYSIS: Determine the likely root cause. Is it a bug, missing
   feature, configuration issue, or design limitation?

4. ONLINE RESEARCH:
    - Use Context7 to fetch current documentation and best practices for the
      relevant libraries and frameworks. If Context7 is unavailable or returns
      no results, fall back to web search for the same documentation.
    - Search the web for similar issues, bug reports, stack traces, and
      solutions.
    - Search GitHub for similar implementations, upstream fixes, and
      established patterns.
    - Check if there are known workarounds or upstream fixes.
    - CITE SOURCES INLINE as you mention findings. Use markdown links:
      `According to [React docs](url)` or `As shown in [GitHub issue #123](url)`.
      Do not reference a source without linking to it.

5. PROPOSE SOLUTIONS: Suggest 2-3 concrete solutions, ranked by:
   - Effectiveness (how well it solves the problem)
   - Complexity (effort to implement)
   - Risk (potential for regressions)
   Include specific files to change and a high-level approach for each.

6. ASSESS RISKS: Identify potential side effects, edge cases, and testing
   requirements for each solution.

Return a structured research report:
- Summary (1-2 sentences)
- Root Cause Analysis
- Online Research Findings (with references)
- Proposed Solutions (ranked, with files to change)
- Risks and Testing Requirements
- Recommended Approach (with justification)
- Sources: Group by category with direct links:
    - Documentation: [Library/Framework] - [URL]
    - GitHub Issues/PRs: [repo/issue] - [URL]
    - Articles/Blogs: [Title] - [URL]
    - Papers: [Title] - [URL]

IMPORTANT: The report will be posted as a comment on the GitLab issue. Always include a "Sources" section at the end with every link you used during research. A report without sources is incomplete. If no external sources were found, state: "No external references found during research." Every claim that relies on external knowledge must have an inline citation.

Step 4: Collect Results

As subagents complete, collect their research reports. Wait for all to finish before proceeding.

Step 5: Post Findings as Issue Comments

For each issue, post the research report as a comment using gitlab_add_issue_note: - project_path: the project path - issue_iid: the issue number - body: the subagent's research report (already in markdown format)

Step 6: Show Summary

Present a concise summary in chat:

## Research Complete

| Issue | Title | Recommended Approach | Complexity |
|-------|-------|---------------------|------------|
| #42   | Login bug | [brief description] | Medium     |
| #38   | Add caching | [brief description] | Low        |

Detailed comments posted on each issue.

**Next steps:** Ready to implement? Use the `gitlab-solver` skill to turn
these findings into code changes and merge requests.

Important

Subagents are read-only — only the main agent posts comments.
If a subagent returns minimal findings, note that the issue may need clarification.
If research reveals an issue is invalid or duplicate, note this in the comment and suggest closing.
Always check for existing research comments before posting — if one exists, reference it in your summary.
Online research is mandatory — every subagent must use Context7 (with web search fallback) and web search to ground findings in current best practices.

When NOT to Use

When the user just wants to quickly fix something without research.
When the user explicitly says "just implement it".
When there's only one trivial issue (typo fix, simple config change).

gitlab-researcher