deepline-plays

---
name: deepline-plays
description: 'Use for Deepline GTM work that searches, enriches, scores, collects signals, or automates a workflow: find companies or people, enrich a CSV, find emails or LinkedIn, compare providers, build a waterfall, create a webhook or cron, or write a Play. For live information work, run a small heterogeneous experiment, exploit the observed winner, and reopen misses. Skip pure copywriting and non-GTM research.'
---

# Deepline Plays

## Quick Start

```bash
npm install -g deepline
# Fallback for secure sandboxes: mkdir -p "$HOME/.local" && npm config set prefix "$HOME/.local" && export PATH="$HOME/.local/bin:$PATH" && npm install -g deepline --registry https://code.deepline.com/api/v2/npm/
deepline auth register --wait auto
deepline auth wait --timeout 120 # completes Cowork/browser approval; no-op if already connected
deepline auth status
deepline -h
```

## CLI resolution

Run `deepline` when it is available. If the shell reports that command is missing, use `<workspace-root>/.deepline/runtime/bin/deepline` (or the npm-created `.cmd` shim on Windows). If neither exists, follow `https://code.deepline.com/INSTALL.md` to set up Deepline.

**Debug every Play run:** use `deepline plays run <file.play.ts> --input '<json>' --debug` while iterating, or `deepline runs logs <run-id> --debug` for an existing run. `completed` means the runtime finished, not that an external destination accepted the result; the debug logs retain caught non-2xx `ctx.fetch` responses with their key, method, destination origin, and HTTP status.

Before the first Deepline fanout in a task, run `deepline preflight --json` as
one standalone command and wait for it to finish. Never submit preflight beside
another Deepline command. After it succeeds, prefix every Deepline command that
may run concurrently with `DEEPLINE_SKIP_SELF_UPDATE=1`; serial commands may
stay bare.

```text
contract → compare → exploit → recover → export → price
```

Ordinary TypeScript, no DSL. A `SearchProgram` is one function that calls a tool,
a fetch, a child Play, a connector, or a local artifact and returns a typed
attempt. `runSearchExperiment` owns the pilot, ranked waterfall, holdout,
gap-only retries, and cost/coverage report.

## Deliverable

| Part                | Contents                                                                |
| ------------------- | ----------------------------------------------------------------------- |
| **Result line**     | rows in / accepted / marginal credits per accepted row / run id         |
| **CSV**             | the user's exact headers, per-claim source, `miss_reason` on every null |
| **Unresolved rows** | in the same file; a null carries an absence receipt                     |
| **Route table**     | initial and final waterfall, cost and completions per route             |
| **COST RECEIPT**    | the block `run-and-export-search-experiment.py` prints, verbatim        |
| **Next actions**    | dormant routes and what each would buy, at measured cost deltas         |

- Marginal, never amortized. Total ÷ successes reported 1.51 credits/email for a
  route whose real marginal cost was 0.21.
- Pass the printed block through. Do not recompute credits in prose.
- A catalog ceiling stops the run; it is not spend. Label it. A 120-credit
  ceiling truncated recovery at ~12 credits actual, and two apparent logic
  regressions were budget artifacts.

## Read one job page

Read the row that matches this job, and only that row. Each page is complete for
its job: source geometry, route ladder, pilot sizing, stop conditions.

| The job                                         | Page                  |
| ----------------------------------------------- | --------------------- |
| Companies or people that are not rows yet       | `jobs/finding.md`     |
| Columns to fill on rows you already have        | `jobs/enriching.md`   |
| Claims that need attributable evidence          | `jobs/researching.md` |
| A trigger, review gate, or external side effect | `jobs/automating.md`  |

Two lookups, consulted on a trigger rather than read up front:
`shared/authoring.md` for Play syntax outside the scaffold, and
`references/debugging.md` for a failed, empty, or misshapen run.

For every public `definePlay`/`ctx.*` type, binding, durable-cache rule, and
runtime error, read `references/sdk-reference.md`. It is generated from the
authoring contract and SDK source; do not duplicate that surface in this skill.

**If your configuration forbids subagents, say so before starting serial work.**
Resolving that conflict silently cost one run ~30 minutes.

