Try: Structured Library Exploration

You are exploring a library the user wants to evaluate. Your job is to bridge the gap between a too-simple quickstart and full codebase integration. You will:

1. Set up an isolated workspace
2. Discover the library's real API surface (not just what the README shows)
3. Write small, runnable scripts that each prove ONE primitive works
4. Write a composition script that wires primitives together
5. Document everything in Tutorial.md with an honest verdict

Keep this scoped to disposable exploration only. Do not refactor or integrate the target library into the user's production repository during this skill.

Invocation Patterns

The user will say something like:

• /try ComposioHQ/agent-orchestrator
• /try https://github.com/some/repo — help me build X
• explore langgraph, I want to understand the state machine primitives
• kick the tires on better-auth

They may optionally provide:

• A screenshot or context about what they want to build
• A specific angle ("focus on the streaming API")
• A constraint ("I need this to work with Bun")

Phase 0: Setup

WORKSPACE SETUP
───────────────
  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │ User says    │     │ Clone repo   │     │ Create       │
  │ "/try X"     │────>│ into         │────>│ scratch/     │
  │              │     │ /tmp/try-X/  │     │ workspace    │
  └──────────────┘     └──────────────┘     └──────────────┘

1. Determine the target: Parse the repo URL, package name, or shorthand.
2. Clone or install into an isolated directory:
   • GitHub repo → git clone --depth 1 into /tmp/try-<name>/
   • npm package → mkdir /tmp/try-<name> && cd $_ && npm init -y && npm i <pkg>
   • pip package → mkdir /tmp/try-<name> && cd $_ && python -m venv .venv && source .venv/bin/activate && pip install <pkg>
3. Create the scratch workspace inside the clone:

   /tmp/try-<name>/
   ├── scratch/           ← your scripts go here
   │   ├── 01-<primitive>.{ts,py,js}
   │   ├── 02-<primitive>.{ts,py,js}
   │   ├── ...
   │   └── 99-compose.{ts,py,js}
   └── Tutorial.md        ← your writeup
   

If try CLI (github.com/tobi/try) is installed and the user wants filesystem isolation, use it. Otherwise, /tmp/ is fine — this is disposable exploration.

Phase 1: Recon

Goal: Understand the library's actual surface area. Do NOT start writing code yet.

RECON SEQUENCE
──────────────
  README → package.json/pyproject.toml → src/ tree → exports → examples/ → tests/

Read in this order. Stop at each step and extract:

1. README / docs/: What does the library claim to do? What's the mental model?
2. Package manifest: What are the dependencies? What does it actually export?
3. Source tree: find src/ -name "*.ts" -o -name "*.py" | head -40 — get the shape.
4. Public API: Read the main entry point (index.ts, init.py, mod.rs). Extract every public function/class/type. This is the REAL API, not the README's cherry-picked version.
5. Examples/: If they exist, read them. Note what they cover and what they skip.
6. Tests/: Read 2-3 test files. Tests reveal edge cases, expected failures, and the library author's actual mental model better than docs do.

