# Reference-Repo Competitive Audit Methodology

## When to use

Use this when the user provides a list of GitHub repos (or URLs) and asks you to study them for patterns, features, architecture, or UI/UX that should be adapted into their own project. Common triggers:

- "Look at these repos and convert it for us"
- "Audit these apps and tell me what to copy"
- "Research how X app does Y and adapt it"
- "Compare our app against [list of repos]"

## The 4-Phase Process

### Phase 1: Mass Clone & Structure

Clone all repos shallow (`--depth 1`) in parallel to a temp directory. Extract structure stats: file count by extension (shows framework at a glance), package manager file (reveals dependencies/scripts/build system), README first 2000 chars, and top-level directory listing (reveals monorepo structure).

### Phase 2: Deep Inspection

For repos that pass the structure filter (relevant to your target platform):
1. List all source files in the app directory
2. Read key architectural files: navigation/routing, theme/design system, main screens, state management, API/auth layer
3. Read the most visually interesting screens: hero, cards, search, player

### Phase 3: Pattern Extraction & Rating

Rate each repo 1-5 on: UI quality, navigation, loading states, error/empty states, search, player, settings, auth flows, backend/API. Identify the single best pattern from each repo.

### Phase 4: Clean-Room Adaptation Plan

For each pattern: name it, describe it, identify source + target files, note what's safe to adapt vs unsafe, assign priority (P0/P1/P2).

## Deliverable Templates

When the user asks for formal deliverables:
```
docs/audit/
├── DELIVERABLE_1_CURRENT_APP_AUDIT.md
├── DELIVERABLE_2_REFERENCE_COMPARISON_MATRIX.md
├── DELIVERABLE_3_FINAL_UIUX_DESIGN_PLAN.md
├── DELIVERABLE_4_5_MENU_AND_FEATURE_PLAN.md
└── DELIVERABLE_6_7_BACKEND_AND_IMPLEMENTATION_PLAN.md
```

## Pitfalls

- **Don't spend equal time on every repo.** Triage early — a 13-file vanilla HTML app doesn't deserve the same depth as a 300-file Next.js app.
- **Don't read every file.** Focus on the 5-10 most architecturally significant files per repo.
- **Don't copy code verbatim** unless license permits AND the user directs it. Describe the pattern, not the implementation.
- **Don't skip the comparison matrix.** Cross-repo comparison shows consensus patterns vs unique innovations.
- **The user may say "ignore licenses."** This is their call. Note it and proceed, but flag embedded API keys or hardcoded secrets that should NOT be copied regardless.