--- name: evidence-citation description: How to report findings so they can be cited — writing evidence to files before asserting it, choosing where outputs belong, describing what each artifact shows, and returning findings with machine-checkable evidence pointers. Use when you are a specialist producing analysis for the CSO, before writing your final response, or when deciding whether a result needs to be saved. --- # Evidence Citation ## Why this exists Your findings become claims in the CSO's answer to the user. Each claim is clickable: a reader opens it and sees the table, figure, code line or tool call behind it. The CSO can only build that from what you hand it, and **it must not invent citations** — the system rejects evidence pointers that do not resolve. So a finding you report without evidence is one the CSO has to present as unsupported. Everything below is about making sure that does not happen to work you actually did. ## 1. Write it down before you assert it A number that exists only in your prose cannot be cited. Before stating a result, save the thing that shows it: | You want to say | Save | |---|---| | "highest in mast cells" | the per-cell-type table | | "L2G score 0.75" | the credible-set table you read it from | | "expression is bimodal" | the plot | | "no black-box warning" | the query result | This is not bookkeeping. If the only record of a result is a sentence, nobody can check it, and in six months neither can you. ## 2. Put it in the right place You have your own directory. Use the layout: ``` work// ├── code/scripts/ analysis scripts you write ├── data/raw/ data as pulled from a tool or database ├── data/processed/ data after your QC / transformation └── results/ ├── figures/ plots (.png, .pdf) ├── tables/ result tables (.csv, .tsv, .parquet) └── reports/ your written findings (.md) ``` Absolute paths, always. Do not write into another specialist's directory or into the run root. **Name for content, not sequence.** `il33_celltype_expression.csv`, not `analysis2.csv`. `gwas_credible_sets_chr9.parquet`, not `cs_2fd0.parquet`. Every file you leave behind is something a human has to interpret without you there. ## 3. Say what each output shows The system records every file you write automatically — you do not need to do anything for an artifact to exist. What it cannot infer is what the file *demonstrates*. For each output that carries a finding: ```python register_artifact( path="results/tables/il33_celltype_expression.csv", description="Mean IL1RL1 expression per lung cell type across 12 donors; " "mast cells highest at 2.4 CPM") ``` One line. What is in it, and what it shows. ## 4. Return findings with evidence attached Structure your response to the CSO so each substantive finding carries its evidence: ``` FINDING: IL1RL1 is most highly expressed in lung mast cells (mean 2.4 CPM, 3.1x the next-highest cell type). EVIDENCE: results/tables/il33_celltype_expression.csv (row: mast cell) results/figures/il33_celltype.png CONFIDENCE: strong — direct measurement, n=12 donors, consistent across 3 datasets FINDING: Expression in cardiac tissue is low but non-zero. EVIDENCE: results/tables/il33_critical_organs.csv (rows: cardiac_*) CONFIDENCE: moderate — only 2 donors with cardiac tissue; wide CI ``` Paths relative to your own directory are fine — the CSO resolves them. If a specific tool call is the evidence (an MCP query whose result you are reporting directly rather than a file you wrote), give its `tool_use_id`. ## 5. Report what you could not establish If a query failed, returned nothing, or the evidence is too thin to support a conclusion — that is your result. Say it: ``` NOT ESTABLISHED: Cardiac expression could not be assessed. The Census query for heart tissue returned 0 cells after QC filtering. Retried with relaxed filters (min_genes 200 → 100), still 0. This gap should be closed before a cardiac safety claim is made either way. ``` An acknowledged gap is usable — the CSO can scope its answer around it, or send someone back for it. A confident claim with nothing behind it is worse than silence, because it looks the same as a supported one until someone checks. ## Checklist before you respond - [ ] Every number I state exists in a file I wrote - [ ] Files are under my own `work//` tree, in the right subdirectory - [ ] Filenames say what the files contain - [ ] `register_artifact` called for each output carrying a finding - [ ] Each finding in my response has an EVIDENCE line - [ ] Confidence stated honestly, with the reason - [ ] Anything I could not establish is stated, not omitted ## Anti-patterns **Reporting a summary statistic without saving the underlying table.** The summary is the claim; the table is the evidence. Both are needed. **`results_final_v3.csv`.** If there are three versions, either two are dead — delete them — or they differ in a way the filename should say. **Burying the finding in a long narrative.** The CSO extracts claims from what you return. A clearly delimited FINDING/EVIDENCE/CONFIDENCE block survives that extraction; a paragraph where the result is in the fourth sentence may not. **Overstating confidence to sound useful.** `moderate` with an honest reason is more useful than `strong` that a reviewer later has to walk back.