Workbooks and worksheets

Understand the workbook and worksheet model

A workbook is the container. A worksheet is the working surface inside it: it has one row source, rows from that source, columns that expose or derive evidence, and an optional score. A row source is not shared across worksheets. Keeping one source per worksheet makes the origin of a row inspectable when the source or its filters change.

Use separate worksheets when the row kinds are different. For example, a Companies worksheet can prove a hiring or funding signal, while a linked People worksheet can hold the people to contact at qualifying companies. Do not put a person name in a company cell. People are rows in the People worksheet, with a link to the company row that supplies the qualifying evidence.

Architect can read the current workbook and worksheet records before it changes anything. The workbook list returns headers rather than worksheets or row counts. The worksheet list is scoped to one workbook, returns worksheets in workbook_position order, and also does not return columns, rows, or counts. Those reads are free and read-only.

Create the right starting shape

Creating a workbook always creates its first worksheet in the same operation. The first worksheet is required, so there is no empty workbook state. The operation can also create worksheet columns and rows in the same all-or-nothing call, but it attaches no row source and starts no run. Its policy is a free, internally reversible draft write.

The creation result includes workbook_id, worksheet_id, and table_id. The worksheet and table identifiers are the same UUID at this point. Keep the returned table_id: later column, row, and cell operations use it. The result also includes created column keys and ids, row ids, a default view id, and workbook and first-worksheet records.

To add a second worksheet, use the worksheet creation capability against the existing workbook. It creates only the worksheet, with no columns, source, or rows. The returned record includes its workbook position, name, row kind, description, timestamps, creator, and archive state. That is also a free, internally reversible draft write.

Design the data chain before running it

Start with four facts: the list purpose, what makes a row qualify, what disqualifies it, and which criteria are required rather than nice to have. Architect reads the request and saved company context, then turns intent into observable evidence. A vague term can have broad and narrow readings, so resolve that difference before choosing a source.

Choose the source that can carry the scarcest criterion or strongest signal. Put each stated criterion into the source input that supports it. A place belongs in a location filter, a title belongs in a title filter, and a size belongs in a size filter. A criterion left out of the inputs is not applied. A guessed filter value can still return rows, which is why a successful run is not proof that the rows are correct.

When the qualifying signal lives on a company but the outcome is outreach to people, plan both worksheets from the beginning. First sample companies that carry the signal. Then use the company rows to find people, preserving the company link. The title a company is hiring for belongs on the company search; the titles of people to contact belong on the people search. Mixing those roles can produce an apparently successful but incorrect result.

Build one layer at a time. Attach and sample the source first. Next add catalog enrichments and judgments that decide qualification. Add derived formulas, projections, or scores after the evidence they use exists. A derived column before its input has nothing to show and hides whether the earlier step worked.

Sample before you scale

A first batch is a sample to review, not a finished list. The list-building skill uses a small sample of about twenty-five rows, reads the entities, and can compare two or three parameter variants before retaining the most precise one. The goal is for most sampled rows to be right at the source, rather than relying on expensive downstream checks to repair a broad search.

After a source or column run starts, follow it until it finishes and read the cells it wrote before adding the next layer. A status read that times out does not change the run and does not prove failure. A queued or running run should be read again rather than restarted. When the sample is correct, scale the same source to the requested count. If no count was stated, the skill uses 100 rows as its default target.

Cost control comes from sequence. Use cheap and selective evidence before expensive contact data. Run paid lookups only for rows that passed the qualifying column. An estimate is a ceiling, while the amount charged is read from the finished run. A count observed before a run finishes is unknown, not zero.

Read the workbook back

A write is a request. A read back is the evidence that the request produced the intended result. Do not report a worksheet as landed, enriched, judged, or scored until the relevant run is finished and the worksheet has been read. Counts alone are insufficient because a computed count can still be unknown.

Read representative rows in full. Report answered, empty, and failed cells separately. An empty or failed value is not zero, and a missing provider answer is unknown rather than false. Do not copy a value from a similar row to fill a missing one. Let the column run settle the cell so the evidence trail remains intact.

Before calling the work complete, confirm the source run, landed count, duplicate count, and enrichment runs. Read at least three rows in full, inspect empty cells in key columns, and check duplicates on the identifier that defines the entity, such as a company domain or person profile URL. If the user asked for people, confirm that the linked People worksheet exists and holds rows from qualifying companies.

Use the diagnostics skill when a result is unexpected. Queued, paced, capped, and unknown states are not automatically failures. An empty, failed, or unrelated cell can indicate a missing input, wrong field reference, or wrong setting. Correct that cause and recheck the sample, rather than claiming that a run alone proved the result.

When the model does not match the work

If Architect cannot create a workbook because a required first-worksheet value is missing, correct the workbook request rather than retrying an unchanged call. The contract records an example refusal for an optional first_worksheet.declared_mixed_row_kinds value sent as null: optional values that are not being set should be omitted. A malformed request can also hide a later mode error, so fix the capability input first.

If a planned source cannot run because an account is missing, keep the workbook and source binding. Missing credentials block the run, not workbook or source authoring. If the rows are broad, wrong, or empty, inspect the source inputs and landed sample before adding columns. Do not create a duplicate worksheet merely to retry a filter.

If two worksheets carry the same entity and decision, consolidate the plan before continuing. A Companies worksheet and People worksheet are different because their rows and source chains are different. Two company worksheets with the same source and criteria create competing evidence trails and make later readback ambiguous.

Archive is not deletion. An archived workbook drops out of default lists, while its worksheets, columns, rows, and cells survive; a list with archived records included can still find it. There is no workbook unarchive capability in this family, so read the workbook before archive if you need its current state. Use archive only when retiring the whole workbook is the intended outcome.

• Read a workbook record when you need its metadata but not its worksheets or counts.
• Read the workbook overview when the workbook and its worksheets are both needed.
• Read the worksheet list before a worksheet-specific change resolves its identifier.
• Read cells after a finished run when the result, rather than the request, matters.