---
name: demo-research
description: Create a complete notebook-style data analysis page. This skill demonstrates the full workflow for turning research data (CSVs, DuckDB) into interactive visualizations with a narrative story.
compatibility: Created for Zo Computer
metadata:
  author: rob.zo.computer
---

# Demo Research Skill

This skill creates a complete, impressive notebook-style data analysis page for US electricity energy (2014–2024) in the `web/scratch` site.

## What it creates

When you run this skill, it will:

1. **Generate JSON data files** from the DuckDB database
2. **Create the React page component** with all charts and narrative
3. **Add the route** to the application
4. **Verify the page works** in the browser

The resulting page includes:
- Headline summary cards showing key metrics
- Interactive charts (line, area, stacked) using Recharts
- Narrative sections explaining the data story
- Regional comparisons across major ISOs
- Key takeaways and follow-up questions

## Running the skill

```bash
# From the workspace root
cd /home/workspace

# Run the skill
python Skills/demo-research/scripts/run-skill.py
```

The script will:
1. Check that the research data exists
2. Generate JSON data files in `web/scratch/src/data/usa_energy/`
3. Create the page component in `web/scratch/src/pages/UsaEnergy.tsx`
4. Add the route to `web/scratch/src/App.tsx`
5. Verify the page is accessible

## Cleaning up between demos

To delete the page and rerun the skill:

```bash
# Delete the generated files
rm -rf web/scratch/src/data/usa_energy
rm web/scratch/src/pages/UsaEnergy.tsx

# Remove the route from App.tsx (the script will re-add it)
# Then run the skill again
python Skills/demo-research/scripts/run-skill.py
```

## Files created

### Data files
- `web/scratch/src/data/usa_energy/energy_story.json` - Main story data
- `web/scratch/src/data/usa_energy/regional_data.json` - Regional ISO data

### Page component
- `web/scratch/src/pages/UsaEnergy.tsx` - Complete React page with all charts

### Route modification
- `web/scratch/src/App.tsx` - Adds the `/usa-energy` route

## The data story

The page tells the story of US electricity from 2014–2024:

**Headline metrics:**
- Total demand change: +5.6%
- Coal share shift: -23.5 percentage points
- Renewables share shift: +11.2 percentage points

**Key sections:**
1. Generation vs retail sales (the gap is losses)
2. Demand by sector (residential, commercial, industrial, transportation)
3. Generation mix transformation (coal collapse, gas rise, renewables growth)
4. Renewables breakdown (wind, solar, hydro)
5. Regional comparisons (CAISO, ERCOT, PJM, NYISO)
6. Key takeaways and follow-up questions

## Technical details

- **Data source**: `research/usa_energy/usa_electricity.duckdb`
- **Chart library**: Recharts (LineChart, AreaChart, BarChart)
- **Component**: NotebookTemplate for consistent layout
- **Styling**: Tailwind CSS 4 with shadcn/ui components
- **Type safety**: Full TypeScript types matching JSON structures

## Customization

To adapt this skill for other datasets:

1. Modify `scripts/generate-story-json.py` to query your database
2. Update the page template in `assets/UsaEnergyTemplate.tsx`
3. Adjust the narrative sections to match your data story
4. Change the route path and page name in `scripts/run-skill.py`