util-research-library

What this skill does

# Library Research & Evaluation

## Purpose

Systematic library evaluation framework that produces readable, actionable decision briefs for library adoption, migration, and upgrade decisions using a 6-dimension research methodology.

## Quick Start

**Create readable, actionable research that drives informed decisions.**

This skill is about **research methodology** - knowing what to look for, where to find it, how to synthesize it, and how to present it. The goal is NOT to dump data, but to **accelerate time to adoption** through clear, confident recommendations.

**Most common use case:**
```
User: "Should we use Pydantic v2?"

→ Research 6 dimensions (docs, updates, alternatives, security, community, codebase)
→ Score each with evidence
→ Deliver decision brief with clear ADOPT/MIGRATE/STAY/AVOID recommendation

Result: 40 minutes (vs 2-4 hours ad-hoc research)
```

## Table of Contents

1. [When to Use This Skill](#when-to-use-this-skill)
2. [What This Skill Does](#what-this-skill-does)
3. [Instructions](#instructions)
4. [Research Framework (6 Dimensions)](#research-framework-6-dimensions)
5. [Output Format: Decision Brief](#output-format-decision-brief)
6. [Usage Examples](#usage-examples)
7. [Expected Outcomes](#expected-outcomes)
8. [Integration Points](#integration-points)
9. [Expected Benefits](#expected-benefits)
10. [Success Metrics](#success-metrics)
11. [Requirements](#requirements)
12. [Troubleshooting](#troubleshooting)
13. [Red Flags to Avoid](#red-flags-to-avoid)

---

## When to Use This Skill

Use this skill when:
- **Adoption decisions:** "Should we use library X?"
- **Migration decisions:** "Should we switch from X to Y?"
- **Upgrade decisions:** "Should we upgrade to version Z?"
- **Security audits:** "Are our dependencies safe?"
- **Performance optimization:** "Is there a faster alternative?"
- **Technology evaluation:** "What's the best tool for this job?"

---

## What This Skill Does

This skill provides systematic library evaluation through:

1. **Research 6 dimensions** - Official docs, recent updates, alternatives, security, community, codebase usage
2. **Score with evidence** - Each dimension rated 1-10 with specific supporting data
3. **Synthesize decision** - Clear ADOPT/MIGRATE/UPGRADE/STAY/AVOID recommendation
4. **Deliver decision brief** - Scannable report with TL;DR, decision matrix, action items
5. **Time-boxed process** - Complete research in ~40 minutes (vs 2-4 hours ad-hoc)

See Instructions section below for detailed step-by-step workflow.

---

## Instructions

### Phase 1: Gather (15 minutes)

**Goal:** Collect evidence across 6 research dimensions

**Steps:**

1. **Context**: Read `pyproject.toml` for existing libraries and Context7 IDs
2. **Docs**: Get official docs (check pyproject.toml first, then resolve-library-id)
3. **Updates**: WebSearch for recent changes, changelogs
4. **Alternatives**: WebSearch for comparisons, discussions
5. **Security**: WebSearch for CVEs, advisories
6. **Community**: WebSearch on reddit, HN, GitHub, StackOverflow
7. **Codebase**: Search current usage patterns

### Phase 2: Synthesize (10 minutes)

**Goal:** Transform evidence into clear decision

**Steps:**

1. **Score each dimension** (1-10) with specific evidence
2. **Identify decision driver** (what matters most?)
3. **Determine recommendation** (ADOPT/MIGRATE/UPGRADE/STAY/AVOID)
4. **Assess confidence** (High/Medium/Low)
5. **List action items** (what happens next?)

### Phase 3: Write (15 minutes)

**Goal:** Create scannable decision brief

**Steps:**

1. **TL;DR**: Write last, summarize the decision
2. **Decision Matrix**: Fill in scores and evidence
3. **Recommendation**: State decision and rationale
4. **Action Items**: Specific, assignable tasks
5. **Supporting Evidence**: Details for skeptics
6. **References**: Links for deep dive

**Total time: ~40 minutes** (vs 1-2 hours of ad-hoc research)

---

## Core Principles

### 1. **Readability First**
- ❌ Walls of text, data dumps, exhaustive lists
- ✅ Scannable sections, bullet points, clear structure
- ✅ Executive summary fits in one screen
- ✅ Each section answers ONE question

### 2. **Decision-Focused**
- Every fact must support a decision
- If it doesn't change the recommendation, cut it
- Lead with "SO WHAT?" not "WHAT?"
- Clear action items, not observations

### 3. **Confidence Over Completeness**
- Better to be 80% confident with 6 sources than 60% with 20 sources
- Quality of sources > quantity
- Synthesize, don't concatenate

### 4. **Time to Value**
- Reader should know the recommendation in 30 seconds
- Supporting evidence in 3 minutes
- Full context in 10 minutes
- Everything else is noise

---

## Usage Examples

### Example 1: Adoption Decision

**Scenario:** User asks: "Should we use Pydantic v2 for data validation?"

**Process:**
1. Research 6 dimensions: docs, updates, alternatives, security, community, codebase
2. Score each dimension with evidence
3. Synthesize into decision brief

**Outcome:**
```
📋 TL;DR
Recommendation: ✅ ADOPT
Confidence: High (8/10)
Key insight: Production-ready, 20x faster, easy migration

🎯 Decision Matrix: 8.2/10 overall
🚀 Action Items: POC this week, migrate next month
```

**Time:** ~40 minutes (vs 2-4 hours ad-hoc research)

---

### Example 2: Migration Decision

**Scenario:** User asks: "Should we migrate from Neo4j to Memgraph?"

**Outcome:**
```markdown
📋 TL;DR
Recommendation: ❌ STAY
Confidence: High (8/10)
Key insight: Neo4j meets needs, migration cost high, unclear benefit

🎯 Decision Matrix:
| Dimension | Neo4j | Memgraph | Winner |
|-----------|-------|----------|--------|
| Functionality | 9/10 | 8/10 | Neo4j |
| Performance | 8/10 | 9/10 | Memgraph |
| Maturity | 10/10 | 6/10 | Neo4j |
| Migration Cost | N/A | 3/10 | Neo4j |

🚀 When to Reconsider: If query performance drops below SLA
```

---

### Example 3: Security Audit

**Scenario:** User asks: "Audit our dependencies for security issues"

**Outcome:** Security report for each dependency with:
- CVE status (none found / issues identified)
- Latest version check
- Upgrade recommendations
- Priority ranking (critical/high/medium/low)

---

## Research Framework (6 Dimensions)

### 1. **Official Documentation** (Context7)
**Question:** Does it do what we need?

- Check `pyproject.toml [tool.context7]` FIRST for existing library ID
- If not found, use `resolve-library-id`
- Focus search on specific use case (e.g., "async patterns", "performance tuning")
- Extract: capabilities, limitations, best practices

### 2. **Recent Developments** (WebSearch)
**Question:** Is it actively maintained and improving?

- Last 6 months of updates (use current year from env)
- Changelog, release notes, roadmap
- Breaking changes, deprecations
- Extract: momentum, stability, future-proofing

### 3. **Alternatives** (WebSearch)
**Question:** Is this the best tool for the job?

**Sources:**
- General: `best {category} 2025 comparison benchmark`
- Head-to-head: `{lib} vs {alternative} 2025` (db-engines.com, github.com)
- Community: `{lib} vs {alternative} discussion` (reddit.com, news.ycombinator.com)

Extract: competitive positioning, trade-offs, deal-breakers

### 4. **Security** (WebSearch)
**Question:** Is it safe to use?

**Sources:**
- CVEs: `{lib} CVE vulnerability 2025` (nvd.nist.gov, snyk.io)
- Advisories: `{lib} security advisory 2025` (github.com)

Extract: known vulnerabilities, security track record, response time

### 5. **Community Health** (WebSearch)
**Question:** Will we get support when we need it?

**Trusted sources:**
- **reddit.com**: Real-world experiences, gotchas, war stories
- **news.ycombinator.com**: Technical discourse, deep dives
- **github.com**: Issues, PRs, responsiveness, contributor activity
- **stackoverflow.com**: Common problems, solutions, adoption

**Searches:**
- Adoption: `{lib} adoption trends 2025`
- Experiences: `{lib} experiences 2025` (reddit.com)
- Discussion: `{lib} discussion 2025` (news.ycombinator.com)
- Issues: `{lib} pr