deepline-plays-review

Files (3)

• SKILL.md
• openai.yaml · agents/
• review-sheet-presentation.mjs · scripts/

SKILL.md (first lines)

# Review and Improve Deepline Plays

## Quick Start

```bash
npm install -g deepline
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.

Loop: `revision → run → assess → decide → next revision`. Google Sheets is the
human review surface; the Play revision, completed run, and durable dataset
remain the execution record.

## Route the request

| User intent                          | Start here                                     |
| ------------------------------------ | ---------------------------------------------- |
| Put a run in a Sheet                 | Export the completed dataset for review        |
| Address edits, notes, or comments    | Read fresh feedback and run one revision       |
| Make feedback a standing rule        | Record a general expectation                   |
| Never regress on a corrected case    | Add a case-specific expectation or golden case |
| Compare revisions                    | Evaluate both against one frozen basis         |
| Try several improvements             | Establish a bounded agent-driven loop          |
| Keep improving together across turns | Resume the loop and yield after each candidate |

**Stop at planning boundaries.** When the user asks for a plan,
classification, or proposed evaluation before any calls or edits, write it
from the supplied context and stop. Do not inspect live Plays, runs, files, or
tool contracts, even through read-only commands: exploration cannot grant
missing authority or define a budget, and it can start paid work. Resume
discovery only after the user asks to proceed.

To only build, run, or debug a Play, use `deepline-plays`; for unrelated
spreadsheet manipulation, use the relevant spreadsheet workflow. This skill
begins when a result will be reviewed, measured, or used to change the Play.

## Establish or resume the loop

- **Revision:** the Play version under test.
- **Run:** that revision executed on known inputs.
- **Expectation:** what good means, generally or for a specific case.
- **Assessment:** evidence about how a run met an expectation.
- **Golden dataset:** a versioned collection of representative inputs with
  case-specific expectations.
- **Evaluation:** a reproducible assessment of one revision against a fixed
  basis.
- **Optimization:** permission to repeat the loop, not a new kind of evaluation.

Before changing the Play, state or recover: the objective; baseline revision
and run; applicable expectations; human-stepped or agent-driven control;
allowed changes; budget and stopping rule; and run, dataset, spreadsheet, and
tab breadcrumbs.

Default to one candidate and then yield. Trying multiple candidates spends
credits and can move farther than the user intended, so first require explicit
authority, mutation scope, budget, and a stopping rule.

Work in a durable directory: files in `/tmp` disappear along with the evidence
needed to resume. Set `WORKDIR="deepline/data/<descriptive-slug>"` and run
`mkdir -p "$WORKDIR"`.

Tool names in this skill are starting hints. Discover the live Workspace tools
and confirm their contracts before first use:

```bash
deepline search "Play run dataset -> spreadsheet" --type tools
deepline search "spreadsheet ID -> its rows and comments" --type tools
deepline describe google_workspace_export_dataset
deepline describe google_workspace_request
```

## Run and review

Run the Play and keep its completed run ID. When provider calls are involved,
pilot on one or two rows before scaling, so a wrong payload or output shape
does not waste credits across every candidate. Preserve source and status
columns: they explain why a row passed or failed. Then inspect the completed
run and choose the durable dataset the user wants to review:

```bash
deepline runs get "$RUN_ID" --full --json > "$WORKDIR/run.json"
jq -e '
  .datasets | if type != "array" then error("Expected datasets array") else .[] end |
  if (.datasetId | type) != "string" or .datasetId == "" then error("Missing dataset identity")
  else {datasetId, name, table: .storage.table, rowCount} end
' "$WORKDIR/run.json"
```

The CLI returns a `run_overview`: datasets are at `.datasets` and raw
diagnostics (including billing) at `.diagnostics`. Raw SDK/API responses use
`package.datasets` and `billing`; do not apply those paths to CLI JSON. Set
`DATASET_ID` to an advertised `datasetId`; the export tool accepts it directly.
If the dataset list or identity is missing or malformed, stop and retrieve
valid run evidence instead of guessing `result.rows`.

Export the persisted dataset, never CLI preview rows, which are only samples.
Use one operation key for one intended export; reuse it only to retry that
exact request. Leave `SPREADSHEET_ID` empty for a new workbook, or set it to
append a new immutable run tab to an existing workbook:

```bash
: "${SKILL_DIR:?Set SKILL_DIR to the installed deepline-plays-review directory}"
: "${RUN_ID:?Set RUN_ID to a completed Play run}"
: "${DATASET_ID:?Set DATASET_ID to the selected datasets[].datasetId}"
TAB_LABEL="${TAB_LABEL:-Results}"
SPREADSHEET_TITLE="${SPREADSHEET_TITLE:-Play review}"
EXPORT_OPERATION_ID="${EXPORT_OPERATION_ID:-review-$(date -u +%Y%m%dT%H%M%SZ)}"
PRESENTATION="$(node "$SKILL_DIR/scripts/review-sheet-presentation.mjs")"

EXPORT_INPUT="$(jq -n \
  --arg run_id "$RUN_ID" \
  --arg dataset_id "$DATASET_ID" \
  --arg spreadsheet_id "${SPREADSHEET_ID:-}" \
  --arg spreadsheet_title "$SPREADSHEET_TITLE" \
  --arg tab_name "$TAB_LABEL" \

From getaero-io/gtm-eng-skills, MIT.

More from getaero-io/gtm-eng-skills