Decision log

1 Definition and purpose of a decision log

A decision log is a structured record of choices made during a project, study, or investigation. Each entry documents not only the decision itself, but also the surrounding context—such as why the choice was made, what other options were considered, which assumptions underpinned the ruling, and who owned the call. The resulting artifact functions as a time-stamped “memory” of the work, preserving the decision trail for later reference.

1.1 What qualifies as a “decision” to log

A “decision” to log is typically any choice that meaningfully affects the scope, method, execution, or interpretation of the work. Examples include selecting an analytical approach, setting inclusion criteria, choosing data-cleaning rules, deciding on measurement procedures, or determining how to handle missing values. Smaller operational calls may also qualify if they alter downstream steps, require agreement among team members, or are likely to be questioned later.

1.2 Benefits for research transparency and traceability

Decision logs improve transparency by showing how conclusions may have been influenced by earlier methodological choices. They also strengthen traceability: a reader can follow from an outcome back to the relevant decisions, including the assumptions and constraints that shaped them. In collaborative environments, logs clarify accountability by identifying decision owners and capturing the reasoning that informed their calls.

1.3 Relationship to documentation and change logs

Decision logs complement other project records rather than replacing them. Research documentation often describes “what was done,” while decision logs capture “how and why it was chosen.” Change logs typically track modifications to documents or requirements; a decision log focuses on the rationale behind those modifications, especially when multiple stakeholders or competing alternatives are involved.

2 When to use a decision log in research

Decision logs are most valuable when methods evolve, multiple options are plausible, or outcomes could be sensitive to procedural choices. They help teams maintain coherence across time, particularly when personnel change, timelines extend, or review processes demand evidence of methodological stewardship.

2.1 Common phases of research where decisions occur

Decisions arise throughout research, often at points where uncertainty is resolved or trade-offs are made.

2.1.1 Planning and protocol design

During protocol design, teams decide on study objectives, research questions, sampling strategies, measurement approaches, and planned analyses. Logging these early decisions supports later justifications, especially when protocol amendments become necessary.

2.1.2 Data collection and preprocessing choices

Data collection decisions include instrument settings, data capture procedures, and site or batch selection. Preprocessing decisions cover cleaning rules, feature engineering, transformations, handling of missingness, and how quality controls are applied. Because these choices can change the dataset, documenting them supports interpretability.

2.1.3 Analysis and interpretation decisions

Analysis decisions include model selection, statistical assumptions, parameter settings, evaluation metrics, and how to address outliers or confounders. Interpretation decisions—such as how to frame results within the study’s limitations—also benefit from logging, since they influence what conclusions readers accept.

2.1.4 Reporting, dissemination, and archiving decisions

When preparing manuscripts, reports, or presentations, teams decide how to present methods, what figures to include, what level of detail to publish, and how to document reproducibility artifacts. Archiving decisions cover where data and code are stored, what access is granted, and what should be retained for future verification.

2.2 Projects with multiple iterations and reviewers

Projects that iterate through drafts, undergo external review, or involve multiple teams commonly produce methodological shifts. A decision log helps prevent “lost context” by recording why changes were introduced and how they align with the project’s evolving objectives.

3 Decision log structure and fields

A consistent structure enables efficient searching, comparison across time, and reliable interpretation by others. While formats vary, a good decision log includes enough fields to reconstruct the context and rationale without needing informal conversations.

3.1 Core metadata (date, owner, scope)

At minimum, each entry includes a date and an owner—who is accountable for the decision—and a scope indicating what part of the project it pertains to. Scope can be defined by protocol section, dataset subset, analysis stage, or workflow component.

3.2 Decision statement and context

The decision statement should be explicit and unambiguous, typically written as a clear “We decided to…” sentence. Context explains what triggered the decision, what problem it addressed, and what conditions were present at the time (e.g., constraints, deadlines, tool availability, data characteristics).

3.3 Alternatives considered and selection criteria

Decision logs often list the alternatives that were evaluated, even if briefly. Selection criteria describe the basis for choosing among them—such as expected performance, alignment with study objectives, feasibility, interpretability, compliance requirements, or consistency with prior work.

3.4 Evidence and references

