Updates to Role Skills README

advanced-research-roles-skills/README.md

@@ -1,18 +1,18 @@
 # Lumora Agent Skills Training Demo
 
+## Overview
+
 This repository is a synthetic World Bank-style coding-agent training project.
 It teaches how reusable agent skills improve output on realistic development
 research and operations tasks.
 
-Participants who cannot use `git` can download
-`lumora-agent-skills-training-demo.zip` from the repository root and unzip it
-locally.
-
 The mock study is the **Lumora Family Support Grant Evaluation**, a fictional
 cash transfer program with baseline, follow-up, payment, field visit, survey
-log, and back-check data.
+log, and back-check data. It bundles synthetic data, a Stata pipeline (a set of
+scripts that run in order), tables, figures, and role-based tasks for managers,
+field coordinators, and research assistants.
 
-## What Is Included
+### What Is Included
 
 - Synthetic raw CSV data in `data/raw/`
 - Participant-facing Stata pipeline in `code/stata/`
@@ -23,7 +23,7 @@ log, and back-check data.
 - Exercise-specific skill setup instructions in `.agents/README.md`
 - Role-specific exercises in `exercises/`
 
-## Run The Stata Pipeline
+### Run the Stata Pipeline
 
 Open Stata from the project root and run:
 
@@ -45,43 +45,59 @@ Expected outputs include:
 - `outputs/figures/enumerator_quality_flags.png`
 - `outputs/qa_reports/stata_pipeline.log`
 
-## Participant Tasks
+## Exercise
+
+### 1. Get Content
+
+Start by downloading the repo to your computer. If you are familiar with Git, you may clone the repo. Participants who are not familiar with Git can download the content as a [zip file](https://github.com/dime-worldbank/coding-agent-exercise/releases/latest/download/advanced-research-roles-skills-all.zip) and unzip it
+locally.
+
+### 2. Choose a Role Exercise
+
+Pick the exercise that matches your role in `exercises/`:
+
+- Managers: [exercises/manager_update_deck.md](exercises/manager_update_deck.md)
+- Field coordinators: [exercises/field_coordinator_hfc_review.md](exercises/field_coordinator_hfc_review.md)
+- Research assistants: [exercises/research_assistant_analysis.md](exercises/research_assistant_analysis.md)
+
+To try another role, reset the exercise first — delete the generated output, or re-clone the repository (or re-download the zip). Then pick a different role and repeat the steps.
+
+### 3. Run the Comparison Workflow
 
-Each exercise uses the same before/after workflow:
+Each role exercise uses a shared comparison workflow:
 
-1. clear `.agents/skills/` and run the task with a general coding agent;
-2. evaluate the output against the exercise checklist;
-3. copy in only the role-specific skills;
-4. run the same substantive task again;
-5. compare what changed and what still needs human judgment.
+1. Empty the `.agents/skills/` folder and run the task with a general coding agent.
+2. Evaluate the output against the exercise checklist.
+3. Copy in only the role-specific skills.
+4. Run the same task again and compare what changed.
 
 See `exercises/comparison_prompts.md` for the shared scorecard.
 
-## Skill Setup
+### Skill Setup for Each Role
 
 The source skills live in `skills/`. For the workshop, copy only the skills
 needed for the current exercise into `.agents/skills/`.
 
 See [.agents/README.md](.agents/README.md) for role-specific copy commands.
 
-You can run a baseline prompt first, then activate the relevant skill set and compare the difference.
+You can run a baseline prompt first, then copy in the relevant skills and compare the difference.
 
 Managers:
 
-- update `decks/baseline_round1_deck.pptx` with follow-up outputs;
-- inspect the Stata do-files first;
-- produce an update log mapping slide claims to generated outputs.
+- Update `decks/baseline_round1_deck.pptx` with follow-up outputs.
+- Inspect the Stata do-files first.
+- Produce an update log mapping slide claims to generated outputs.
 
 Field coordinators:
 
-- run high-frequency data quality checks;
-- produce an actionable follow-up list before the next payment cycle.
+- Run high-frequency data quality checks.
+- Produce an actionable follow-up list before the next payment cycle.
 
 Research assistants:
 
-- clean and construct the household panel;
-- validate IDs and merges;
-- generate tables and figures reproducibly.
+- Clean and construct the household panel.
+- Validate IDs and merges.
+- Generate tables and figures reproducibly.
 
 ## Important Caveat