Run a Mode 1 (Reflexive Scaffold) provocateur analysis

Top-level Mode 1 entry point. Where run_analysis runs the Mode 2/3 inductive-/framework-coding pipeline, run_mode1 orchestrates the provocateur loop with the same scaffolding (output directory + run_metadata.json + methodology rules + audit log + fabrication log + finalize_run + report) so a Mode 1 run produces a canonical reviewable artifact set under outputs/<run-id>-rs/.

Usage

run_mode1(
  data,
  theme_set,
  config_path = NULL,
  config = NULL,
  categories = .VALID_PROVOCATION_CATEGORIES,
  resume = FALSE,
  config_overrides = list()
)

Arguments

data: Tibble: standardized + preprocessed corpus. Must carry std_id + std_text; should also carry std_author for T0.2 participant spread, and either theme_membership_* columns or an emerged_themes column to indicate which entries support each theme.
theme_set: ThemeSet with researcher-authored themes. The provocateur loop runs once per theme.
config_path: Path to a YAML config file that declares methodology.mode = "reflexive_scaffold". Mutually exclusive with config.
config: A pre-loaded ThematicConfig. Mutually exclusive with config_path.
categories: Character vector of provocation categories to run (defaults to all five). Restricting this here also restricts the T0.3 coverage assertion to the supplied subset.
resume: Logical; if TRUE, look for a prior Mode 1 run dir and resume the provocateur loop from its reflection_log.json. Memos are also rehydrated from outputs/<run>/memos/<id>.md (the canonical persistence layer per AC4).
config_overrides: Named list of overrides applied after the YAML config is loaded. Two equivalent styles are supported and may be mixed: dot-path keys (list("study.research_focus" = "x")) and nested named lists (list(study = list(research_focus = "x"))). Both deep-merge into the loaded config; sibling fields under the same parent key are preserved. See load_config for the full leaf-vs-recurse rule.

Value

Invisibly: a list with output_dir, reflection_log, theme_set, coverage, theme_stats, config, integrity, artifact_paths.

Details

Mode 1's architectural commitment (Sarkar 2024 / patterns doc): the AI does NOT author themes or codes – the researcher does, in their own external workflow (NVivo, ATLAS.ti, MAXQDA, etc.). pakhom's contribution is the extractive provocateur loop: counter-narrative, absent voice, alternative interpretation, disconfirming evidence, and assumption surfacing. This function takes the researcher's finished theme set as input and surfaces the AI's challenges to it as verifiable, citation-anchored provocations.

Examples

if (FALSE) { # \dontrun{
# 1. Author your themes elsewhere (e.g., NVivo) and load them.
#    pakhom never writes themes in Mode 1.
my_themes <- create_theme_set(list(
  list(id = 1, name = "Adoption",
       description = "Researcher-authored: remote-work flexibility",
       codes_included = c("async_routine", "daily_batching"))
))

# 2. Load + standardize + preprocess the corpus from your config,
#    then attach theme_membership_* columns that came out of your
#    external coding tool (NVivo / ATLAS.ti / MAXQDA). pakhom does
#    not author theme membership in Mode 1; you do.
cfg <- load_config("config.yaml")  # methodology.mode = "reflexive_scaffold"
my_corpus <- load_corpus_from_config(cfg)
my_corpus$theme_membership_Adoption <- as.integer(
  my_corpus$std_id %in% adoption_ids  # ids from your NVivo export
)

# 3. Run the provocateur loop with full transparency and run-state scaffolding
result <- run_mode1(
  data      = my_corpus,
  theme_set = my_themes,
  config    = cfg
)

# 4. Add reflexive memos (available in every mode)
result$reflection_log <- add_memo(
  result$reflection_log,
  body = "The 'Adoption' theme rests heavily on contributors 1-3.",
  type = "theoretical",
  linked_themes = "Adoption"
)
persist_memos(result$reflection_log, result$output_dir)
} # }