OWID Grapher Development Assistant

An AI assistant specialized in working with the Our World in Data (OWID) Grapher codebase, a platform for creating interactive data visualizations.

What This Skill Does

This skill provides expert guidance for developing features, fixing bugs, and maintaining the OWID Grapher platform. It understands the monorepo structure, coding conventions, database schema, testing workflows, and the Google Docs-based CMS pipeline.

Instructions

When helping users with OWID Grapher development tasks, follow these guidelines:

1. Common Development Commands

Use these commands for development workflow:

**After completing large changes:** Run `yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck` and fix any errors.

**For commit messages:** Refer to `docs/agent-guidelines/commit-messages.md` for instructions.

2. Code Style Requirements

Follow these coding conventions strictly:

- Only use `@computed` and `@action` decorators

- Do NOT use `@observable` decorator

- List all observable props in a `makeObservable()` call in the constructor

- The `makeObservable()` call must include all observable props but exclude `@computed` and `@action` ones

- Avoid inline styles unless the component already uses them for similar cases

- Components have companion `.scss` files with matching names

- Site styles entry point: `/site/owid.scss`

- Grapher styles entry point: `/packages/@ourworldindata/grapher/src/core/grapher.scss`

3. Codebase Structure

The codebase is a TypeScript monorepo using React 19 and Node 22. Key directories (ordered by dependency):

4. Database Work

**Before writing any query or migration:**

1. Run `ls db/docs/` to see available table documentation

2. Read `db/docs/README.md` for overview

3. Read relevant `db/docs/TABLE-NAME.yml` files for table details

4. Use `yarn query "..."` to explore data and understand cardinality

The main datastore is MySQL 8. All database documentation lives in `db/docs/`.

5. Google Docs CMS Pipeline

For gdocs-related work, consult these documentation files first:

6. Testing & Quality Checks

Before finalizing work:

1. Run `yarn fixPrettierChanged > /dev/null 2>&1 && yarn typecheck`

2. Fix all TypeScript errors

3. Run relevant unit tests with `yarn test run --reporter dot [test-files]`

4. For database changes, run `make dbtest`

5. Check linting with `yarn testLintChanged`

7. Common Patterns

Examples

**Example 1: Adding a new chart feature**

1. Check `./packages/grapher/` structure

2. Follow MobX class pattern with `makeObservable()` in constructor

3. Use double quotes and type all parameters

4. Create companion `.scss` file with BEM naming

5. Run `yarn typecheck` and `yarn test run --reporter dot`

**Example 2: Database schema change**

1. List `db/docs/` to find relevant table documentation

2. Read `db/docs/TABLE-NAME.yml`

3. Use `yarn query` to understand current data

4. Create migration file

5. Run `make migrate` to apply

6. Run `make dbtest` to verify

**Example 3: Google Docs integration**

1. Read `./docs/agent-guidelines/gdocs-cms-pipeline.md`

2. Understand which gdoc type from `gdocs-class-hierarchy.md`

3. Check attachment mechanism in `gdocs-attachments.md`

4. Review `./db` business logic for ArchieML parsing

Important Notes