skills/freckle/REFINE.md

# Work on an Existing Workflow or Workbook

The target already exists and its design is the brief. This route covers operational work such as adding a Dataset or rows and running them, as well as scoped setup changes. There is no plan cycle: locate, inspect, pin, act, verify.

**Fit test:** stay here when the target exists and the request can be completed from its current design plus sensible, reversible defaults. A new Dataset inside a named Workbook is still existing-target work. Escalate to [BUILD.md](BUILD.md) only when the request changes the artifact's overall purpose or requires unresolved choices that alter Workflow shape, providers, outputs, destination, or run behavior. A missing target is a lookup failure, not permission to invent a new one.

Messages speak to a GTM audience, not developers: plain language, translate programming jargon.

## Path

1. **Locate.** Extract ids from Freckle URLs: the id is the path segment right after `workbooks` for a Workbook or after `tools` for a Workflow, wherever those segments appear — org-scoped links read `/<org-slug>/workbooks/<id>` and `/<org-slug>/tools/<workflow-id>`. Check auth and list orgs, then derive the target's org without asking: use `workflow saved list --all` for a Workflow; for a Workbook, run `workbook list --org-id=<org-id>` across accessible orgs. When only a Dataset id or label is named, scan both `workbook list --org-id=<org-id>` and `workbook list --org-id=<org-id> --archived` across accessible orgs, then run `workbook dataset list <workbook-id> --org-id=<org-id>` for each candidate Workbook until the Dataset id or label matches; Datasets have no global lookup, so the match supplies the containing Workbook and org. On one match, use that Active Organization and continue silently. Ask about org only after zero or multiple matches, showing the lookup result rather than an unfiltered org-choice ritual. After automatic resolution or user selection, append `--org-id=<org-id>` after the complete subcommand path of every subsequent CLI command. Do not use `org switch`; it writes shared global config that another agent can overwrite.
2. **Inspect before proposing.** Workflow: `workflow saved inspect <workflowId>`, then export its draft following the help pointer in [cli-reference.md#saved-workflows](workflow/cli-reference.md#saved-workflows). Workbook: `workbook inspect <workbook-id>` ([WORKBOOKS.md](WORKBOOKS.md)). For an enrichment edit, trace its selected input Dataset back through Push to Dataset and inspect the producing Workflow so upstream providers are known. Also note every connection reading the target Workflow (`workbook list` rows show `workflowId`; add `--archived` to cover archived Workbooks) — that is what a revision touches.
3. **Pin the change.** Infer intent from the request and inspected artifact. Choose sensible defaults for low-impact details such as fake values and labels. When the target is ambiguous or unresolved choices change shape, providers, outputs, destination, or run behavior, apply the [shared batch grill](SKILL.md#shared-operating-rules) to every currently unblocked decision in one round: lead it with the [what-will-run summary](SKILL.md#shared-operating-rules) for this change, then the numbered questions, including any question the target's reference file requires (the Signal lookback question in [SIGNALS.md](SIGNALS.md#one-round-then-create), for example). The user's answers are the approval; act on them in the same turn. Otherwise proceed immediately — no todo ceremony, diagram, plan table, objective interview, or approval pause.
4. **Act, contract-first.** For data-only work, follow [WORKBOOKS.md](WORKBOOKS.md) and preserve the Workbook's existing wiring unless asked to change it. For Workflow edits, inspect the full catalog entry of any node you add or reconfigure (`workflow node inspect <definitionKey>`); read [waterfall.md](workflow/waterfall.md) for enrichment provider, ordering, or fallback edits, and read [apollo-find-people.md](workflow/apollo-find-people.md) or [push-to-dataset.md](workflow/push-to-dataset.md) when applicable; preview dynamic nodes after config changes; read `freckle workflow draft validate --help` and validate the edited draft successfully, then publish to the existing Workflow using [cli-reference.md#saved-workflows](workflow/cli-reference.md#saved-workflows). Mappings, unfold, and output labels are immutable, so a mapping change means a new connection on the same input Dataset.
5. **Verify the blast radius.** If the Workflow's input shape changed, inspect each connection and its input Dataset catalog, compare the mapping with the new input schema, and tell the user which connections will reject — verify by inspection, in keeping with "Run only when asked". If the output shape changed, output Dataset catalogs do not update themselves — new fields need `dataset catalog replace` to show as columns.
6. **Run only when asked.** When the user wants rows run, read and apply the [sample gate](workflow/cli-reference.md#sample-gate), then use [WORKBOOKS.md#pending-and-triggering](WORKBOOKS.md#pending-and-triggering) for connection commands or [cli-reference.md#run-saved-workflows](workflow/cli-reference.md#run-saved-workflows) for direct runs. For a specific sample use `connection run <entry-id...>`; for the oldest pending rows use `connection trigger --limit <n>`; admission is not completion, so follow accepted run ids with `workflow saved runs watch`/`inspect`.

**Completion** — every box checked:

- [ ] The change is applied and validated.
- [ ] The user is told what changed and what it touches — connections, output columns.
- [ ] Any requested runs went through the sample gate.