After recon, produce a mental inventory (don't write this to a file yet, just hold it):

PRIMITIVES IDENTIFIED
─────────────────────
  1. <PrimitiveName> — what it does, one line
  2. <PrimitiveName> — what it does, one line
  ...
  N. <Composition> — how they wire together

If the user gave a specific angle ("help me build an agent orchestrator"), filter primitives to what's relevant. If not, cover the top 5-8 most important ones.

Phase 2: Primitive Scripts

Goal: One script per primitive. Each script is self-contained and runnable.

SCRIPT STRUCTURE
────────────────
  ┌─ scratch/01-<name>.ts ──────────────────────────┐
  │                                                   │
  │  // PRIMITIVE: <Name>                             │
  │  // WHAT: <one-line description>                  │
  │  // EXPECT: <what should happen when you run it>  │
  │                                                   │
  │  <minimal setup>                                  │
  │  <exercise the primitive>                         │
  │  <print/assert the result>                        │
  │                                                   │
  │  // FINDINGS:                                     │
  │  // - <what you learned>                          │
  │  // - <gotchas, if any>                           │
  │  // - <what the docs didn't mention>              │
  │                                                   │
  └───────────────────────────────────────────────────┘

Rules for primitive scripts:

• One concept per file. No script should exercise more than one primitive.
• Actually run each script after writing it. Capture stdout/stderr.
• If it fails, debug it. The failure itself is valuable intel — note it in FINDINGS.
• If the docs are wrong, note it. This is one of the main values of /try.
• Use the library's native patterns, not wrappers. You want to feel the raw API.
• Name files with numeric prefix for reading order: 01-, 02-, 03-, etc.
• Match the library's language. If it's a TS library, write TS. If Python, write Python.

After each script runs, update your mental model. Adjust the plan for remaining scripts if you discover something unexpected.

Phase 3: Composition Script

Goal: Wire 2-4 primitives together into something that resembles a real use case.

  scratch/99-compose.ts
  ─────────────────────
  // COMPOSITION: <what this demonstrates>
  // PRIMITIVES USED: 01, 03, 05
  // SCENARIO: <realistic-ish use case>

This is where you find out if the library's primitives actually compose well or if there are impedance mismatches. The composition script should:

• Use the primitives you proved work in Phase 2
• Simulate a realistic (but minimal) workflow
• Handle at least one error case
• Print clear output showing what happened at each step

If the user provided a screenshot or description of what they want to build, the composition should approximate that.

Phase 4: Tutorial.md

Write Tutorial.md in the repo root. Structure:

# Trying: <library-name>

> <one-line verdict: would you use this in production?>

## What It Is
<2-3 sentences. What problem does it solve? What's the mental model?>

## Key Primitives

### 1. <Primitive Name>
<What it does. What surprised you. Link to scratch/01-*.>

### 2. <Primitive Name>
...

## Composition
<How the primitives wire together. What worked. What was awkward.
Link to scratch/99-compose.>

## Gotchas
<Bulleted list. Things the docs don't tell you. Failure modes.
Missing features. Version issues.>

## Verdict
<Honest assessment:>
<- Maturity (alpha/beta/production)>
<- API ergonomics (1-5)>
<- Docs quality (1-5)>
<- Would I build on this? Why/why not?>
<- What I'd want to see before committing>

Execution Discipline

Throughout all phases, follow this cadence:

LOOP (per script)
─────────────────
  WRITE ──> RUN ──> OBSERVE ──> NOTE FINDINGS
    ^                                 │
    └─────── ADJUST PLAN ─────────────┘

• Write small, run often. Don't write 5 scripts then run them all.
• Capture real output. Include actual stdout in Tutorial.md findings, trimmed.
• If something takes >2 minutes to debug, note it as a complexity signal and move on.
• Don't fake it. If a primitive doesn't work, say so. The user is evaluating whether to invest time in this library. Honest signal > polished demo.

Output Checklist

Before declaring done, verify:

  ✓ scratch/ contains 3-8 numbered primitive scripts
  ✓ scratch/99-compose.{ts,py} exists and runs
  ✓ Every script in scratch/ was actually executed
  ✓ Tutorial.md exists with all sections filled
  ✓ Tutorial.md verdict is honest, not promotional
  ✓ All gotchas from debugging are captured

Edge Cases

• Repo requires API keys: Note it, mock if possible, skip if not. Don't ask the user for keys unless they offered.
• Repo is huge (monorepo): Focus on the specific package the user mentioned. Use find and grep to navigate, don't try to read everything.
• Repo is broken / won't install: That IS the finding. Write a short Tutorial.md noting what failed and bail. This saves the user hours.
• Library is for a different runtime (e.g., user wants Bun but lib is Node-only): Try it anyway, note compatibility issues.
• User provides a screenshot: Use the screenshot as context for what the composition script should approximate.