The evidence network
The notebook's links let you recover a paper's evidence, see what shaped an experiment, and find which conclusions a correction affects. Each relationship is recorded in the file responsible for maintaining it.
Read the network
A claim is an assertion tracked with its evidence in the claims ledger. An experiment can contribute to several claims, and a claim can depend on several experiments. More than one paper can use the same evidence. Findings explain how results fit together; the measurements remain in experiment records. Keeping measurements there avoids correcting separate copies in each paper's private notes.
Illustrative map: every ID, result, and connection below is synthetic. This is a teaching example, not a live notebook view.
- →Cites evidence: claim cites an estimand; estimand links to its run and artifact.
- ⇢Informed design: prior observation shaped a later choice.
- ↝Requires renewed review: amendment changes what must be checked, not claim validity by itself.
- ↦Paper mapping: the claim has a role in the named paper.
Full evidence map: relationship types and synthetic examples
The map separates evidence citations from design lineage and renewed-review obligations. Select a claim or estimand to trace cited quantities, illustrative run/artifact examples, and papers; choose a corrected estimand to see which records need reassessment.
How to trace claimsClaim-promotion workflowEstimand record sectionRuns and artifacts section
Correction follow-throughRepair workflowRun/artifact evidence section
Recover design historyDesign decisions sectionExperiment record structure
Key traces in this example
- C1 cites EXP-101:E1 and EXP-103:E1, reaching RUN-101 /
summary.csvand RUN-103 /results.csv; it maps to Paper A. - C2 cites EXP-103:E1 and maps to Paper B. If EXP-103:E1 is corrected, reassess both C1 and C2 and their papers; EXP-101:E1 is a separate cited quantity and is not changed by that correction.
- EXP-101's observed length pattern informed EXP-102's design. A threshold amendment requires renewed review of the dependent analysis script. That review obligation does not automatically invalidate a scientific claim.
Keep shared evidence in its experiment record. Use each claim row's paper key to connect that assertion to its publication. Paper-specific wording and scope can differ while the underlying measurements remain the same. Reusing a measurement across papers does not create another independent replication; publication and disclosure rules still apply.
Record what each link means
“This result informed the design” and “this result supports the claim” are different relationships. Record that meaning in the file responsible for maintaining the link, and check it when following the link.
| Relationship | What it means | Where to read or write it |
|---|---|---|
| Experiment → question | The test addresses this inquiry, whether its answer is positive, negative, or still unavailable. | The experiment's research-question metadata. |
| Plan → experiment | This test belongs to a work packet (a piece of work with defined limits) or a phase of the plan. | The plan's phases and completion evidence. |
| Experiment → prior evidence | These observations or sources affected the design or an amendment. | The experiment's Informed by section. |
| Plan or experiment → what settled a choice | This choice between credible options was made for this reason, at this cost, after seeing this evidence. | A dated entry in the record's Decisions log. |
| Experiment → run and artifacts | These attempts and outputs implement the test and supply its observations. | The experiment's runs table, methods, and artifact records. |
| Finding → experiments | A synthesis draws on several tests and explains their joint implications. | The finding's evidence links; an experiment's finding pointer is a convenience. |
| Claim → estimands | An estimand is a quantity the experiment aims to estimate. Its result is the evidence to assess for this assertion. | The claim ledger's Evidence cell, with references such as EXP-103:E1. |
| Claim → paper | This assertion has a role in this paper's argument. | The claim row's Paper cell; PUBLICATION.md locates the manuscript and packets. |
| Experiment → follow-up | An outcome makes another test worth considering, subject to its gate and approval. | The upstream experiment's decision rule or follow-ups. |
A finding can add synthesis or correction context to a claim's evidence cell, but it does not replace direct experiment evidence. A scientific gate is a precondition for interpreting another quantity. Citing a passed gate alone cannot establish the main scientific result.
Trace a paper claim back to the work that supports it
Start with the paper key in PUBLICATION.md and locate its claim rows.
Read the exact claim sentence and scope, then follow each estimand citation to its
experiment. Check the observed result, predictions, scientific gates, limitations, and
registration history. The experiment's runs and artifacts take you to the underlying work.
If the argument combines several results, read the linked finding as well. For the fictional retrieval project, an overall comparison and a long-document test may justify different statements. A summary claim must preserve those distinctions: a narrower result does not establish an overall improvement.
The validator reports a citation that does not resolve. A citation that resolves to inadequate evidence passes the validator and has to be caught in review. The claim-promotion workflow guides the assessment of that evidence. The paper workflow connects reviewed claims to the manuscript and its submission versions.
Recover why an experiment was designed that way
Follow Informed by when asking how a metric, threshold, subgroup, or next test
was chosen. That section records the information available to the designer, including
exploratory plots and summaries received from collaborators or agents. A code revision
identifies the implemented threshold; it does not establish whether the threshold was
selected before or after looking at outcomes.
In the retrieval example, EXP-102 investigates a length pattern seen in EXP-101. EXP-103 later tests the selected hypothesis on independent evidence. Both descendants retain their information history.
To find the plan that commissioned an experiment, search its ID in the notebook and read the matching plan phase. The plan owns that connection; the experiment need not maintain a competing list of every plan and claim that uses it. See the different uses of research plans for the decisions these connections organize.
Follow a correction to every affected record
When a check changes an experimental result, state the superseded value beside the correction in that experiment. Search for its ID and the old values across the notebook. These searches find plans, findings, and claims that refer to the result, including references in prose that a link validator cannot recognize.
Assess each dependency. A correction to EXP-103:E1 would require revisiting both C1 and C2 in the diagram, then the corresponding papers. It need not invalidate every other quantity in EXP-103 or every conclusion in either paper. Record what changes and what remains supported.
Update claims and add correction pointers or superseding findings. A terminal plan retains its original passage with a retraction notice beneath it. Update the main manuscript and submission packets still in preparation. Preserve submitted snapshots and record any required correction or revision action separately. The repair workflow gives the steps.
Keep each relationship in its responsible record
Record a relationship when it becomes known: when a plan creates an experiment, when observations influence a design, when a job is submitted, or when a claim is recorded. Maintain each link in the file responsible for it. Indexes, searches, and visualizations can reconstruct other views without requiring a second database maintained by hand.
Run the notebook validator after structural changes and keep review decisions with the evidence they evaluate. Validation can check supported link and registration conventions. Review still needs to assess whether an estimate warrants a claim, whether all design influences were disclosed, and whether the artifacts suffice for reproduction.
The published notebook graph convention specifies which records maintain each relationship. For exact formats, use the experiment reference, plan reference, and claim ledger reference. Return to the workflow overview to choose the next task.