Why Record Decisions and Changes?
A pharmacometric workflow develops through choices as well as calculations. A team may decide how to name run folders, which file is the authoritative input, or how a data transformation is represented. If the reason for a consequential choice exists only in a meeting or in one analyst’s memory, a later reader may be unable to tell whether an apparent difference between runs was intentional, when it began, or what it affected.
A decision log and a changelog address related but different questions. A decision log records a choice and its rationale: what was decided, when, why, and with what expected consequences. A changelog records consequential changes that were made: what changed, when it took effect, and what files, outputs, or workflow steps may be affected. Neither is a substitute for a detailed analysis report, which presents the analysis methods, results, and interpretation. The introductory material on writing a project README addresses orientation to a project; these records preserve a more specific history of choices and changes.
What Belongs in a Record?
Record a choice when a future analyst or reviewer may need to understand, reproduce, assess, or deliberately revise it. Not every edit deserves an entry. Correcting a spelling error in a temporary note is usually not consequential; changing which input dataset a modeling workflow uses may be. The practical test is whether the choice could alter the workflow, its outputs, its interpretation, or a later person’s ability to retrace the work.
A useful decision entry gives enough information to reconstruct the reasoning without turning into a report. Include a stable identifier, the date the decision was made, its status, the issue being addressed, the selected option, the main alternatives considered, the rationale, and the expected implications. Identify the responsible role or person where appropriate. If the decision depends on evidence, point to the relevant analysis, data specification, or other project artifact using a location or identifier that readers can find. A short rationale should name the evidence or constraint that mattered; “team agreed” describes the outcome of a discussion, not why the choice was appropriate.
For a change-history entry, use the date the change took effect or was introduced, and say which date it is. Describe the changed item concretely, explain the reason, and note known consequences, including whether a rerun or review may be needed. When an effect is not yet known, say so instead of implying that nothing was affected. A record can also identify who implemented or reviewed the change, if that distinction matters for the project.
| Record element | Question it answers | Useful practice |
|---|---|---|
| Identifier and date | Which entry is this, and when was it made? | Use a unique, stable label and an unambiguous date. |
| Context and decision | What issue arose, and what was chosen? | State the choice directly, rather than only describing the discussion. |
| Rationale and alternatives | Why this option rather than another? | Give the decisive reason and mention material alternatives. |
| Status and consequences | Is this current, and what does it affect? | Mark proposed, accepted, superseded, or withdrawn; state implications. |
| Evidence or artifact reference | Where can the supporting detail be examined? | Point to a findable project artifact without copying its contents. |
Worked Example: Recording a Run-Folder Convention
Hypothetical project. On 2026-03-04, a team notices that two analysts have been saving runs under names that do not identify the configuration used. The team chooses a standard name containing a run label and a date.
A concise decision entry could read: DEC-004, accepted, 2026-03-04. Context: run folders created by different analysts cannot be reliably distinguished by name. Decision: new run folders will use the pattern “run label_YYYY-MM-DD”; the configuration file remains inside each run folder. Alternatives considered: retain free-form names, or include the full model description in every folder name. Rationale: a consistent date and run label make folders easier to identify, while keeping long descriptions in the configuration avoids unwieldy names. Effect: apply the convention to new runs; existing folders are not renamed. Reference: the project’s run-naming specification.
This entry records the decision, its scope, and its reason. It does not restate the full specification or claim that earlier run folders were changed. The distinction between “new runs” and “existing folders” prevents a reader from assuming a retrospective conversion occurred.
From a Decision to a Change History
A decision record documents what should happen; a change-history entry documents what did happen. They may be linked, but they need not be identical. A choice can be recorded before implementation, and implementation can occur later. Conversely, a change may be a routine correction that does not require a separate decision record. When both records are useful, link them with the decision identifier so a reader can follow the rationale to the implementation.
Worked Example: Documenting an Implemented Change
Hypothetical project. The team has accepted DEC-004, and on 2026-03-06 an analyst updates the project instructions and uses the convention for a new run folder.
A change-history entry could read: 2026-03-06 — Implemented DEC-004. Updated the run-folder instructions to use “run label_YYYY-MM-DD” for new runs and created the new run folder as “base_2026-03-06.” Existing folders were not renamed. The configuration for this run is in that folder. No prior run outputs were regenerated by this naming change.
The entry names the changed artifact, connects the action to the decision, and states the scope and effect. The statement about outputs is appropriately limited: it says that this naming change did not regenerate earlier outputs, not that the run itself has been independently validated.
A short justification for this structure follows from the questions a later reviewer must answer. To understand a workflow change, the reviewer needs to identify the change, locate when it took effect, learn why it was made, and determine what it touched. If one of those pieces is missing, the reviewer must infer it from other material or ask someone who may no longer be available. Linking an entry to the relevant detailed artifact supplies evidence without copying the artifact’s analysis into the log. Thus, a concise record can preserve the trace from context to choice to implementation to consequence, while leaving technical detail in the appropriate project file.
Worked Example: Updating a Superseded Decision
Hypothetical project. On 2026-04-10, a team records DEC-011: the processing workflow will read the cleaned dataset from “inputs/cleaned.csv.” On 2026-04-18, the team finds that the designated input is being replaced with a clearly identified, controlled dataset file.
The original entry should remain visible, with its status changed to superseded and a reference to the replacement decision. A new entry could read: DEC-014, accepted, 2026-04-18. Context: the prior input designation does not identify the controlled dataset file now used by the workflow. Decision: configure the workflow to read “inputs/analysis_dataset.csv.” Rationale: this path identifies the file designated for analysis in the updated data specification. Effect: update the input configuration and rerun affected processing from that input; earlier outputs remain historical outputs unless separately regenerated. Reference: the updated data specification and the change-history entry dated 2026-04-18.
Keeping the superseded entry makes the sequence interpretable: the new choice did not silently erase the old one. The record also avoids claiming that all downstream results have already been regenerated. The changelog can state when that work is completed, if and when it occurs.
Writing Entries That Remain Useful
Use dates in a consistent, unambiguous format, such as YYYY-MM-DD. If a choice was made on one date but became effective later, label both dates rather than leaving readers to guess. Distinguish fact from expectation: “the change requires downstream outputs to be rerun” is different from “downstream outputs were rerun.” Record uncertainty and pending work explicitly, then update the status when the situation changes.
Keep entries concise, but not cryptic. “Changed input” is too vague: it does not identify what changed or why. “Updated the configured input from the earlier cleaned dataset file to the file specified in the revised data specification” is more informative, especially when paired with the exact paths and a reference. Avoid unexplained abbreviations and descriptions such as “latest,” which become ambiguous as files change. Prefer identifiers and dates that can be interpreted later.
Do not quietly rewrite history when a choice is revised. Mark the old decision superseded or withdrawn, link the replacement, and record the effective date of the new choice. If a record was entered late, retain the actual decision or implementation date and indicate the entry date as well. This preserves an honest timeline instead of making a retrospective record appear contemporaneous.
Ask whether the choice could affect workflow execution, inputs, outputs, interpretation, or traceability. Record it if a later reader would need its history.
Name the selected option or implemented action, its date, scope, and status. Do not leave the central choice implicit in meeting notes.
State the decisive rationale and important consequences, then point to supporting detail. Keep full analyses in their appropriate reports or project artifacts.
When implementation occurs or a decision changes, add or update the relevant status and link the related entries without obscuring the earlier record.
Diagnostics, Alternatives, and Limits
A decision log is failing when entries consist mostly of unexplained outcomes, when a reader cannot tell whether a decision is current, or when the rationale is only “it was agreed.” A changelog is failing when it says “updated files” without naming them, when it records a reason but not an effect, or when it implies that downstream work was completed without evidence. Review a sample of entries by asking whether a new team member could identify what changed, when, why, and what to inspect next. If the answer requires private knowledge, add the missing information or a findable reference.
These records complement rather than replace several other forms of documentation. A README introduces the project and helps with onboarding; a decision log explains consequential choices; a changelog summarizes material changes over time; a detailed analysis report explains methods and findings. Meeting minutes preserve discussion more broadly, but may not make the adopted decision and its rationale easy to locate. A ticket or task tracker can coordinate work, but is not necessarily a durable account of why the workflow took its current form. Teams may link these artifacts, provided the essential decision or change remains clear in the log itself.
There are limits to what a log can establish. A recorded rationale is not proof that a decision was scientifically appropriate, and a changelog is not evidence that an implementation was correct or that results were independently checked. Records can also become unwieldy if every minor edit is included. Set a practical threshold around consequential workflow choices, and use references for technical detail. Consistent structure and periodic review matter more than length.
Check Your Understanding
Answer each question, then compare with the brief solutions.
- A team changes the designated dataset input but writes only “input updated.” What important information is missing?
- A decision was made on 2026-05-02 and implemented on 2026-05-05. Which dates should the records show?
- Why should a superseded decision generally remain discoverable?
- Does a changelog entry stating that a processing script changed establish that downstream outputs were regenerated? Explain.
- A spelling correction in a temporary note has no workflow effect. Must it be recorded in the changelog? Explain the significance test.
Solutions. (1) Name the old and new input, the reason, the effective scope, known or expected effects, and a useful reference. (2) Record the decision date in the decision entry and the implementation date in the changelog; label both clearly. (3) It preserves the sequence and allows readers to understand what was previously in force and when it was replaced. (4) No. The entry establishes only that the script changed; regeneration must be recorded or evidenced separately. (5) Usually not. Record changes that a future reader may need to understand or retrace because they affect workflow, outputs, interpretation, or traceability.