# GEOmend workflow and review guide for agents

Use this document to choose a workflow, locate the canonical instructions, and preserve
the distinction between suggestions, saved opinions, imported reviews, and output values.
Call `geomend capabilities --json` first. It is offline and reports the installed
release's commands, schemas, input types, and mutation boundaries.

## Produce a project table

Use `geomend project create SOURCE... --project PROJECT` for GSE accessions, family-SOFT
files, CSV/TSV, or a supported manifest. Export with
`geomend project exports table PROJECT --mode best_guess --profile analysis --output metadata.tsv`.
This can include unreviewed executable suggestions. Read `metadata.columns.tsv` for
units, codes, component definitions, and status; retain `metadata.context.tsv` for extra
metadata. `--mode reviewed` uses reviewed mappings but keeps the sample roster even
when reviewed cells are blank. Resume stopped processing with `project inputs run PROJECT`.

Inspect fields and actual values before changing a match. `project mappings candidates`
returns the best guess, alternatives, current/reviewed choices, and previews. Preview
and select with that page's revision and pool hash. Preserve rationale and attribution;
do not automatically select the first-ranked option. Inspect ontology links separately
from variable grouping and transformation approval.

Project tutorial: https://prestonraab.github.io/geomend/project/
Export semantics: https://prestonraab.github.io/geomend/project-exports/
Advanced controls: https://prestonraab.github.io/geomend/project-reference/

## Prepare or complete fixed-evidence review

For reconciliation, run `geomend reconcile plan SOURCE... --output-dir PLAN`, read the
plan, and resolve blockers in `reconcile.yaml`. Satisfy target/ontology prerequisites
before `reconcile run`. Planning is offline; offline execution requires cached or local
inputs and target evidence. Source-derived target drafts remain proposals until curated.
Planning and running do not accept mappings.

If assigned a packet, open the `.geomend-review.zip` directly with `review queue`, then
`review model PACKET CASE`. Do not create another workspace. Expand fixed evidence with
`review evidence`, full case detail, or source detail. Compare sources with scoped stable
IDs; aliases such as `P1/S1` identify items only within that packet or workspace view.

Check meaning, scope, units, reference events, and representation before accepting.
Use `accept` with exactly one variant or a nonempty subset of source IDs, `nomatch`
when no selectable target in this case applies, and `defer` when evidence is insufficient.
Preview before saving. Recording requires an evidence-based rationale. Use `review judge`
for the full judgment payload, including fixed citations and ideas; `--submit` saves it.

Saving writes a portable response; coordinator `review import` adds its complete opinion
set to the workspace. Keep the response and original packet together. For a moved
response, lightweight commands accept `--evidence-packet ISSUED_PACKET`; SDK reopening
uses `ReviewerClient(RESPONSE, evidence_packet=ISSUED_PACKET)`. The hash must match.
Use `review progress RESPONSE --json` to recover saved answers. Return the generated
response when the assignment is complete; never hand-edit its records.

Canonical protocol: https://prestonraab.github.io/geomend/reviewer-protocol/
Client limits and retries: https://prestonraab.github.io/geomend/reviewer-client-contract/
Scientific meaning checklist: https://prestonraab.github.io/geomend/metadata-representation-vocabulary/

## Compare opinions and export a selected view

Comparison retains separate attributed opinions and does not choose a mapping. A
synthesis must incorporate all required active opinions. Derivation applies a declared
policy to fixed evidence without changing current mappings. Export a derived view only
by selecting its ID explicitly. Agreement cannot waive target/transformation readiness.

`geomend export data STATE OUTPUT_DIR` uses reviewed, export-eligible mappings; this
release's native reviewed values use identity materialization. An empty reviewed dataset
requires explicit `--allow-empty`. Audit export retains evidence and review history in a
validated BagIt bundle. These formats differ from project tables.

Transformations use native LinkML-Map specifications and separate validation, approval,
and execution records. Keep raw values, hashes, scope, units, qualifiers, and endpoint
status. Do not invent midpoints, category probabilities, missingness mechanisms, or
equivalence from labels. Optimizer scores rank suggestions and are not correctness probabilities.

Exports: https://prestonraab.github.io/geomend/native-review-export/
Curation: https://prestonraab.github.io/geomend/curation-contracts/

## Recover and report failures

JSON errors contain code, message, remediation, and object-valued details. Exit codes:
2 invocation, 3 incomplete input, 4 environment, 5 acquisition, 6 validation, 7 internal.
Refresh stale revisions, pools, or snapshot preconditions and inspect the relevant state
before retrying. Preserve source metadata and use only supported CLI, SDK, or
authenticated API operations for scientific decisions; direct SQLite writes are unsupported.

Troubleshooting: https://prestonraab.github.io/geomend/troubleshooting/
Source: https://github.com/prestonraab/geomend
