compare-tools

Files (5)

• SKILL.md
• evals.json · evals/
• priority-catalogue.md · references/
• report-template.md · references/
• rubric.md · references/

SKILL.md (first lines)

# Compare Tools

Help the user pick the right technology for a specific use case. The output is a grounded,
auditable recommendation — not a generic listicle, but a score derived from *this codebase's*
shape and *this user's* stated priorities.

## Operating principles

- **Codebase first.** Technology decisions are context-dependent. Understand what's already here
  before evaluating what might be added.
- **Priorities are the rubric.** Don't rank tools on your own taste. Derive the ranking from the
  user's stated priorities weighted against observed options. Show the arithmetic.
- **Push back when it matters.** If a stated priority contradicts the observed codebase (e.g.
  "avoid vendor lock-in" in a repo already deep in AWS), name that tension and ask them to
  reconcile. Don't push back reflexively — only when the conflict is real and material.
- **Research, don't invent.** Don't claim a tool has a feature unless you can verify it. If
  unsure, say so or omit the claim.
- **One question at a time.** Use `AskUserQuestion` for every clarification. Never batch
  questions — each answer may change what you ask next.

---

## Phase 1 — Alignment

### 1a. Explore the codebase

Read the following in order, stopping when you have enough to write a one-paragraph
characterisation:

1. `README.md` and `CLAUDE.md` (or `CLAUDE.local.md`) — project intent and conventions
2. Top-level `docs/` if it exists
3. Dependency manifests — whichever of these exist:
   - `package.json` / `package-lock.json` (Node/TS)
   - `pyproject.toml` / `requirements.txt` (Python)
   - `go.mod` (Go)
   - `Cargo.toml` (Rust)
   - `Gemfile` (Ruby)
4. Recent git log: `git log --oneline -20`

Characterise the codebase in one paragraph: *type of project, primary language/runtime,
what's already installed, who it's for, what it does.* Surface this so the user can correct
a wrong framing before the research phase.

### 1b. Confirm the use case

State your understanding of what the user wants to choose a tool for and ask them to confirm
or correct it. If the use case is under-specified — "I need a database", "pick a queue",
"something for caching" — invoke the `grilling` skill to resolve the decision tree:
scale, read/write mix, latency, hosting constraints, team familiarity, existing
infrastructure, etc. Skip `grilling` if the use case is already crisp.

### 1c. Elicit priorities

Present a short list of common high-level priorities from `references/priority-catalogue.md`
and ask the user to pick 3–5 that matter most to them, then rank them. Use `AskUserQuestion`
— one question at a time. Rankings become the rubric weights in Phase 3.

Good default priorities to offer:
- Community support
- Maintenance activity
- Avoiding vendor lock-in
- Extensibility / composability
- Ecosystem fit (language + framework)
- License
- Performance
- Learning curve
- Cost
- Operational burden

### 1d. Sensible push-back

After the priorities are in, check them against what you observed in Phase 1a. If a stated
priority contradicts the codebase:

- **Real conflict**: "You said 'avoid vendor lock-in', but the repo already uses AWS Secrets
  Manager, CloudWatch, and S3. Adding a vendor-neutral queue would be swimming upstream — is
  that still the goal, or should we score SQS more favorably?" Ask via `AskUserQuestion`.
- **No conflict**: say nothing. Don't manufacture friction.

---

## Phase 2 — Research

Use `WebSearch` to survey the market. Aim for **4–7 candidates** covering:

- The mature/default choice (the boring, safe option)
- 1–2 newer or popular challengers
- At least one left-field option that could win on the user's specific priorities
- Any option already in the dependency manifests (it may already be installed)

For each candidate, record:

| Field | What to capture |
|-------|----------------|
| One-liner | What it is in one sentence |
| Strengths | Primary advantages, typical use cases |
| Weaknesses | Known pain points, limitations |
| Maintenance | Last release date, release cadence, # of active maintainers |
| License | MIT / Apache / GPL / commercial / etc. |
| Doc URL | Canonical documentation URL |

Don't invent features or claims. If you can't verify something, note "unverified" or omit it.

---

## Phase 3 — Output

### Resolve the output path

```bash
mkdir -p ./ideas
DATE=$(date -u +%Y-%m-%d)
SLUG="<short-kebab-case-topic>"   # e.g. "job-queue", "vector-db", "state-manager"
BASE="./ideas/${DATE}-tech-${SLUG}"
OUT="${BASE}.md"; N=2
while [ -e "$OUT" ]; do OUT="${BASE}-${N}.md"; N=$((N+1)); done
echo "$OUT"
```

From O-Marsters-1997/my-claude-code, MIT.

More from O-Marsters-1997/my-claude-code