Research Harness Work
Execute approved analysis tasks from analysis_plan.md. For each task, write a reproducible script, run it, verify the log exists, and update the evidence ledger.
This skill runs after /research-harness-plan (human-approved) and before /research-harness-review.
Quick Reference
| Input | Action |
|---|
/research-harness-work 1.1 | Execute task 1.1 from analysis_plan.md |
/research-harness-work 2 | Execute all tasks in stage 2 sequentially |
/research-harness-work all | Execute all cc:todo tasks sequentially |
/research-harness-work --no-commit | Execute without committing; leave outputs for review |
Default behavior with no argument: ask the user which task or stage to run. Do not auto-select.
Pre-flight Checks
Before executing any task:
- Read
analysis_plan.md. If it does not exist, stop and tell the user to run /research-harness-plan first.
- Confirm the task ID exists in
analysis_plan.md and its status is cc:todo or cc:wip. Do not re-execute cc:done tasks without explicit user instruction.
- Confirm the analysis-ready dataset specified in
analysis_plan.md exists under data/processed/.
- If the task has
cc:blocked status: report the blocking reason and stop. Do not work around a blocked task.
Procedure
Step 1 — Read the task definition
From analysis_plan.md, read for the specified task:
- Script path
- Log path
- Output path
- DoD (definition of done)
- Assumptions
- Unresolved questions
- Identification strength label
If the task has unresolved questions: stop and list them. Ask the user to resolve them before the task runs.
Mark the task cc:wip in analysis_plan.md.
Step 2 — Write the analysis script
Write the script at the path specified in the task definition.
Script requirements:
- Language: use whichever language the study uses (R, Stata, Python). If not specified, use R.
- Header comment: study name, task ID, date, analyst (Claude Code), identification strategy from
study_spec.md §2
- Project-relative paths only
- Set random seed if any random operation is used
- Open log file at the start; close at the end
- Log: task ID, date, dataset loaded, N rows loaded, any sample restrictions applied with N dropped and N remaining, all model results including coefficients and standard errors, N in estimation sample
R template for regression task:
library(here)
log_file <- here("analysis", "<stage>", "logs", "<task>.log")
sink(log_file, append = FALSE, split = TRUE)
cat("Task:", "<task-id>", "\n")
cat("Started:", format(Sys.time()), "\n\n")
df <- read.csv(here("data", "processed", "analysis_ready.csv"))
cat("Loaded:", nrowdf
n_before nrowdf
df dfrestriction
cat nrowdf n_before nrowdf
fit lmformula data df
cat
printsummaryfit
write.csvbroomtidyfit here row.names
cat
cat formatSys.time
sink
Do not hard-code numerical results into the script. The script computes them; the log records them.
Step 3 — Run the script
Run the script. Capture the exit code and the full log output.
- Exit code 0: proceed to Step 4
- Exit code non-zero (attempt 1): read the log, identify the error, fix the script, re-run
- Exit code non-zero (attempt 2): read the log again, fix the specific error, re-run
- Exit code non-zero (attempt 3): stop. Do not invent output. Write the error to
analysis_plan.md under the task. Mark the task cc:blocked. Tell the user what failed and why.
Do not continue to the next step if the script did not exit with code 0.
Step 4 — Verify evidence
After a successful run, verify:
- Log file exists at the path specified in the task definition
- Output file (table or figure) exists at the path specified
- The log contains the numerical results that will be reported (coefficients, standard errors, sample size)
If any verification fails: do not mark the task cc:done. Report what is missing.
Step 5 — Update analysis_plan.md
Add an evidence row to the Evidence Ledger in analysis_plan.md:
| Task | Script | Log | Output | Verified | Date |
|---|
| 1.1 | analysis/descriptive/scripts/table1.R | analysis/descriptive/logs/table1.log | output/tables/table1.csv | YES | YYYY-MM-DD |
Mark the task status cc:done.
Step 6 — Report completion
Print a task completion summary:
Task 1.1 — Complete
Script: analysis/descriptive/scripts/table1.R
Log: analysis/descriptive/logs/table1.log [exists: YES]
Output: output/tables/table1.csv [exists: YES]
Status: cc:done
Key results from log:
N = <value from log>
[other key stats from log]
Next task: 1.2 or run /research-harness-work 1.2
Do not paraphrase or interpret the results. Quote them from the log.
Forbidden Actions
- Do not report any number that is not present in the log file
- Do not mark a task
cc:done unless the log file and output file both exist
- Do not continue after a script failure without documenting the error
- Do not change
analysis_plan.md task scope without recording the change under the task
- Do not use absolute file paths in scripts
- Do not execute a task that is
cc:blocked without user instruction
- Do not run tasks that were not in the approved
analysis_plan.md without user instruction
Evidence Requirements
- Script file exists at the documented path
- Log file exists at the documented path
- Output file exists at the documented path
- Evidence row added to
analysis_plan.md
- Task status updated to
cc:done in analysis_plan.md
Completion Criteria (per task)
Escalation (task failure)
If a task fails after 3 attempts:
- Write to
analysis_plan.md under the task:
- What error occurred (quoted from log)
- What was tried
- What is needed to resolve it
- Mark task
cc:blocked
- Tell the user: the data or design may not support this task. They must decide whether to revise the plan.
Do not invent output, use estimated values, or continue as if the task completed.
Handoff to Stage 6
After all approved tasks are complete:
All requested tasks are done. Review analysis_plan.md to confirm all expected tasks are cc:done.
When ready, run /research-harness-review to check identification, numerical accuracy, and causal claims before release.
