Skip to main content
A Collection is not a spreadsheet. It is the operational substrate: a configured table whose records read the team’s Knowledge before anyone works them. This guide works a single record the right way, reading the collection’s criterion first, so the update reflects the team’s criteria instead of a fresh guess. The example is a pipeline collection where each record is an account. Read it as a lead, a customer, a content item, or a product signal: the shape is the same, only the configuration differs.

​
Outcome

One record advanced with the team’s criteria applied: the criterion Knowledge read first, the confirmed fields updated, and the status changed only because the underlying state changed, not because the workflow reached a step.

​
When to use it

  • You are working a record in a pipeline, an analysis, or a content collection and want to apply the team’s recorded criteria, not improvise.
  • The same real-world identity shows up in more than one collection and you want it understood as one Entity.
  • You want to keep operational state where it belongs while escalating any finite follow-up to Work.

​
Availability and prerequisites

ItemState
Collections, records, entities (CLI, MCP, REST)Available
retrieve (records plus criterion in one call)Available
collection context (criterion only)Available
distill_policy as a configuration fieldAvailable (it declares intent; it is not an automatic runtime)
You need the CLI installed and logged in. Over MCP or OAuth, collection, record, and entity writes require the work:write scope; reads and collection doctor are member-level.

​
Objects involved

ObjectRole in this workflow
CollectionThe configured table: record_schema, stages, views, criterion.
RecordOne typed row; its status is validated against the collection’s stages.
EntityA cross-collection identity records point at, deduped on (kind, dedup_key).
CriterionThe Knowledge Topics the work reads before acting (criterion_rel_slugs).
CardWhere finite follow-up work belongs, a separate primitive.

​
Before you begin

Find the collection you mean to work, and confirm the workspace. 
driftless workspace current
driftless collection list --status active

​
Context preflight

The seam that makes a Collection more than a table is its criterion: the criterion_rel_slugs that resolve to the Topics the team wants read before a record is worked. Read them before you evaluate anything. Two ways to pull it, depending on whether you also want the records: 
driftless collection context <collection-id>                      # criterion only
driftless collection retrieve <collection-id> --status qualified --limit 25   # records plus criterion
retrieve returns { records, nextCursor, criterion, criterion_missing }. If criterion_missing lists a slug that does not resolve, that is a gap: the collection points at Knowledge that does not exist yet. Close it with a Note or a Topic (see Govern agent learning) rather than working the record blind. Do not pull the whole workspace; the criterion is the scoped context this collection asked for.

​
Step-by-step workflow

1

Resolve the Collection and read its shape

Read the archetype, schema, stages, views, and criterion relations before touching a record. The stages are the only statuses a record may sit in.
driftless collection get <collection-id>
2

Read the criterion, then pull the relevant records

Load the team’s “how we do this” first, then the records to work.
driftless collection retrieve <collection-id> --status qualified --limit 25
Read criterion before you read the records. It is the difference between working with the team’s judgment and working from scratch.
3

Resolve or create the Entity

If this account also appears in another collection, tie the records to one identity. An Entity upserts idempotently on (kind, dedup_key), so re-adding the same pair updates it instead of creating a duplicate.
driftless collection entity add --kind company --name "Globex" --dedup globex.com
You should get back an <entity-id>. An Entity is not a row in a collection; it is a separate identity that records point at.
4

Resolve the Record

Find the specific record and read its current fields and status.
driftless collection records <collection-id> --status qualified
driftless collection record get <collection-id> <record-id>
5

Evaluate, then update confirmed fields

Judge the record against the criterion and its current state, then write only the fields you can confirm. Link it to the entity while you are here.
driftless collection record update <collection-id> <record-id> \
  --fields '{"owner":"me","next_step":"schedule review"}' \
  --entity <entity-id>
6

Advance status only when the state actually changed

A status is a claim about reality. Move the record to a new stage only because the underlying thing changed, never because the workflow reached this step.
driftless collection record update <collection-id> <record-id> --status engaged
The status is validated against the collection’s own stages; a value outside them is rejected.
7

Escalate finite follow-up to a Card

If the record needs bounded work (reconcile a duplicate, run an analysis, draft a reply), that belongs in Work, not in the record. Reference the record by id; there is no formal record-to-card link to invent.
driftless project card add <project-id> \
  --title "Reconcile Globex duplicate records" \
  --description "Record <record-id> in <collection-id> may duplicate an existing entity"
Same surface over MCP: driftless_collection action:'retrieve', driftless_collection_record action:'update', and driftless_entity action:'upsert'. Over REST it is GET /workspaces/:slug/collections/:id/retrieve and the record and entity routes under the same base. See API: Collections, Records, and Entities.

​
Expected states

MomentWhat you should see
After collection getThe archetype, record_schema, stages, views, and criterion.
After retrieve{ records, nextCursor, criterion, criterion_missing }.
After entity addAn <entity-id>; re-adding the same (kind, dedup_key) updates, not duplicates.
After a field updateThe record carries the new fields and its entity_id.
A status outside the stagesRejected with 400 VALIDATION_FAILED.

​
Knowledge write-back

Most of what you touch here is operational state, and it should stay that way. Escalate deliberately:
  • The record’s own values stay in the Record. That is operational state, not Knowledge.
  • Finite follow-up becomes a Card. It is Work, not a durable why.
  • A reusable observation (a pattern in how these records behave, a rule that keeps recurring) becomes a Note. Capture it, do not inline it into the record.
  • A durable why worth the whole team trusting (how this collection should be worked) may become Knowledge, but only after a person reviews it.
driftless note add --content "Accounts stalled in qualified for 30+ days are usually mis-scored, not lost"
driftless context propose <slug>    # later, if it proves durable and reviewed
A single record’s outcome is not Knowledge. The recurring pattern behind many records might be, once reviewed.

​
What not to do

  • Do not invent a terminal status. Never set won, published, signed, completed, validated, deposited, or committed unless that thing actually happened. A status is a claim, and an agent writing it is making the claim.
  • Do not treat a Collection as an isolated table. Read the criterion first; that is the whole point of the substrate.
  • Do not confuse Entity and Record. A Record is a row in one collection; an Entity is an identity across collections. Deduplicate identities on the Entity, not by editing rows.
  • Do not promote a single record’s result into Knowledge. Operational outcomes live in the record; only a reviewed, durable pattern becomes a Topic.
  • Do not invent a record-to-card relation. Reference by id; no typed link between them is shipped.

​
Troubleshooting

  • A field write returns 400 VALIDATION_FAILED. The field is not in the collection’s record_schema, or its value is the wrong type. Read the schema with collection get and match the field keys and types.
  • A status change is rejected. The status is not one of the collection’s declared stages. A record can only sit in a stage its collection defines.
  • A duplicate entity appeared. You used a different dedup_key (or none). The upsert is idempotent on (kind, dedup_key); use the stable key consistently.
  • Something looks off across records. Audit the collection before relying on it:
driftless collection doctor    # records off-lifecycle, schema violations, drifted, orphaned entities

​
Limits and truth states

CapabilityState
Collections, records, entities on all three surfacesAvailable
retrieve and collection context (the criterion seam)Available
Entity dedup on (kind, dedup_key)Available
distill_policy as a configuration fieldAvailable (declares intent)
Automatic execution of distill_policy at record closeNot available (not an automatic runtime)
A typed relation between a Record and a Card or ProjectNot available