This field captures the evidence used to justify the selection. It may include internal reports, pilot results, diagnostic outputs, literature references, or dataset summaries. Citations should be specific enough that a reader can locate the supporting material.

3.5 Risks, assumptions, and constraints

Many decisions are made under uncertainty. Recording key assumptions and constraints clarifies what must remain true for the decision to remain valid. Risks can include potential biases, failure modes, sensitivity to parameter changes, or dependencies on unavailable resources.

3.6 Impact assessment and follow-up actions

Effective logs note downstream impact—how the decision changes later steps, expected outputs, or documentation. Follow-up actions list who must implement the decision, when it will take effect, and what checks verify that execution matches the logged intent.

4 Writing decisions clearly and consistently

Clarity is central to decision logs. Entries should be written so they can be understood by someone who was not present at the time of the decision.

4.1 Describing alternatives without ambiguity

Alternatives should be named in a way that avoids vague categories. For instance, instead of “use a different method,” specifying “switch from logistic regression to a random forest classifier” or “apply median imputation rather than listwise deletion” improves interpretability and audit value.

4.2 Capturing rationale (why this choice)

Rationale should explain the decision basis, not merely restate preferences. A helpful approach is to connect the chosen option to criteria (e.g., better calibration, stronger prior alignment, lower computational cost) and to indicate what evidence supported those expectations.

4.3 Differentiating facts vs. judgments

Decision logs often combine observed information (facts) with interpretations (judgments). Separating them reduces confusion—for example, distinguishing “the pilot results showed improved stability” from “therefore the approach seems more robust.”

4.4 Maintaining consistent terminology

Teams benefit from shared vocabulary for common constructs such as “preprocessing,” “inclusion criteria,” “outlier handling,” and “protocol amendment.” Consistent naming reduces search errors and makes it easier to compare decisions across the project timeline.

5 Governance and collaboration practices

Governance practices define how decisions are made, reviewed, and recorded. Without these norms, decision logs can become incomplete or reflect personal preferences without accountable oversight.

5.1 Ownership, accountability, and review workflow

Ownership clarifies who is responsible for accuracy and completeness. Review workflow specifies how entries are vetted—such as peer review for methods, verification for data-handling changes, and sign-off for protocol-affecting decisions.

5.2 Versioning and permissions

Because projects evolve, logs should support versioning—especially when new evidence prompts reconsideration. Permissions control who can edit entries versus who can read them, balancing collaboration with integrity of the historical record.

5.3 Handling disagreements and escalation paths

Disagreements should be captured neutrally, including differing viewpoints and how the final call was reached. Escalation paths outline what happens when consensus cannot be achieved—such as involving a senior reviewer, invoking a steering committee, or pausing work pending resolution.

5.4 Stakeholder communication and sign-off

Where multiple stakeholders influence decisions, communication ensures alignment. Sign-off records who approved the decision and when, providing a reliable reference for later scrutiny and for ensuring that methodological changes are consistently implemented.

6 Linking decisions to research outputs

A decision log is most useful when it connects to the artifacts produced by the research—protocols, analyses, reports, and archived datasets.

6.1 Mapping decisions to protocol amendments

When a decision changes the protocol, the log should link to the specific amendment or protocol revision. This mapping prevents confusion between “planned” steps and “actual” steps taken under new circumstances.

6.2 Referencing decisions in methods and appendices

Methods sections and appendices can cite decision log entries where relevant. This helps readers understand why particular methods were used, especially when methodological choices differ from the original plan.

6.3 Traceability from decision to results

Traceability means that outputs can be associated with the methodological decisions that produced them. For example, a figure or model output can be linked to the logged choice of preprocessing and analysis configuration, supporting reproducibility.

6.4 Archiving and long-term accessibility

Decision logs should be archived alongside project deliverables. Long-term accessibility depends on durable storage, stable links to evidence, and preservation of formats so that future readers can interpret entries without relying on inaccessible systems.

7 Quality assurance and audits

Quality assurance ensures that decision logs fulfill their transparency role. Regular checks reduce the likelihood of missing rationale, unclear scope, or unverifiable references.

7.1 Completeness checks and templates

