# Skill: Research

## Mô tả
Skill này giúp **tìm kiếm và phân tích repo mẫu** trên GitHub trước khi triển khai. Thay vì "nghĩ từ đầu", chúng ta học hỏi từ những gì đã có, tiết kiệm thời gian và tránh lỗi phổ biến.

## Khi nào sử dụng
- User đưa yêu cầu nhưng chưa rõ cách làm nhanh nhất
- Cần tìm patterns, architectures đã proven
- Muốn so sánh các approaches khác nhau
- Cần tìm libraries/tools phù hợp

## Workflow

### Phase 1: Parse Requirements
1. Đọc `intake.md` để hiểu context
2. Extract keywords cho search
3. Xác định tech stack constraints

### Phase 2: GitHub Search
1. Tạo search queries thông minh
2. Tìm repos phù hợp (stars, recent activity, license)
3. Filter theo language/tech stack
4. Rank theo relevance

### Phase 3: Deep Analysis
1. Phân tích cấu trúc thư mục của top repos
2. Xác định patterns được dùng
3. Tìm hiểu technologies và dependencies
4. Ghi nhận anti-patterns cần tránh

### Phase 4: Summarize
1. Tổng hợp shortlist các repos hay nhất
2. Recommend architecture/patterns
3. Liệt kê lessons learned
4. Xuất output chuẩn

## Output Format

### File: `output/research/shortlist.json`

```json
{
  "query": "original search context",
  "timestamp": "2024-01-22T00:00:00Z",
  "intake_source": "output/intake/intake.md",
  "repos": [
    {
      "rank": 1,
      "name": "owner/repo-name",
      "url": "https://github.com/owner/repo-name",
      "stars": 5000,
      "forks": 500,
      "last_updated": "2024-01-15",
      "description": "Short description from GitHub",
      "language": "TypeScript",
      "license": "MIT",
      "relevance_score": 0.95,
      "technologies": ["React", "Next.js", "Prisma"],
      "patterns_found": [
        "monorepo with turborepo",
        "feature-based folder structure",
        "server components"
      ],
      "strengths": [
        "Well documented",
        "Active maintenance",
        "Good test coverage"
      ],
      "weaknesses": [
        "Complex setup",
        "Heavy dependencies"
      ],
      "notes": "Good example for enterprise-scale apps"
    }
  ],
  "summary": {
    "total_repos_analyzed": 50,
    "shortlisted": 5,
    "recommended_stack": {
      "frontend": "Next.js with App Router",
      "backend": "tRPC or Next.js API Routes",
      "database": "PostgreSQL with Prisma",
      "deployment": "Vercel"
    }
  }
}
```

### File: `output/research/patterns.md`

```markdown
# Research Patterns Report

## Context
- **Project**: [from intake]
- **Search Date**: [timestamp]
- **Repos Analyzed**: [count]

---

## Recommended Architecture

### Pattern: [Name]
- **Source**: [repo link]
- **Why it fits**: [reasoning]
- **Implementation notes**: [how to apply]

### Folder Structure
```
src/
├── app/           # Routes (Next.js App Router)
├── components/    # Reusable UI
├── lib/           # Utilities
├── services/      # Business logic
└── types/         # TypeScript types
```

---

## Technology Recommendations

### Frontend
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| Next.js | SSR, App Router, Vercel | Learning curve | Yes |
| Vite + React | Fast dev, simple | No SSR | For SPAs |

### Backend
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| tRPC | Type-safe, fast | Next.js specific | Yes |
| Express | Flexible | More setup | No |

### Database
| Option | Pros | Cons | Recommended? |
|--------|------|------|--------------|
| Prisma + PostgreSQL | Type-safe ORM | Schema migrations | Yes |
| Drizzle | Lighter | Newer | Alternative |

---

## Code Patterns

### 1. [Pattern Name]
**Source**: [repo]
**Usage**: [when to use]

```typescript
// Example code from repo
```

### 2. [Pattern Name]
...

---

## Anti-patterns to Avoid

1. **[Anti-pattern]**: [why it's bad, found in repo X]
2. **[Anti-pattern]**: [why it's bad]

---

## Dependencies Worth Noting

| Package | Purpose | Stars | License |
|---------|---------|-------|---------|
| package-name | Description | 10k | MIT |

---

## Next Steps

1. Clone [recommended repo] as reference
2. Adapt [pattern] for our use case
3. Create specs based on this research

---

*Generated by Research Skill | Based on [X] repos*
```

## Search Strategies

### 1. Keyword-based Search
```
# Basic search
language:typescript stars:>1000 "nextjs dashboard"

# With topic filters
topic:react topic:typescript stars:>500

# Recent and maintained
pushed:>2024-01-01 stars:>100 "auth"
```

### 2. Awesome Lists
- Tìm `awesome-*` lists liên quan đến tech stack
- Đây là curated lists với quality repos

### 3. GitHub Topics
- Browse topics: `github.com/topics/[topic]`
- Filter by language và stars

### 4. Similar Projects
- Dùng GitHub's "Used by" để tìm projects dùng cùng dependencies
- Check "Insights > Dependency graph"

## Scoring Criteria

| Criterion | Weight | Description |
|-----------|--------|-------------|
| **Stars** | 20% | Popularity indicator |
| **Recent Activity** | 25% | Maintained in last 6 months |
| **Documentation** | 20% | README, docs folder, examples |
| **Code Quality** | 20% | Structure, types, tests |
| **Relevance** | 15% | Match với requirements |

### Relevance Score Formula
```
score = (stars_norm * 0.2) +
        (activity_norm * 0.25) +
        (docs_score * 0.2) +
        (quality_score * 0.2) +
        (keyword_match * 0.15)
```

## Integration với Pipeline

### Input từ Intake
```javascript
// Đọc intake để extract keywords
const intake = readFile('output/intake/intake.md');
const keywords = extractKeywords(intake);
// => ['dashboard', 'authentication', 'react', 'typescript']
```

### Output cho Spec-Kit
```javascript
// Research cung cấp context cho specs
const patterns = readFile('output/research/patterns.md');
const shortlist = readFile('output/research/shortlist.json');
// => Dùng để tạo feature specs có grounding
```

## Lệnh thực thi

```bash
# Search GitHub với keywords từ intake
node ".agent/skills/research/scripts/search-github.js"

# Phân tích một repo cụ thể
node ".agent/skills/research/scripts/analyze-repo.js" --repo owner/repo-name

# Generate full research report
node ".agent/skills/research/scripts/generate-report.js"

# Quick search với custom query
node ".agent/skills/research/scripts/search-github.js" --query "nextjs dashboard template"
```

## Quy tắc cho AI Agent

### DO
- Ưu tiên repos có tests và documentation
- Kiểm tra license trước khi recommend
- Ghi nhận cả pros và cons
- Update patterns.md với code examples

### DON'T
- Đừng chỉ dựa vào stars (có thể outdated)
- Đừng copy code verbatim (chỉ learn patterns)
- Đừng bỏ qua security issues
- Đừng recommend repos không maintained

## Environment Variables

```bash
# GitHub API Token (for higher rate limits)
GITHUB_TOKEN=ghp_xxxxx

# Optional: Custom API endpoint
GITHUB_API_URL=https://api.github.com
```

## Rate Limiting

- **Without token**: 60 requests/hour
- **With token**: 5000 requests/hour
- **Search API**: 30 requests/minute

Always handle rate limits gracefully.

## Tham khảo
- [GitHub Search API](https://docs.github.com/en/rest/search)
- [GitHub Topics](https://github.com/topics)
- [Awesome Lists](https://github.com/sindresorhus/awesome)