Add R refactoring skill and journal figure specifications documentation

- Created a new documentation file for the optional R refactoring skill, detailing the process to refactor R scripts into the lab format with clear organization and emoji section comments.
- Introduced a new reference document outlining fictional journal figure specifications, including detailed requirements for figure formatting, accessibility, and behavior verification.

Author: ilarsf

README.md

@@ -1,23 +1,26 @@
 # Practical GenAI Agentic Coding Guide
 
-**[Read the online guide](https://fritschelab.org/practical-genai-agentic-coding-guide/).** Choose [Python](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/python/) or [R](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/r/), then follow six lessons through one reporting change, verification, review, and a short handoff.
+**[Read the online guide](https://fritschelab.org/practical-genai-agentic-coding-guide/).** Choose [Python](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/python/) or [R](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/paths/r/), then repair a plot with a coding agent in six lessons.
 
 This is Part 2 of the [Practical GenAI series](https://fritschelab.org/practical-genai-coding-guide/), from [Lars G. Fritsche](https://medschool.umich.edu/profile/4980/lars-fritsche) and the [Fritsche Lab](https://fritschelab.org/) at the University of Michigan.
 
 ## Get the exercise
 
-The runnable Python/R pipeline, synthetic data, tests, and agent instructions are in the **[example repository](https://github.com/FritscheLab/practical-genai-agentic-coding-example)**. Download only that repository and follow along online. It also includes the language walkthroughs for offline use.
+Download the **[example repository](https://github.com/FritscheLab/practical-genai-agentic-coding-example)** for code, invented totals, tests, and offline lessons. Follow the website alongside it.
 
 ```bash
 git clone https://github.com/FritscheLab/practical-genai-agentic-coding-example.git
 cd practical-genai-agentic-coding-example
 ```
 
-Start with its README and your chosen language's setup. You should be comfortable running a Python or R script and using a terminal; the lessons explain the Git steps. The baseline uses synthetic data and needs no model API or credentials. Use an institution-approved coding assistant for the agent exercise.
+Start with its README and language setup. Bring basic Python/R and terminal skills; the lessons explain Git. Plotting needs no model API or credentials. Use an institution-approved coding assistant for the agent exercise.
+
+Include accessibility in every figure: contrast, readable labels, and reviewed alternative text.
 
 ## Explore the guide
 
 - [Agent setup](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/platforms/): configure your coding client and check its access.
+- [Optional R refactoring example](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/platforms/r-refactoring.html): reuse a lab formatting skill or named Codex agent, then verify that results stay the same.
 - [Repository practices](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/practices/): context, testing, logs, and handoffs.
 - [Teaching materials](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/lab_meeting/): a 45-minute workshop and slides.
 - [Lab data guidance](https://fritschelab.org/practical-genai-agentic-coding-guide/docs/reference/lab-data-policy.html): institutional requirements before adapting the workflow to study data.

_includes/path_choices.html

@@ -1,13 +1,13 @@
 <div class="guide-path-grid" aria-label="Choose a language path">
   <section class="guide-path-card" aria-labelledby="python-path-heading">
     <h2 id="python-path-heading">Python</h2>
-    <p>Use Python, pandas, and pytest. Start with a working package, then add and check the exclusion report.</p>
+    <p>Use Python and Matplotlib. Repair a grouped plot, then check its image and tests.</p>
     <p class="guide-path-runtime">Python 3.10–3.12</p>
     <a class="btn btn-primary" href="{{ '/docs/paths/python/' | relative_url }}">Start the Python path <span aria-hidden="true">→</span></a>
   </section>
   <section class="guide-path-card" aria-labelledby="r-path-heading">
     <h2 id="r-path-heading">R</h2>
-    <p>Use base R and native R checks. Start with a working script, then add and check the exclusion report.</p>
+    <p>Use base R and native R checks. Repair a grouped plot, then check its image and tests.</p>
     <p class="guide-path-runtime">R 4.1 or later</p>
     <a class="btn btn-primary" href="{{ '/docs/paths/r/' | relative_url }}">Start the R path <span aria-hidden="true">→</span></a>
   </section>

assets/images/plotting-before.png

@@ -5,41 +5,45 @@ parent: Teaching
 nav_order: 1
 ---
 
-# A small change, from request to handoff
+# Repair a plot, from request to handoff
 
 ## Prepare
 
-Have participants keep the guide open online and download the [example repository](https://github.com/FritscheLab/practical-genai-agentic-coding-example). Choose the [Python path](../paths/python/index.md) or [R path](../paths/r/index.md). Run its setup, tests, and six-row example before the presentation. Prepare an approved [coding client](../platforms/index.md). Use synthetic files throughout.
+Before the session, participants download the [example](https://github.com/FritscheLab/practical-genai-agentic-coding-example), complete [Python](../paths/python/index.md) or [R setup](../paths/r/index.md), and prepare an approved [coding client](../platforms/index.md). Run tests and save `runs/baseline/summary.png`.
 
-Open the [six-row example and expected report](../lessons/02-specify.md). Find measurements d, e, and f in the input and `outputs/flagged_rows.tsv` so you can help participants check their counts.
+Open the [exercise and target](../lessons/02-specify.md): two invented groups overlap and long labels are clipped. The task repairs that layout for a fictional journal.
+
+Keep study data and logs outside this teaching workspace.
 
 ## Follow along
 
 | Minutes | Activity |
 | --- | --- |
-| 0–5 | Open the six input rows and baseline output. Find the three excluded measurements. |
-| 5–12 | Ask the agent to explain where cleaning and reporting happen. Check the files it names. |
-| 12–17 | Show the desired report: 3 of 6 excluded, missing height 2, missing weight 2. Explain the overlap. |
-| 17–30 | Use the chosen path's implementation prompt. Watch the change and ask about anything unclear. |
-| 30–40 | Run the example and existing tests. Read the summary and inspect the diff. |
+| 0–5 | Open the baseline plot. Identify overlapping groups and clipped labels. |
+| 5–12 | Ask the agent to explain the plotting functions, layout settings, and tests. Check the source files it names. |
+| 12–17 | Compare the baseline with the target. Read the fictional JUSF specifications: grouped bars, exact dimensions, typewriter text, purple/lime groups, legend, and value labels. |
+| 17–30 | Use the chosen path's implementation prompt. Watch the source change and ask about anything unclear. |
+| 30–40 | Render the repaired PNG, run both checks, review contrast and grayscale readability, and write/review `runs/with-fix/summary.alt.txt`. |
 | 40–45 | Write a short handoff: what changed, what was checked, and what remains. |
 
 ## The example
 
-The [six-row table](../lessons/02-specify.md) fits on one screen. Measurements d/e/f are excluded; f lacks both height and weight. The task adds a readable summary of these existing decisions. Cleaning and record selection stay the same.
+The [exercise table](../lessons/02-specify.md) fixes the values; the [figure specifications](../reference/figure-specifications.md) fix the format. Point the agent there.
+
 
-Use the complete-data file next. Its report should show no exclusions. Different wording and code can produce the same useful result.
 
 ## During the change
 
-Use the prompts in the participant's language path. Ask for an explanation before edits, a short plan if needed, and implementation once the request is clear. Check the client's actual file and command permissions separately.
+Use your language path's prompts. Ask about source and tests before edits; plan only if needed. Check actual file and command permissions.
+
+Behavior tests should pass before and after; the strict figure checker should fail before and pass after. Open the image and diff too. If the agent cannot view images, a person performs that check.
 
-Existing tests help catch regressions. Reading the report checks whether the improvement makes sense. Reviewing the diff checks whether the agent changed more than requested. These are complementary habits learners can reuse in their own repositories.
+Review contrast, grayscale readability, and `runs/with-fix/summary.alt.txt` against the figure specification. The plotting CLI does not create alt text.
 
 ## If time runs short
 
-Save the current state and any failing command. Use the [expected report](../lessons/02-specify.md#describe-the-improvement) and the flagged rows to discuss what remains, and leave a short handoff so participants can continue at home.
+Save the source, latest image, commands, and unfinished work. Participants can continue from that handoff at home.
 
 ## Debrief
 
-What did you check yourself? What did the agent help you find? What would a labmate need to continue this work tomorrow?
+What did the tests establish? What did opening the image reveal? Could a labmate reproduce the edited plot from the handoff?

assets/images/plotting-target.png

@@ -7,21 +7,33 @@ nav_order: 2
 
 # Prompts for the workshop
 
-Send participants to their language path at the start. Each lesson already supplies a copyable prompt with that language and its files filled in. Participants can keep using Next to follow the exercise.
+Use your language path's prompts; they already name the right source files and checks.
 
 | Stage | Python prompt | R prompt |
 | --- | --- | --- |
 | Orient | [Python Lesson 1](../paths/python/01-orient.md) | [R Lesson 1](../paths/r/01-orient.md) |
 | Describe the change | [Python Lesson 2](../paths/python/02-specify.md) | [R Lesson 2](../paths/r/02-specify.md) |
 | Implement | [Python Lesson 3](../paths/python/03-implement.md) | [R Lesson 3](../paths/r/03-implement.md) |
+| Verify | [Python Lesson 4](../paths/python/04-verify.md) | [R Lesson 4](../paths/r/04-verify.md) |
 | Review | [Python Lesson 5](../paths/python/05-review.md) | [R Lesson 5](../paths/r/05-review.md) |
 | Hand off | [Python Lesson 6](../paths/python/06-handoff.md) | [R Lesson 6](../paths/r/06-handoff.md) |
 
-Use planning while the group still has questions about the approach. Discuss the six-row example and the report, then switch to implementation. Keep the [shared example](../lessons/02-specify.md) available to the facilitator.
+Open the baseline and [figure specifications](../reference/figure-specifications.md). Plan only while the approach is unclear, then implement.
 
-A handoff request can be shared across languages:
+Short prompts work because `AGENTS.md`, the skill, and the specification carry the reusable instructions. Point to those files instead of repeating their contents.
 
-```markdown
-Leave a short handoff: what changed, the commands and results we checked,
-and anything unfinished. Include how to rerun the example.
+If alt text is still missing, ask:
+
+```text
+Write runs/with-fix/summary.alt.txt following the journal specification.
+Check it against the image and report any accessibility checks you cannot do.
+```
+
+Review the draft yourself. Alt text is a separate deliverable; rendering creates only the PNG.
+
+For the handoff:
+
+```text
+Write a short handoff with the changes, actual checks and results,
+image and alt-text paths, and anything unfinished or untested.
 ```

docs/lab_meeting/45min_runbook.md

@@ -6,14 +6,16 @@ has_children: true
 has_toc: false
 ---
 
-# Work through a change together
+# Repair a plot together
 
-The [45-minute runbook](45min_runbook.md) is a session you can lead with your group. Use the [six short steps](../lessons/index.md) to follow along or continue at home. Choose the Python or R path, install its dependencies, and run its baseline before the session; use the meeting for reasoning and review.
+The [45-minute runbook](45min_runbook.md) is a session you can lead with your group. Use the [six short steps](../lessons/index.md) to follow along or continue at home. Choose Python or R, install its dependencies, and render the baseline before the session; use the meeting for reasoning and review.
+
+Participants and agents work with a plotting function, invented totals for two groups, rendered images, tests, and local [figure specifications](../reference/figure-specifications.md). The task separates overlapping bars and fixes clipped labels without changing the totals.
 
 - [Runbook](45min_runbook.md): agenda, preparation, and checkpoints.
-- [Demo prompts](demo_prompts.md): concise requests for orientation, implementation, and review.
-- [Six-row example](../lessons/02-specify.md): inputs, expected report, and checks for either language.
+- [Demo prompts](demo_prompts.md): requests for orientation, implementation, and review.
+- [Plot-repair exercise](../lessons/02-specify.md): baseline, target, and checks for either language.
 
 To present the [Quarto slides](https://github.com/FritscheLab/practical-genai-agentic-coding-guide/blob/main/docs/lab_meeting/slide_deck.qmd), run `quarto render docs/lab_meeting/slide_deck.qmd` from a local copy of the [guide repository](https://github.com/FritscheLab/practical-genai-agentic-coding-guide) and open the resulting HTML file. Participants only need the example repository; the guide source is for presenting or editing the slides.
 
-Participants should leave with a reporting change they understand, test results, and a short handoff they can use to continue at home.
+Participants should leave with a readable plot, reviewed alternative text, a source change they understand, test results, and a short handoff. Accessibility is part of the task and review from the start.