Geofeed Tuner

Geofeed tuner

Create and improve public IP geolocation feed CSV files by validating RFC 8805 structure, making them well-formed and real-world useful, applying opinionated tuning checks to operator-supplied data, using bundled ISO and territory data, and generating an HTML tuning report.

When to invoke

• "Validate this RFC 8805 geofeed CSV."
• "Tune our IP geolocation feed for better accuracy."
• "Create a self-published geofeed for these public prefixes."
• "Check geofeed country, region, city, and postal code fields."
• "Publish a geofeed for an ISP, carrier, cloud provider, IXP, hosting provider, or satellite provider."

Prerequisites and context

• Python 3 is required.
• Use this skill only for publicly routable IP addresses. Do not use it for private or internal IP address management.
• Accepted input: pasted subnet rows, a local CSV file, or a remote URL pointing to a CSV file.
• If the user has not supplied IP subnets or ranges (inetnum or inet6num), ask for them before processing.

Progressive disclosure and bundled resources

Use progressive-disclosure: bundled resources are read-only distribution content, while run/ contains agent-generated files.

Execute generated scripts from the skill root directory, the directory containing SKILL.md, so relative paths such as assets/iso3166-1.json and ./run/data/report-data.json resolve. Do not cd into ./run/ before running scripts.

RFC 8805 feed rules

Structural rules:

• Files may contain comment lines beginning with #, including the header when present.
• Header row is optional; if present, treat it as a comment when it starts with #.
• Files must be UTF-8.
• Subnet host bits must not be set; 192.168.1.1/24 is invalid and should be 192.168.1.0/24.
• Feed rows apply only to globally routable unicast addresses, not private, loopback, link-local, or multicast space.
• An empty alpha2code or case-insensitive ZZ, regardless of region/city, is an explicit do-not-geolocate signal.
• Postal or ZIP codes are deprecated by RFC 8805 Section 2.1.1.5 because they are too fine-grained and create privacy concerns.

Procedure

Before each phase, print a visible TODO checklist, update it as steps complete, and do not skip phases.

Phase 2 input handling:

• Remote URL: download to ./run/data/. On 4xx, 5xx, timeout, or redirect loop, stop with Feed URL is not reachable: HTTP {status_code}. Please verify the URL is publicly accessible.
• Local file: process directly without downloading.
• Encoding: try UTF-8, then utf-8-sig, then latin-1; on UnicodeDecodeError, continue to the next encoding; re-encode and rewrite the working copy as UTF-8. If decoding fails, stop with Unable to decode input file. Please save it as UTF-8 and try again.

Phase 3 execution rules:

• Generate a script for Phase 3.
• Do not combine Phase 3 with other phases.
• Do not precompute future-phase data.
• Store output exactly at ./run/data/report-data.json.
• Keep Phase 3 schema IMMUTABLE; Phase 4 may add only TunedEntry to each object in Entries.

Phase 3 JSON schema

Phase 3 MUST preserve each per-entry, entry-level, human-readable field. Messages.Checked is auto-tunable when the reference table has Tunable: true; checked report controls use checked, and non-tunable controls may render disabled. The schema includes non-empty Messages when a rule fires and preserves examples such as "1101", "3301", "ERROR", "WARNING", "SUGGESTION", and "ZZ".

JSON keys map directly to template placeholders such as {{.CountryCode}} and {{.HasError}}.

{
  "InputFile": "",
  "Timestamp": 0,
  "TotalEntries": 0,
  "IpV4Entries": 0,
  "IpV6Entries": 0,
  "InvalidEntries": 0,
  "Errors": 0,
  "Warnings": 0,
  "OK": 0,
  "Suggestions": 0,
  "CityLevelAccuracy": 0,
  "RegionLevelAccuracy": 0,
  "CountryLevelAccuracy": 0,
  "DoNotGeolocate": 0,
  "Entries": [
    {
      "Line": 0,
      "IPPrefix": "",
      "CountryCode": "",
      "RegionCode": "",
      "City": "",
      "Status": "",
      "IPVersion": "",
      "Messages": [
        {"ID": "", "Type": "", "Text": "", "Checked": false}
      ],
      "HasError": false,
      "HasWarning": false,
      "HasSuggestion": false,
      "DoNotGeolocate": false,
      "GeocodingHint": "",
      "Tunable": false
    }
  ]
}

Top-level fields: InputFile, Timestamp, TotalEntries, IpV4Entries, IpV6Entries, InvalidEntries, Errors, Warnings, OK, Suggestions, CityLevelAccuracy, RegionLevelAccuracy, CountryLevelAccuracy, and DoNotGeolocate. Entry fields: Line, IPPrefix, CountryCode, RegionCode, City, Status, IPVersion, Messages, HasError, HasWarning, HasSuggestion, DoNotGeolocate, GeocodingHint, and Tunable.

Status severity is ERROR > WARNING > SUGGESTION > OK. Line is 1-based and counts comments and blanks. IPVersion is "IPv4" or "IPv6". GeocodingHint is always "" in Phase 3. Tunable is true when any message has Checked: true.

Validation rules reference

Populate messages exactly from the table:

entry["Messages"].append({
    "ID": "1201",
    "Type": "ERROR",
    "Text": "Invalid country code: not a valid ISO 3166-1 alpha-2 value",
    "Checked": True,
})
entry["HasError"] = any(m["Type"] == "ERROR" for m in entry["Messages"])
entry["HasWarning"] = any(m["Type"] == "WARNING" for m in entry["Messages"])
entry["HasSuggestion"] = any(m["Type"] == "SUGGESTION" for m in entry["Messages"])
entry["Tunable"] = any(m["Checked"] for m in entry["Messages"])

Output template

## Geofeed tuning report

**Status:** complete | blocked | needs input
**Input file:** <InputFile>
**Report data:** `./run/data/report-data.json`
**HTML report:** `./run/report/<report-name>.html`

### Summary
| Metric | Count |
| --- | --- |
| Total entries | <TotalEntries> |
| IPv4 entries | <IpV4Entries> |
| IPv6 entries | <IpV6Entries> |
| Invalid entries | <InvalidEntries> |
| Errors | <Errors> |
| Warnings | <Warnings> |
| Suggestions | <Suggestions> |
| Do-not-geolocate | <DoNotGeolocate> |

### Findings
| Line | Prefix | Status | Messages | Tunable |
| --- | --- | --- | --- | --- |
| <Line> | <IPPrefix> | <Status> | <ID: Text> | <true/false> |

### Validation
- Phase checklists completed: yes/no
- RFC 8805 structure checked: yes/no
- JSON schema written unchanged in Phase 3: yes/no
- Phase 4 `TunedEntry` extension only: yes/no/not run

Quality gate

• The task is for public, globally routable IP space, not private IPAM.
• Each phase printed and updated a visible TODO checklist.
• Phases ran in order from 1 through 6 with no skipped dependency.
• Remote downloads went only to ./run/data/; reports went only to ./run/report/; generated scripts went only to ./run/.
• assets/, references/, and scripts/ were not modified.
• Phase 3 wrote ./run/data/report-data.json and did not add future-phase data.
• Validation messages use the exact ID, Type, Text, and Checked values from the table.
• Postal codes are removed or flagged; ZZ and empty alpha2code are treated as do-not-geolocate.