report-catalog-issue

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- drift: depends-on: portolan-registry, rashid -->

# Report a Problem with a Registered Catalog

You found something wrong with a Portolan catalog while reading it. The problem may be one of these:

- a license that misdescribes the data
- a collection whose schema contradicts its items
- an asset that does not open
- a description that documents something else

This skill files that report as a catalog feedback issue on [portolan-registry](https://github.com/portolan-sdi/portolan-registry). The registry mails the person who registered the catalog.

Use it for problems with the data a catalog serves. A problem with the registry itself, its crawl, or its export is an ordinary bug report on the same repo.

## Step 1: Resolve the catalog against the registry

Only a registered catalog can be reported. The registry export lists every one. Each child link includes the registry id.

```bash
# Accepts either the registry id or the catalog.json URL
NEEDLE="pergamino-ide"

curl -fsSL https://raw.githubusercontent.com/portolan-sdi/portolan-registry/refs/heads/main/exports/catalogs.json \
  | NEEDLE="$NEEDLE" python3 -c "
import json, os, sys
needle = os.environ['NEEDLE'].rstrip('/')
links = [l for l in json.load(sys.stdin)['links'] if l.get('rel') == 'child']
for l in links:
    if needle in (l.get('portolan_registry:id'), l.get('href', '').rstrip('/')):
        print(l['portolan_registry:id'])
        break
else:
    print('NOT REGISTERED. Ids:', ', '.join(l['portolan_registry:id'] for l in links), file=sys.stderr)
    raise SystemExit(1)
"
```

If the script exits 1, stop. The catalog is not in the registry, so there is nobody to notify. Offer the `register-catalog` skill instead.

## Step 2: Run the check that shows the problem

The report is worth nothing without evidence. Run a command against the live catalog and keep both the command and its output.

`rashid check` accepts a local path or published HTTPS URL and cites spec rule IDs in its findings. Inside a catalog managed by the CLI, use `portolan check`.

```bash
uvx --from 'rashid>=0.3.0,<0.4.0' rashid check ./catalog --summary
```

For published catalogs, rashid follows links and runs live checks:

```bash
uvx --from 'rashid>=0.3.0,<0.4.0' rashid check "$CATALOG_URL" --summary
```

Use `curl` and `jq` to show metadata fields, or DuckDB to inspect data.

```bash
curl -fsSL https://data.source.coop/nlebovits/pergamino-ide/catalog.json \
  | jq '{title, stac_extensions}'
```

Never paste output you did not produce. If you cannot reproduce the problem now, say so to the user and stop.

## Step 3: Compose the body

Write in Simplified Technical English. Run `.claude/hooks/writing_check.py --print-rules` in any portolan-sdi repo to read the rules. The `gh issue create` hook blocks a body that fails them. Lead with what is wrong and what should happen instead, in words a reader who did not follow your investigation understands in a minute. Put the evidence after that.

`gh` cannot fill an issue form, so write the headings the form renders. The registry's notifier reads the **Catalog ID** and **Kind of problem** sections by name. Those two spellings must be exact.

<!-- drift-sample: issue -->
````markdown
### Catalog ID

pergamino-ide

### Kind of problem

Schema

### What you found

The root catalog declares no `title` and no `stac_extensions`. Both are MUST fields. The registry lists the catalog by its slug and records no Portolan spec version. Add a `title` and the v0.2.0 schema URI to `stac_extensions`.

### How you hit it

```shell
$ curl -fsSL https://data.source.coop/nlebovits/pergamino-ide/catalog.json | jq '{title, stac_extensions}'
{
  "title": null,
  "stac_extensions": null
}
```

### Date observed

2026-08-11

### Tool or agent

curl 8.5.0
````

Kind is one of: Data quality, Schema, Accessibility, Documentation, Other. A missing or wrong metadata field is Schema. A wrong README or description is Documentation. Data quality is for the values in the data files. Accessibility is for an asset that does not open or a host that fails range requests.

Report one problem per issue. File a second issue for a second problem. Fill the **How you hit it** block with the command you ran and its output. Do not describe the output in prose.

## Step 4: Get approval, then file

Show the user the finished body and the catalog it names. Do not open the issue until they approve it. The report is public and it mails a third party.

```bash
gh issue create \
  --repo portolan-sdi/portolan-registry \
  --label catalog-feedback \
  --title "pergamino-ide: root catalog declares no title or spec version" \
  --body-file body.md
```

From portolan-sdi/portolan-skills, Apache-2.0.

More from portolan-sdi/portolan-skills