---
name: validate-contribution
description: >
  Validate geographic data contributions against the CSC database schema.
  Use this skill whenever you encounter a PR that adds, modifies, or deletes
  data in the contributions/ directory. Trigger on: validate, check, review,
  verify, audit, inspect, or assess any data contribution, PR review requests,
  schema compliance checks, field validation, or when someone says "is this
  correct", "check my data", "validate this", or "review my PR". Also use
  when asked about required fields, allowed values, or data format rules.
  Read schema-rules.md in this directory for the complete field specification.
---

## Validation Process

When validating a contribution, follow these steps in order:

### Step 1: Identify the Entity Type

Determine whether the contribution is for cities, states, or countries based on the file path or content structure.

### Step 2: Check for Auto-Managed Fields

The following fields must NOT be present in contributions (they are auto-managed):
- `id`
- `created_at`
- `updated_at`
- `flag`

If any are present, flag as an error and instruct the contributor to remove them.

### Step 3: Validate Required Fields

Read the `schema-rules.md` file in this skill's directory for the complete field specifications, constraints, and example records per entity type. Use it as the authoritative reference for all field validation.

**Cities require:** `name`, `state_id`, `state_code`, `country_id`, `country_code`, `latitude`, `longitude`
**States require:** `name`, `country_id`, `country_code`
**Countries require:** `name`

### Step 4: Validate Field Formats

- `country_code`: must be exactly 2 uppercase letters (ISO 3166-1 alpha-2)
- `latitude`: must be a decimal number between -90 and 90
- `longitude`: must be a decimal number between -180 and 180
- `name`: must be non-empty, max 255 characters (100 for countries)
- `wikiDataId`: must match pattern Q followed by digits (e.g., Q65)
- `state_id`, `country_id`: must be positive integers

### Step 5: Cross-Reference Validation

- Load the existing `countries.json` and `states.json` files
- Verify `country_id` exists in the countries data
- Verify `country_code` matches the ISO2 code of the referenced country
- For cities: verify `state_id` exists in states data AND belongs to the specified country
- For cities: verify `state_code` matches the code of the referenced state

### Step 6: Coordinate Plausibility

- Check that coordinates are within the geographic bounds of the specified country
- Flag coordinates that fall outside the country (may be valid for border cities)

### Step 7: Duplicate Detection

- Check for existing entries with the same name in the same state/country
- Check for entries within 5km of the new coordinates
- Report potential duplicates as warnings (they may be legitimate)

## Output Format

Present results as a clear validation checklist:

```
### Validation Results for [filename]

**Schema Compliance:**
- [PASS/FAIL] Required fields present
- [PASS/FAIL] No auto-managed fields included
- [PASS/FAIL] Field formats valid

**Cross-References:**
- [PASS/FAIL] country_id [X] exists ([country name])
- [PASS/FAIL] country_code "[XX]" matches country_id
- [PASS/FAIL] state_id [X] exists ([state name])
- [PASS/FAIL] state_code "[XX]" matches state_id

**Data Quality:**
- [PASS/WARN] Coordinates within country bounds
- [PASS/WARN] No duplicates detected

**Overall: [PASS / NEEDS CHANGES]**
```