git:20261001.6b161d2 to git:20261003.2de3c0b

---

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

deepline auth register --wait auto

deepline -h

```

```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>"

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.

## Product friction feedback

is disproportionately slow, appears stuck through repeated status checks, or an

ordinary result requires avoidable product steps. Continue the user's task after

Use judgment rather than a fixed threshold. Do not report normal provider work

just because it is not instant. Report when the duration is surprising for the

input size or prior comparable runs, progress stays uninformative, or the path

needs avoidable discovery, conversion, ID extraction, retry, export, or manual

workaround steps.

Include the goal and Play/run ID. For latency, include input size, observed

duration, status transitions or polling count, and expected progress. For excess

steps, include the actual path, avoidable detours, and expected direct path. Do

not pass `--requested` for a proactive report. Omit `--error-outcome` when no

error occurred; if an error did occur, use `terminal` only when it stopped the

task and `continued` when work continued.

```bash

deepline feedback send "Goal: <goal>. Play/run: <play and run id>. Friction: <what was slow or indirect>. Observed: <duration, polling, or actual steps>. Expected: <reasonable duration, progress, or direct path>."

```

## 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.