update agents md

AGENTS.md

@@ -10,6 +10,9 @@ The main teaching example is an ICU septic shock study:
 
 - Teach by showing small code chunks that the user can type in manually.
 - Explain each meaningful line of code before moving on.
+- Add generous learner-focused comments, especially around R functions, function arguments, return values, and unfamiliar package functions.
+- Include many small examples and REPL-style checkpoints with code, expected output, and interpretation.
+- Keep report-style Quarto notebooks focused on rendered tables and interpretation unless the user asks for REPL-style checkpoints there.
 - Teach the base R mechanics when a concept is new, then prefer readable tidyverse-style code for routine analysis.
 - Make the smallest correct change when editing project files.
 - Keep scripts and notebooks numbered so the learning sequence is obvious.
@@ -21,8 +24,11 @@ The main teaching example is an ICU septic shock study:
 
 - Use the native pipe `|>`, not `%>%`
 - snake_case for all names
+- Prefer explicit, teaching-oriented comments over terse production-style code while this remains a learning project.
+- For reusable functions, include comments describing purpose, arguments, return value, and at least one example call.
 - Prefer `vapply` over `sapply`; explicit return types
 - Use `cli::cli_*` for messages, not `message()`/`cat()`
+- Prefer cleaner imports with grouped startup message suppression, for example `suppressPackageStartupMessages({ library(readr); library(dplyr) })`.
 - Prefer `dplyr` verbs for data manipulation when external dependencies are allowed.
 - Prefer `skimr` for quick data summaries.
 - Prefer `gt` and `gtsummary` for clear analytic tables in notebooks and reports.
@@ -40,6 +46,7 @@ The main teaching example is an ICU septic shock study:
 - renv for dependency management; lockfile is source of truth
 - targets for pipeline orchestration
 - tidyverse, especially `dplyr`, for routine data manipulation
+- ggplot2 for exploratory plots and visual diagnostics
 - data.table for performance-oriented data manipulation when needed
 - skimr for quick data summaries
 - gt for presentation tables
@@ -53,6 +60,15 @@ The main teaching example is an ICU septic shock study:
 - Keep base R explanations available when they help the user understand what the package code is doing.
 - Do not add packages outside the approved stack without asking first.
 
+## Workflow Roles
+
+- Put reusable logic in `R/` functions.
+- Put reusable smoke checks or command-line workflows in `scripts/`.
+- Put polished displays, interpretation, exploratory visualization, and rendered result tables in Quarto notebooks.
+- Avoid CSV intermediates when functions can be called directly and reproducibly.
+- Use `run_all.sh` as the lightweight end-to-end runner until the project is ready for `targets`.
+- Keep rendered notebook reports in `outputs/reports/`.
+
 ## Learning Roadmap
 
 - [x] Choose ICU teaching scenario: early vasopressor strategy in septic shock.
@@ -104,14 +120,16 @@ Baseline confounders in the first simulated dataset:
 - Lactate.
 - Mean arterial pressure.
 
-Initial causal contrast:
+Initial estimand:
 
 - Risk difference in 28-day mortality.
 - Risk ratio for 28-day mortality.
 
 ## File Sequence
 
-- `scripts/01_simulate_icu_data_base_r.R`: generate synthetic ICU cohort data from the reusable simulation primitive.
-- `scripts/02_naive_analysis_base_r.R`: compute an initial naive comparison with readable tidyverse-style code.
+- `run_all.sh`: run the key scripts and render all current notebooks.
+- `scripts/01_simulate_icu_data.R`: simulate an ICU cohort in memory and print a quick `skimr` summary.
 - `R/simulate_icu_cohort.R`: first reusable simulation primitive.
-- `notebooks/01_target_trial_basics.qmd`: conceptual walkthrough of the target trial protocol with `skimr`, `gt`, and `gtsummary` examples.
+- `R/estimate_naive_vasopressor_mortality_effect.R`: shared naive mortality-effect primitive used by notebook workflows.
+- `notebooks/01_target_trial_basics.qmd`: report-style walkthrough of the target trial protocol and initial results.
+- `notebooks/02_explore_simulated_data.qmd`: exploratory visual diagnostics for the simulated cohort.