research-expert
Exploratory analysis of repositories and technical sources: dependency map generation (AST parsing), bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis via git log mining, multi-source triangulation, and citation tracking. Use when exploring unfamiliar codebases, researching technical approaches, comparing technologies, analyzing repository structure, or building knowledge bases from source code. Trigger: research, codebase exploration, dependency mapping, technical debt, hot-spot analysis, git mining, triangulation. Do NOT trigger for: debugging specific bugs, writing code, reviewing pull requests, general web research without codebase context (use websearch tool directly).
- License 许可
- MIT
- 最近更新
- 2026-08-27
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- research-expert
- license
- MIT
- metadata
- { "author": "Community", "status": "stable", "version": "1.1", "category": "process" }
- description
- Exploratory analysis of repositories and technical sources: dependency map generation (AST parsing), bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis via git log mining, multi-source triangulation, and citation tracking. Use when exploring unfamiliar codebases, researching technical approaches, comparing technologies, analyzing repository structure, or building knowledge bases from source code. Trigger: research, codebase exploration, dependency mapping, technical debt, hot-spot analysis, git mining, triangulation. Do NOT trigger for: debugging specific bugs, writing code, reviewing pull requests, general web research without codebase context (use websearch tool directly).
02 资源文件 4
- 参考文档evals/evals.json3.0 KB
- 参考文档references/analysis-tools.md1.5 KB
- 参考文档references/codebase-analysis.md847 B
- 参考文档references/triangulation.md1.3 KB
03 SKILL.md 正文
Research Expert
Codebase exploration, dependency mapping, tech research and triangulation.
Research Workflow
- Define question — what specifically are we trying to learn?
- Gather sources — code, docs, git history, external references
- Map dependencies — what depends on what?
- Identify patterns — architecture style, bounded contexts, anti-patterns
- Triangulate — cross-validate across >=3 independent sources
- Synthesize — produce structured findings document
Codebase Analysis
# Hotspot analysis — files changed most frequently
git log --format=format: --name-only | sort | uniq -c | sort -nr | head -20
# Code churn — files with most added/deleted lines
git log --numstat --pretty=format: | awk '{a[$3]+=$1+$2} END {for(f in a) print a[f],f}' | sort -nr | head -20
# Dependency map — what imports this package?
grep -r "import.*github.com/example/services" --include="*.go" -l
Dependency Graph Analysis
Entry points -> Core domain -> Infrastructure -> External deps
Identify:
- Circular dependencies (A imports B, B imports A)
- God packages (imported by >20 files)
- Orphans (imported by 0 files — dead code?)
Multi-Source Triangulation
| Source | Reliability | Use For |
|---|---|---|
| Source code | Highest | Behavior, architecture |
| Tests | High | Expected behavior, edge cases |
| Git history | High | Change frequency, ownership |
| Documentation | Medium | Intent, rationale |
| Issues/PRs | Medium | Known problems, discussions |
| External docs | Variable | API specs, best practices |
Constraints
- NEVER trust documentation over code behavior (code is truth)
- NEVER draw conclusions from single source (triangulate >=3)
- ALWAYS verify assumptions by reading actual source code
- NEVER assume patterns without statistical evidence (grep counts, git stats)
Overview
Conduct exploratory analysis of repositories and technical sources: dependency graph mapping via AST parsing, bounded context detection, quantitative technical debt identification (code churn, cyclomatic complexity), hotspot analysis through git log mining, multi-source triangulation, and citation tracking.
Quick Reference
| Analysis | Command | Insight |
|---|---|---|
| Hotspot files | git log --name-only | sort |
| Code churn | git log --numstat | awk sum |
| Dependencies | grep -r "import.*pkg" | Which files depend on a given package |
| Cyclomatic complexity | gocyclo ./... | High-complexity functions needing refactor |
| Bounded contexts | grep package declarations | Module boundaries and cohesion |
Workflow
- Define the research question explicitly before gathering data
- Gather sources: code, git history, docs, issues, external references
- Map dependencies and identify circular deps or god packages
- Analyze hotspots: high churn + high complexity = refactor candidates
- Triangulate findings across at least 3 independent sources
- Synthesize into structured document with evidence and recommendations
Anti-patterns
FAIL: Drawing conclusions from a single source
# BAD: trusting a single comment or doc
# docs say "this is the target service" — may be outdated
# GOOD: triangulate
# 1. Check actual imports in go.mod
# 2. Read handler entry points
# 3. Verify with git history ownership
FAIL: Confusing documentation with implementation reality
# BAD: trusting README over source code
# README says "supports async" — check actual code
# GOOD: verify assumptions
# grep -r "async\|goroutine\|channel" ./services/
FAIL: Relying on intuition instead of statistical data
# BAD: "I think services is the most complex module"
# no data to back it up
# GOOD: measure it
# gocyclo ./services/ && git log --numstat -- services/
Claim Verification and Fact-Check
Applies when a research question demands factual verification, not codebase exploration (closes the "no general web research" gap, master catalog #102):
- Extract claims: split the question into individual checkable claims
- Gather evidence: collect at least two independent sources per claim
- Structured verdicts: mark each claim VERIFIED, PARTIALLY VERIFIED, or UNVERIFIED
- Transparent report: list every source with its access date and any conflict between sources
Rules:
- A claim stays UNVERIFIED when sources conflict or a source cannot be located
- Rank sources: primary documentation and vendor docs above aggregators
- Never fabricate a citation; an unverifiable claim is reported as UNVERIFIED, not silently dropped
References
-
Martin Fowler on technical debt quadrant: https://martinfowler.com/bliki/TechnicalDebtQuadrant.html (last_verified: 2026-05)
-
Adam Tornhill's code analysis tools: https://codescene.com/ (last_verified: 2026-05)
-
Google's research methods guide: https://research.google/pubs/ (last_verified: 2026-05)
Verification Checklist
- [ ] Research question defined explicitly before gathering data
- [ ] Findings triangulated across at least 3 independent sources
- [ ] Code behavior verified by reading actual source (not trusting docs/comments alone)
- [ ] Statistical evidence gathered (grep counts, git stats) — not intuition
- [ ] Circular dependencies and god packages identified in dependency map
- [ ] Hotspot analysis run: high churn + high complexity files identified
- [ ] Structured findings document produced with evidence and recommendations
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Conclusion contradicts actual code | Relied on documentation instead of reading source | Re-read the actual source files; doc is always secondary to code |
| Multiple false hotspots identified | Git log includes auto-generated or vendored files | Exclude generated code and vendor dirs from git log analysis |
| Dependency graph shows no circular deps | Static grep misses dynamic imports or runtime resolution | Use AST-level analysis tool (e.g., go tool deps) instead of grep for Go modules |
| Git log hotspot analysis skews toward recent commits (known issue: recency bias in git mining) | Recent history weighted equally with all-time history | Use time-windowed analysis (last 3 months, last year) instead of full git log; compare delta |
04 同仓库更多 Skills
web-browsing-agent-expert
Web browsing for AI agents: driving a headless browser (Playwright, Puppeteer) from agent tooling, navigation and page-state grounding, DOM extraction and structured data capture, form interaction, session and cookie management, anti-bot mitigation awareness, and safe browsing rules (no PII exfiltration, respect robots and terms). Use when building a browsing tool or MCP server for an agent, teaching an agent to navigate and read web pages, extracting structured content from dynamic sites, or handling login walls and pagination in agent workflows. Trigger: web browsing agent, headless browser, Playwright MCP, Puppeteer, browser automation for agents, DOM extraction, page navigation, session management. Do NOT trigger for: end-to-end UI testing of an application (use playwright-expert); writing standalone scraping scripts for data pipelines (use python-expert); fetching a single public URL (use the fetch tool).
vector-databases
Design and operate vector databases for cloud-native AI features. Use when selecting between pgvector, Pinecone, or Weaviate for AI context layer or integration-hub; designing embedding schemas and index parameters; implementing ANN search with metadata filtering; managing embedding model versions; optimizing query latency; or debugging low retrieval quality. Pairs with rag-architecture for pipeline design and postgres-database-expert for pgvector specifics. Trigger: vector database, pgvector, Pinecone, Weaviate, embedding, ANN search, HNSW, cosine similarity. Do NOT trigger for: relational SQL optimization, standard PostgreSQL schema design, Redis caching.
typescript-expert
Full-stack TypeScript stack for modern projects: frontend SSR/CSR with Next.js 14 App Router and React, backend APIs with Node.js (Express/Fastify), state management with Zustand/Redux Toolkit, unit and integration testing with Vitest/Jest + React Testing Library + MSW, and static analysis with ESLint/Prettier/tsc. Use when building React components or hooks, implementing Next.js App Router or Server Components, writing Node.js REST API handlers, implementing middleware (auth, rate-limit, logging), managing client state (Zustand/RTK), writing frontend/backend tests, or running TypeScript linting/type checks. Trigger: TypeScript, Next.js, React, Zustand, Node.js, Express, Fastify, MSW, Vitest. Do NOT trigger for: Python backend development, Go microservices, iOS/mobile development.
tool-usage
Guide correct tool selection, design, and orchestration for AI agents. Use when choosing between dedicated vs Bash tools, designing MCP tool interfaces, naming tool parameters, handling tool response limits, orchestrating parallel vs sequential calls, evaluating tool accuracy, applying ACI design principles, selecting workflow patterns, or reading/filtering/transforming/generating structured data (JSON, YAML, CSV, TOML, XML). Trigger: tool selection, MCP tool design, orchestration, ACI, parallel execution, composite tool, structured data, jq, yq, dasel, mlr, csvkit. Do NOT trigger for: writing application business logic, domain-specific development (route to domain skill), database migrations.
token-efficiency
Enforce token-efficient output, compression, caching, and model routing. Use when calibrating response verbosity, applying compression strategies to logs or RAG chunks, routing tasks to the right model tier, setting thinking budgets, enforcing word limits, compressing context before reinitiation, applying KV-cache ordering, masking tool output observations, or applying clarification-first protocol before irreversible actions. Trigger: token efficiency, compression, model routing, thinking budget, KV-cache, clarification protocol. Do NOT trigger for: non-agent tooling, CI/CD pipeline scripting, infrastructure provisioning.
time-series-db
Time-series database patterns for cloud-native metrics and analytics: TimescaleDB, InfluxDB, and Amazon Timestream selection; continuous aggregates, retention policies, downsampling, and integration with Prometheus/Grafana. Use when storing business metrics over time, building custom business dashboards, designing high-frequency event storage, or querying time-bucketed aggregations. Trigger: time-series, TimescaleDB, InfluxDB, Prometheus, Grafana, hypertable, continuous aggregate, retention policy. Do NOT trigger for: relational PostgreSQL schema design, NoSQL document stores, Kafka event streaming.