Fix Contribution

When to Use This Skill

• A PR has validation errors and you are asked to fix them
• An issue is assigned to you with the auto-fix or copilot label
• A maintainer comments "@copilot fix this" on a PR

Before starting, read common-fixes.md in this skill's directory for detailed fix patterns with before/after examples.

Fix Process

Step 1: Identify the Issues

Read the validation report comment on the PR (posted by the PR Validator workflow). It will list specific errors and warnings categorised as:

• Schema errors (missing/invalid fields)
• Cross-reference errors (invalid state_id, country_id, mismatched codes)
• Coordinate warnings (out of bounds)
• Duplicate warnings

Step 2: Apply Fixes

Missing Required Fields

For cities missing fields, look up the correct values:

• state_id / state_code: Search states.json by state name and country
• country_id / country_code: Search countries.json by country name
• latitude / longitude: If missing, leave a comment asking the contributor rather than guessing

Wrong Field Formats

• country_code not 2 chars: Look up the correct ISO2 code from countries.json
• Latitude/longitude out of range: Check if values are swapped or have extra digits
• Empty name: Cannot fix - ask the contributor

Auto-Managed Fields Present

Remove these fields from the contribution:

• id
• created_at
• updated_at
• flag

Mismatched References

• If country_code does not match country_id: Look up the correct code from countries.json
• If state_code does not match state_id: Look up the correct code from states.json
• If state_id belongs to a different country: Flag for contributor clarification

Step 3: Commit the Fix

If you have write access to the contributor's branch:

1. Make the corrections directly in the contribution file
2. Commit with message: fix: correct [description] in [filename]
3. Comment on the PR explaining what was fixed and why

If you do NOT have write access:

1. Create a new branch from the PR's base branch
2. Apply the fixes
3. Open a new PR referencing the original: fix: corrections for PR #[number]
4. Comment on the original PR linking to your fix PR

Step 4: Explain Changes

Always comment on the PR explaining:

• What was wrong
• What was fixed
• Source of the correct data (if applicable)
• Any items that need contributor input (cannot auto-fix)

Common Fix Patterns

Pattern: Country Code Lookup

1. Read the country_id from the record
2. Find the country in countries.json by id
3. Use its iso2 field as the correct country_code

Pattern: State Code Lookup

1. Read the state_id from the record
2. Find the state in states.json by id
3. Use its state_code or iso2 field as the correct state_code
4. Verify the state's country_id matches the record's country_id

Pattern: Remove Auto-Managed Fields

For each record in the contribution:
  Remove: id, created_at, updated_at, flag
  Keep everything else unchanged

Important Rules

• Never modify coordinate values without a verified source
• Never change the name field without contributor confirmation
• Always explain what you changed and why
• If unsure about correct data, ask rather than guess
• Preserve the original JSON formatting style of the file