# Workflow run log

A small Python script for tracking the whole effort behind an AI workflow experiment: the initial run, human review, and corrections. Record whether each run met acceptance checks you defined before testing.

Uses Python 3.9 or newer and the standard library. No installation, API keys, external services, or network requests are needed. The CSV stays at the path you choose.

## Use it

Download `workflow-run-log.py` and open a terminal in its folder.

```sh
python3 workflow-run-log.py --help
python3 workflow-run-log.py log --help
```

Record a run. Use separate time amounts so review and correction are not counted twice.

```sh
python3 workflow-run-log.py log \
  --csv ./workflow-experiments.csv \
  --workflow "Meeting follow-up draft" \
  --run-minutes 2.5 \
  --review-minutes 4 \
  --correction-minutes 1 \
  --result pass
```

Record an unsuccessful run in the same file:

```sh
python3 workflow-run-log.py log \
  --csv ./workflow-experiments.csv \
  --workflow "Meeting follow-up draft" \
  --run-minutes 2 \
  --review-minutes 5 \
  --result fail
```

Summarize all runs in that file:

```sh
python3 workflow-run-log.py summary --csv ./workflow-experiments.csv
```

Expected summary for those two examples:

```text
Runs: 2 | Passed: 1 | Failed: 1
Total effort: 14.5 min | Review: 9 min | Correction: 1 min
Average total effort per run: 7.25 min
```

## Decide what to measure

- **Run minutes:** Time spent on the initial workflow run, before checking or fixing the result. Decide whether you will track elapsed time or active working time, then use that definition consistently.
- **Review minutes:** Time spent checking the output against your acceptance checks.
- **Correction minutes:** Additional time spent fixing problems. Defaults to zero.
- **Pass or fail:** Whether the completed run met your predefined checks. Use one convention consistently, and record failed runs as well as successful ones.

Total minutes is the sum of all three time fields. This is an experiment log, not a claim of time saved: compare these results with your existing process before drawing that conclusion. Use a separate CSV per experiment when you want a summary of one workflow.

## Local file behavior

The script creates a CSV if it does not exist and appends to matching files. It checks the header and timing data of an existing nonempty file before appending. Files with an unexpected format are rejected without changing their contents. Parent directories must already exist.

Use short, non-sensitive workflow names. The script stores only a UTC timestamp, workflow name, result, and timing fields. A formula-like workflow name is prefixed with an apostrophe so common spreadsheet applications treat it as text.

Run one instance at a time. The script does not coordinate simultaneous writes, group summaries by workflow, or manage backups. You choose where the CSV is saved and who can access it.