Templates encourage consistent entries and reduce omission. Completeness checks can verify that each log item includes date, owner, decision statement, context, and rationale, as well as evidence references where applicable.

7.2 Consistency checks across the project timeline

Consistency checks evaluate whether later decisions contradict earlier assumptions without explanation. They also verify that terminology and field usage remain stable, and that decisions are recorded under the correct scope.

7.3 Updating the log when new information arises

If new evidence changes interpretation or requires re-selection of methods, the log should reflect that evolution. Rather than overwriting, updated entries can clarify what changed, why it changed, and which prior decisions are now superseded.

7.4 Common failure modes (missing rationale, vague evidence)

Common problems include entries that state an outcome without providing reasoning, decisions that cite references without accessible detail, or entries that omit constraints and assumptions. Another frequent failure mode is logging decisions too late, after related work has already been completed and results produced.

8 Tools and formats for decision logs

Tools influence usability, searchability, and integration with other workflows. The appropriate choice depends on team size, complexity, and existing documentation infrastructure.

8.1 Spreadsheet-based logs

Spreadsheets offer straightforward structure, easy filtering, and quick adoption. They work well for small teams but can be harder to manage at scale, particularly when entries need rich links to evidence files or when controlled version history is required.

8.2 Document and wiki-based logs

Document or wiki systems support narrative context, hyperlinks, and structured sections. They are helpful for projects that need both formal fields and explanatory detail. With proper access controls, they can support collaboration and long-term maintainability.

8.3 Issue-tracker and ticket-based logs

Issue trackers integrate decisions with workflow and accountability. Each decision can be represented as a ticket linked to tasks, code changes, or protocol revisions. This format is effective when decision implementation requires coordinated work and status tracking.

8.4 Version control integration (lightweight approaches)

When version control is already used for code and documentation, lightweight integration can preserve decision history alongside other artifacts. The log may be stored as a structured document with change history, enabling traceable edits and better recovery from accidental modifications.

9 Example decision log entries (illustrative)

Illustrative entries demonstrate how fields combine into a useful record. The examples below show common decision types and how evidence and rationale can be stated.

9.1 Example: choosing an analysis approach

Decision: Use a mixed-effects regression model instead of a fixed-effects model for the primary analysis. Date/Owner/Scope: 2026-03-14 / Analyst Lead / Primary outcome analysis. Context: Pilot diagnostics indicated clustering by batch and repeated measures within subjects. Alternatives: Fixed-effects regression; generalized estimating equations. Selection criteria: Ability to model within-subject correlation; robustness to batch variation; alignment with the planned outcome interpretation. Evidence: Pilot residual diagnostics; intra-class correlation estimates; prior literature on similar study designs. Assumptions/Constraints: Random effects distribution approximations; availability of convergence diagnostics. Impact/Follow-up: Update analysis script; document model choice in methods; verify convergence and sensitivity across alternative random-effects structures.

9.2 Example: deciding on inclusion/exclusion criteria

Decision: Exclude records with measurement artifacts exceeding the predetermined quality threshold. Date/Owner/Scope: 2026-04-02 / Data Manager / Dataset assembly. Context: Initial review identified a subset with sensor saturation leading to distorted readings. Alternatives: Impute corrupted measurements; retain all records and include artifact indicators as predictors. Selection criteria: Preserve validity of measurement scale; minimize bias from unmodeled corruption; feasibility of reliable imputation. Evidence: Quality-control histograms; comparison of summary statistics with and without artifacts; manual review on a sample. Assumptions/Constraints: The threshold correlates with irrecoverable measurement distortion; enough data remain for planned analyses. Impact/Follow-up: Recompute dataset version; update inclusion/exclusion rules in protocol appendix; record counts excluded and reasons.

9.3 Example: selecting a data-cleaning rule

Decision: Perform winsorization at the 1st and 99th percentiles for a continuous covariate used in modeling. Date/Owner/Scope: 2026-04-21 / Stat Consultant / Covariate preprocessing. Context: The covariate distribution showed extreme values likely due to transcription errors or rare operational states. Alternatives: Remove outliers by z-score; transform using log scaling only; leave data unchanged. Selection criteria: Reduce influence of extremes without deleting observations; maintain interpretability of the transformed scale; consistent behavior across batches. Evidence: Sensitivity analysis comparing model coefficients across cleaning strategies; influence diagnostics. Assumptions/Constraints: Extreme values represent leverage points rather than true causal variation. Impact/Follow-up: Apply rule consistently across training and evaluation splits; report pre- and post-cleaning distribution summaries.