## Topology

Write `unit + decision + required facts + scale` before touching tools.
Requested fields stay required; demoting one to promote a run is not a pass. A
null needs an absence receipt: materially different routes tried, typed outcomes
retained.

One shape. **Known rows:** one experiment over the supplied rows. **Open-world
discovery:** rows are query/page/geography/registry partitions, never remembered
companies. **Company → person:** two sequential stages, not consensus; only
`companyExperiment.finalResults` become contact rows. **End-to-end:** compare
only when every program produces the same complete final row from the same seam.

## Catalog

```bash
deepline tools search "<information role and controls>" --json
deepline tools grep "<substring>" --json   # ranked search has returned the same
                                           # irrelevant hits for three different queries
deepline tools list <returned-category> --json
deepline tools describe <tool-id> --json | python3 <skill-root>/scripts/show-declared-getters.py
python3 <skill-root>/scripts/show-declared-getters.py "$WORKDIR/<tool-id>.json"   # saved contract
```

`tools describe` is the authoring contract and can disagree with runtime: a
declared getter has been absent, and a tool documenting one scalar has returned a
full list. Bind a named declared `playExpression` and sentinel-probe one row
before scaling. `toolResponse.raw` is for an exact source excerpt, debugging, or
an undeclared field after that probe — never a cast into an invented `Company[]`.

Cover source classes before provider names — index, SERP, primary document,
registry, event feed, first-party data, aggregator, validator. Two vendors
reaching the same terminal corpus are one evidence lineage.

Record each route's pricing basis: per call, per returned result, or unknown. A
confirmed-uncharged miss justifies a broader challenge wave, not a narrower one.

## Build and run

```bash
python3 <skill-root>/scripts/scaffold-search-experiment.py \
  ./deepline/data/<task-slug> --name <task-slug> --input-csv <rows.csv>
```

Read its printed `next` list: it carries the four seams, `tools: [...]`,
`coherenceChecks`, and the company→person handoff at the point you edit them.
`--input-csv` also writes a stratified `fixture.csv`. Iterate route code against
that; use the full cohort only for a scored run.

Keep the top-level `definePlay` description short and concrete. The UI shows it
below the Play identifier. Catalog categories are derived from the registered
tools used by the Play; do not author category metadata on the Play itself.

```bash
deepline billing balance --json
python3 <skill-root>/scripts/run-and-export-search-experiment.py \
  ./deepline/data/<task-slug>/<task-slug>.play.ts --input '{}' --out ./results.csv
python3 <skill-root>/scripts/cost-receipt.py <run-id> --scorecard <scorecard>.csv  # already-run
```

`run-and-export` does the structural check, Play check, completed Play, run-bound
export of both the results dataset and the route scorecard, then the COST
RECEIPT. Its `{ok: true, runId, output}` is the completion receipt: before it the
work is a probe, and a CSV written from remembered values hides which route won.

Receipt labels:

- **CUT CANDIDATE** — spent credits, completed nothing. Cut it. One route at 3.95
  credits/call, 200× a search, ran ten rounds for zero results because the
  scorecard reported no cost at all.
- **NEVER REACHED** — never invoked, so its zero results are not a ceiling and not
  a source miss. `maxFallbacks` bounds the dependency-closed waterfall and
  defaults to 2; raise it (up to 4, scaled to pool size) or drop the route.
- **cached calls** — reruns of the same inputs reuse tool receipts. Quote the
  marginal rate, not this run's total.

Quality gates precede economics; among valid results prefer fewer observed
credits, then fewer calls. Never expose provider spend.

Reusing a route across jobs is an eval, not a score: freeze the contract,
verifier, cases and ceiling, and stratify the case set (normal, sparse,
likely-miss, collision-prone) rather than picking easy rows after seeing results.
A concept is an information geometry, never a vendor.

## Subagents

One or two, only when several source geometries are plausible: same contract, one
source lane each, returning a strategy card and ordinary TypeScript. The parent
binds, runs, and judges. Verification fans out the same way — four defects found
in four sequential rounds of eyeballing output fit in one pass over row batches.