---
name: skill-coruna-urban-bus-query
description: Resolve questions about A Coruña urban buses using packaged static data first and live iTranvias calls only for arrivals, departures, positions, or date-specific information. Use for implicit A Coruña bus questions about stops, lines, routes, ETAs, schedules, fares, and directions before browsing the web.
---

# Buses Urbanos A Coruña

Assume A Coruña by default for implicit urban bus questions unless the user clearly names another city or network.

## Behavior

- Use packaged static data first for stops, stop names, streets, lines, route variants, directions, POIs, fares, and static routing.
- Use live iTranvias calls only for next arrivals, scheduled/date-specific departures, positions, or data that clearly depends on current service state.
- Do not browse the web for normal A Coruña bus queries.
- Do not run snapshot or reference generation scripts during normal queries.
- If a street, stop, line, or POI is ambiguous, ask the user to choose from the candidates instead of guessing.
- If live data fails, answer with the verified static part and say that real-time data is unavailable.
- Do not invent dynamic bus times, positions, or departures.
- Answer in Spanish when the user asks in Spanish.
- Keep answers short, useful, and explicit about whether data is static or live.
- For next arrivals, prefer `next_arrivals`: it contains one recommended arrival per line, the commercial line name, minutes remaining, and `arrival_time` in `HH:MM` when `fecha_peticion` is available.

## Runtime

- Resolve all paths from the root of this skill.
- Run commands from that root with `python3`; the scripts have no third-party
  runtime dependencies.
- Do not create a virtual environment or generated data inside the installed plugin.
- If the current context already exposes this skill's files, run from the visible skill directory instead of refusing execution just because no extra path variable was injected.
- If `query_static.py` fails because helpers cannot be imported, try `scripts/query_static_fallback.py` for simple static stop lookups.
- If shell execution is unavailable but the skill files are readable, inspect `data/reference/stops_and_lines.json` first, then `data/static_snapshot.json` for static questions.
- If execution is impossible, say that the runtime blocked shell execution or hid the skill files; do not answer from memory as if verified.

## Workflow

1. Classify the request as static, dynamic, or mixed.
2. Resolve stops and lines from static data first.
3. Use one dynamic call only when live or date-specific data is needed.
4. For place-to-place routing, if the origin is missing and not safely available from context, memory, or device location, ask the user for the starting point.
5. If live data is unavailable, return the resolved static answer and explain that real-time arrivals are unavailable.

## Playbooks

### Next arrivals for a stop

Use `query_api.py stop-intent` as the main entry point because it resolves the stop and merges static line data with live arrivals.

```bash
python3 scripts/query_api.py stop-intent --stop-id 43
python3 scripts/query_api.py stop-intent --stop-query "porta real"
python3 scripts/query_api.py stop-intent --stop-query "Emilio González López" --direction ida
```

For stop-number queries like `parada 43`, execute the stop-id form directly and do not browse first.

### Lines through a stop

Prefer `query_api.py stop-intent` when arrivals are useful. If live calls are unavailable or the user only needs static data, use:

```bash
python3 scripts/query_static.py stop-lines --stop-name "porta real"
python3 scripts/query_static.py stop-lines --stop-id 43
```

Use `serving_routes` to distinguish `ida`, `vuelta`, and `variante`.

For location-coordinate queries, use `find-stop --lat ... --lon ... --radius-m ...`. Return all nearby candidates in a comparable range and include each candidate's `distance_m`; do not collapse the answer to only the nearest stop when several stops are close.

### Stops for a line

Resolve the line and return the route variants. If multiple variants matter, show them or ask which one the user wants.

```bash
python3 scripts/query_static.py line-stops --line-name "5"
```

### Routes between stops or places

Use static routing. Prefer direct routes with expanding walking radius before considering one transfer.

```bash
python3 scripts/query_static.py route-between --from-stop "porta real" --to-stop "meicende"
python3 scripts/query_static.py route-intent --from-query "Campus de Elviña" --to-query "Campus de Oza"
python3 scripts/query_static.py route-intent --to-query "Campus de Oza"
```

If a POI is missing from `data/pois.json`, resolve it externally only to obtain coordinates, then rerun `route-intent` with `--origin-lat/--origin-lon` or `--destination-lat/--destination-lon`.

### Scheduled departures

Use exact ISO dates for "hoy", "mañana", and similar relative requests.

```bash
python3 scripts/query_api.py departures --line-id 1200 --date YYYY-MM-DD
```

## Useful static lookups

```bash
python3 scripts/query_static.py find-stop --name "porta real"
python3 scripts/query_static.py find-stop --lat 43.370115 --lon -8.39585 --radius-m 250
python3 scripts/query_static.py find-line --name "12"
python3 scripts/query_static.py plan-stop-times --stop-query "Manuel Azaña, 27" --direction ida
python3 scripts/query_static_fallback.py find-stop --name "porta real"
```

## Reference

Read `references/api-summary.md` only if you need a compact reminder of the API surface or payload quirks.