Skip to content

synesenom/ran / .claude/skills/research

research

Verified

Research Command

You are conducting comprehensive codebase research to document what exists without suggesting changes.

Core Principle

ONLY document what exists — DO NOT suggest changes, improvements, or critiques.

Workflow

When the user invokes /research <topic>:

1. Understand the Research Question

  • Read the user's query carefully
  • If the query contains a GitHub issue URL or a short reference (e.g. #123):
    • Fetch the issue details using: gh issue view <number-or-url> (or mcp__github__issue_read if gh is unavailable)
    • Use the issue title and body as the research question / context
    • Include the issue number in the research document frontmatter as github_issue: <number>
    • Create a development branch (only when invoked standalone — when invoked from /build, the branch already exists):
      1. Check the current branch: git branch --show-current
      2. If the branch name already starts with the issue number, skip branch creation
      3. Otherwise, derive the branch name: <issue-number>-<slugified-issue-title> (lowercase, kebab-case)
      4. Switch to main: git checkout main
      5. Create a linked branch: gh issue develop <issue-number> --name <branch-name> --checkout
      6. gh unavailable: use mcp__github__issue_read to fetch the issue and create the branch locally with git checkout -b <issue-number>-<slug>.
  • Otherwise, identify what the user wants to understand about the codebase

2. Spawn Parallel Sub-Agents

If needed for broad searches, spawn these agents in parallel:

  • discovery-code agent — to find relevant files
  • discovery-analyze agent — for deep analysis of how code works

3. Web Research (when needed)

If the research topic involves external concepts — statistical distributions, mathematical formulas, numerical algorithms, external references (DLMF, NIST, Wikipedia distribution articles) — use WebSearch and WebFetch tools to gather context.

When to do web research:

  • The topic references a distribution not yet in the codebase (find the canonical PDF/CDF formulas)
  • The topic involves a numerical algorithm or special function from the literature
  • The topic references a statistical test with a specific reference distribution
  • The user explicitly asks for external context

When NOT to do web research:

  • The topic is purely about internal codebase structure or data flow
  • The answer is fully derivable from reading the code

4. Gather Codebase Information

  • Search for relevant files using Glob and Grep tools
  • Read and understand key code sections
  • Trace data flows and component interactions
  • Document patterns and conventions

5. Produce Research Document

Create a structured markdown file at: thoughts/research/YYYY-MM-DD-HHmm-<topic-slug>.md

Use this format:

---
date: <ISO timestamp>
topic: "<user's research question>"
github_issue: <number, if sourced from a GitHub issue — omit otherwise>
status: complete
---

# Research: <topic>

**Date**: <timestamp>
**Repository**: ranjs
**Branch**: <current branch>

## Research Question

<Original user query, or issue title + body if sourced from GitHub>

## Summary

<High-level findings - 2-3 paragraphs answering the question>

## Detailed Findings

### Component 1: <name>

- **Location**: `src/dist/log-normal.js:23-45`
- **Purpose**: What this component does
- **Key Details**: Important implementation details
- **Connections**: How it connects to other components

### Component 2: <name>

<Similar structure>

## Information Flow

<Diagram or description of how data/control flows through the system>

## Patterns & Conventions

- Pattern 1: Description with examples
- Pattern 2: Description with examples

## Key Files Reference

- `src/dist/_distribution.js` — Base Distribution class
- `src/algorithms/brent.js` — Brent root-finding (used for quantile)
- `src/special/gamma.js` — Gamma function

## External Context

<If web research was performed, summarize key findings here.
Include canonical formulas with citations. Omit if no web research was needed.>

## Sources

<List of external URLs consulted. Omit if no web research was needed.>

- [Source Title](https://example.com)

## Questions for Planning Phase

<Any open questions that need human decision in planning>

6. Present to User

"I've completed the research on [topic]. The findings are documented at:

thoughts/research/YYYY-MM-DD-HHmm-<topic>.md

Branch: <branch-name> (if created from a GitHub issue)

Key findings:

  • <Key finding 1>
  • <Key finding 2>
  • <Key finding 3>

Please review the research document. When you're ready to create a plan, use: /plan <description> — see thoughts/research/YYYY-MM-DD-HHmm-<topic>.md"

Rules

DO:

  • Describe what IS, not what SHOULD BE
  • Provide precise file:line references
  • For new distributions: document the canonical PDF/CDF formula from authoritative sources
  • Save everything to thoughts/research/

DO NOT:

  • Suggest improvements or changes
  • Perform root cause analysis
  • Propose future enhancements
  • Include subjective opinions or critiques
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 114kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 114kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 114kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 114kUpdated Claude CodeCodexVerifiedInstall