synesenom/ran / .claude/skills/research
research
VerifiedResearch 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>(ormcp__github__issue_readifghis 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):- Check the current branch:
git branch --show-current - If the branch name already starts with the issue number, skip branch creation
- Otherwise, derive the branch name:
<issue-number>-<slugified-issue-title>(lowercase, kebab-case) - Switch to
main:git checkout main - Create a linked branch:
gh issue develop <issue-number> --name <branch-name> --checkout ghunavailable: usemcp__github__issue_readto fetch the issue and create the branch locally withgit checkout -b <issue-number>-<slug>.
- Check the current branch:
- Fetch the issue details using:
- 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>.mdBranch:
<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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 114k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |
| 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: 114k | Updated | Claude CodeCodex | Verified | Install |
| 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: 114k | Updated | Claude CodeCodex | Verified | Install |