/analyze-oss

name: analyze-oss
description: |
  Analyze an open-source project from What/Why perspective (not how-it's-implemented).
  Use when the user says "/analyze-oss", "분석해줘 이 오픈소스", "이 레포 뭐하는거야",
  "analyze this repo", "what does X do", "이거 왜 쓰는거야", "이 라이브러리 분석",
  provides a GitHub URL and wants understanding, or asks to deeply understand
  an OSS project's purpose, value, target users, and usage flow.
  Clones the repo to ~/opensource-analysis/<repo-name>/ (git pull if already exists),
  dispatches parallel subagents per analysis lens, then synthesizes a What/Why-focused
  report in chat. Supports optional user-specific follow-up questions.
validate_prompt: |
  Output must contain these sections:
  - What (one-line definition + core capabilities)
  - Why (problem solved, alternatives, differentiator)
  - Who / When (target users, use cases)
  - How it's used (user-perspective flow, not implementation)
  - (If user provided custom questions) Custom Q&A section
  Output must start with "## Analyze OSS:" header.

Analyze OSS — What/Why-focused open source analyzer

Clone an open-source repo locally, analyze it through multiple lenses in parallel via subagents, and deliver a **What/Why-focused** report in chat.

The goal is **not** to produce an implementation deep-dive. The goal is to help the user quickly decide "is this what I need, and why would I use it?" and then answer any custom questions they have about the repo.

When to use

• User gives a GitHub URL and wants to understand what it is / why it exists
• User asks "what does this repo do?", "이거 뭐하는거야?", "이거 왜 쓰는거야?"
• User is evaluating whether to adopt a library
• User wants a quick intellectual onboarding to an OSS project

Input

Accept any of:

• GitHub URL: `https://github.com/owner/repo` (or `git@github.com:...`)
• `owner/repo` shorthand
• Optional custom questions appended: `analyze-oss owner/repo "X 대비 어떤지, Y 유스케이스 맞는지"`

If the URL is ambiguous, ask the user to confirm before cloning.

Execution

Phase 1 — Fetch repo

Target directory: `~/opensource-analysis/<repo-name>/`

BASE=~/opensource-analysis
REPO_NAME=<derived from URL>
TARGET=$BASE/$REPO_NAME
mkdir -p $BASE
if [ -d "$TARGET/.git" ]; then
  cd "$TARGET" && git pull --ff-only
else
  git clone --depth 50 <repo-url> "$TARGET"
fi

Notes:

• `--depth 50` keeps clone fast; enough for recent commit signals.
• If `git pull` fails (local changes, diverged), warn the user — don't force.
• Capture the absolute path of `$TARGET`; all subagents must use this absolute path.

Phase 2 — Quick recon (main agent, before dispatch)

Read these in parallel to build dispatch context (don't deep-read, just skim):

• `README*` (pick the most prominent)
• `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` (whichever exist)
• Top-level directory listing
• `docs/` top-level listing if present
• Recent 10 commits: `git log --oneline -10`

Extract: repo name, elevator pitch (if README has one), primary language, rough size.

This recon is **only** to brief subagents well — do not write the report yet.

Phase 3 — Parallel subagent dispatch

Spawn the following subagents in **one message, in parallel**. Each gets:

• Absolute path to the cloned repo
• The recon summary from Phase 2
• Instructions to read only what they need (not the whole repo)
• Instruction to return a structured markdown block

**Subagents (4 default lenses):**

1. **what-lens** — "What is this?"

• Read: README, top-level docs, package descriptions
• Produce: one-line definition (≤25 words), 3–5 core capabilities (one sentence each), the repo's own self-description verbatim if useful
• Avoid implementation detail. Stay at the "capabilities the user gets" layer.

2. **why-lens** — "Why does this exist?"

• Read: README motivation/intro sections, CHANGELOG for origin context, any `MOTIVATION.md` / `docs/why*`
• Produce: the problem it solves (in plain language), what you'd have to do without it, 2–3 named alternatives and how this differs, the distinct value proposition
• If motivation is not explicit, infer from the examples and features — but mark inferences as "[inferred]".

3. **who-when-lens** — "Who uses this, and when?"

• Read: README use-cases/examples, `examples/`, showcase/users sections, issues labeled "question" or similar for real-world usage signals
• Produce: target user personas (2–4), concrete use cases (with short scenarios), situations where you'd *not* use this / known limitations

4. **how-used-lens** — "How does a user actually use this?" (user-perspective, not implementation)

• Read: Quickstart in README, `examples/`, minimal usage snippets
• Produce: install step, minimal "hello world", typical usage flow from zero → first success (as a narrative, not code walkthrough), main interaction touchpoints (CLI? API? config file? SDK?)
• Explicitly exclude internal architecture, source-level design, class diagrams.

**If the user provided custom questions**, spawn one more subagent per distinct question:

5. **custom-Q{n}-lens** — answer one specific user question

• Brief it with the full question verbatim and the recon summary
• Tell it to read whatever files it needs (grep liberally) to answer, and to cite file paths in its answer
• If it cannot answer from the repo alone, say so — don't fabricate

Phase 4 — Synthesize

Main agent takes all subagent outputs and composes the final report in chat.

**Output template** (strict):

## Analyze OSS: <repo-name>

**Repo:** <url>  ·  **Language:** <lang>  ·  **Cloned at:** <abs path>

### What
<one-line definition>

**Core capabilities:**
- …
- …

### Why
**Problem:** <plain language>
**Without it:** <what you'd do otherwise>
**Alternatives & differentiator:** <named alternatives, 1 line each, then what makes this different>

### Who / When
**Target users:** …
**Use cases:** …
**Not a good fit when:** …

### How it's used (user perspective)
**Install:** `…`
**Minimal exam