9.4 Example: documenting a change in measurement procedure

Decision: Adjust measurement timing to standardize intervals between two related readings. Date/Owner/Scope: 2026-05-10 / Study Coordinator / Measurement protocol. Context: Operational logs showed variable intervals across sites affecting comparability. Alternatives: Add interval as a covariate; keep procedure unchanged and stratify results by interval bands. Selection criteria: Improve measurement comparability at the source; reduce complexity of downstream modeling; practical feasibility for field teams. Evidence: Site-level comparison of measurement variability; preliminary analysis showing reduced variance after timing standardization. Assumptions/Constraints: New timing schedule is operationally manageable; calibration remains consistent. Impact/Follow-up: Update protocol document version; label dataset with measurement method indicator; adjust analysis to account for method change where necessary.

10 Decision log maintenance and lifecycle

Maintenance determines whether the log remains a dependable artifact. A lifecycle approach defines how entries are created, reviewed, summarized, and closed.

10.1 Establishing the logging cadence

Teams should define when decisions are recorded—such as at protocol design milestones, after pilot results, and whenever a method change occurs. A clear cadence prevents both last-minute scrambling and unnecessary entries.

10.2 When and how to record “small” decisions

Not every minor preference needs a full entry. “Small” decisions are best logged when they meet criteria such as influencing downstream computations, affecting reproducibility, or introducing an assumption that could matter to interpretation. Otherwise, brief notes may be sufficient.

10.3 Review intervals and periodic summaries

Periodic review—weekly or per milestone—improves quality by ensuring entries remain consistent and complete. Summaries can consolidate multiple related decisions, preserving readability while maintaining traceability through links to underlying entries.

10.4 Closing the log at project completion

At completion, the log should be finalized: unresolved decisions marked, superseded entries clearly referenced, and links to evidence consolidated. The final version should be archived with the associated project outputs to support future verification.

11 Privacy, ethics, and confidentiality considerations (non-political)

Decision logs frequently include contextual details, some of which may be sensitive. Ethical handling focuses on protecting personal data and confidential materials without undermining the log’s usefulness.

11.1 Redacting sensitive or personally identifying details

If entries reference individuals—such as internal reviewers or participants—identifying details should be removed or replaced with controlled identifiers. Sensitive operational details can also be generalized to prevent accidental disclosure.

11.2 Access controls for confidential materials

Evidence links may point to restricted files, proprietary instruments, or confidential datasets. Access controls should ensure that only authorized users can view these materials, while preserving the decision narrative required for transparency.

11.3 Retention schedules and data handling norms

Decision logs should align with retention policies for the broader project. When evidence cannot be retained indefinitely, the log can store sufficient metadata to explain the decision while referencing evidence that may be subject to deletion under policy.

12 Related methods and complementary practices

Decision logs work alongside other practices that support documentation, auditability, and learning from variation over time.

12.1 Research notes, lab notebooks, and memoing

Informal notes capture day-to-day reasoning, observations, and intermediate results. Memoing helps clarify hypotheses and evolving interpretations. Decision logs distill the essential calls from these materials into structured, decision-focused entries.

12.2 Audit trails and reproducibility checklists

Audit trails record who changed what and when in tools and datasets. Reproducibility checklists verify that the right materials—code, parameters, and documentation—are available to repeat the work. A decision log connects these components by explaining why certain choices were made.

12.3 Change management and protocol deviation records

Change management systems track modifications to approved procedures. Protocol deviation records document departures from intended steps. Decision logs complement them by capturing the rationale behind the change or deviation and the criteria for deciding whether to adapt or revert.

12.4 Post-hoc reflection and lessons learned

Retrospectives identify what worked well and what should be improved next time. Although lessons learned can be separate from operational decisions, they benefit from the decision log context—revealing which assumptions were later supported or overturned.