---
name: review-stock-symbol-integration
description: Review integrations with GuGuData US and Hong Kong stock symbol directory APIs. Use when a pull request changes symbol search, pagination, market selection, identifier mapping, caching, freshness display, or error handling for reference-data lookups.
---

# Review Stock Symbol Integration

Review US and Hong Kong stock symbol directory integrations as reference-data lookups, not market-data or trading systems.

## Target Users

- Fintech developers building symbol selectors and security directories
- Backend engineers synchronizing US or Hong Kong reference data
- Reviewers validating market selection, identifiers, caching, and freshness labels

## Invocation Boundary

- Limit the review to US and Hong Kong stock symbol directory operations.
- Do not present these endpoints as real-time quotes, price history, investment advice, or trading tools.
- Do not place orders, manage portfolios, change subscriptions, expose keys, or mutate account data.
- Run live directory queries only when the user authorizes account-scoped, credit-consuming read access.
- Treat freshness and market coverage as contract evidence to verify, not assumptions.

## Read-Only Tools

Use only these published reference-data operations:

- `getUsStockSymbols`
- `getHkStockSymbols`

Confirm parameters and response schemas in `https://gugudata.io/.well-known/openapi.json`. Use `https://mcp.gugudata.io/mcp` only for account-authorized discovery and read-only directory queries.

## Review Workflow

1. Identify the intended market and confirm that the code selects the matching operation.
2. Verify filters, pagination, empty-result handling, and response-field mappings against the published contract.
3. Check that symbols, names, exchange fields, and other identifiers are not conflated across markets.
4. Review cache duration, refresh behavior, and user-visible freshness labels.
5. Check handling for `400`, `401`, `403`, `429`, `5xx`, timeouts, and partial synchronization.
6. Flag language that implies live prices, complete coverage, or trading suitability without supporting evidence.
7. Report confirmed contract defects separately from suggestions.

## GitHub Code Review Example

User request:

> Review this pull request with `$review-stock-symbol-integration`. It adds one selector for US and Hong Kong symbols. Do not make trading or quote requests.

Expected review behavior:

- Verify that market selection dispatches to `getUsStockSymbols` or `getHkStockSymbols` correctly.
- Compare pagination and identifier mapping with the published OpenAPI description.
- Check that cached reference data has a visible refresh policy and that failures do not silently mix markets.
- Write actionable GitHub comments with file paths, line references, evidence, and a proposed fix.

## Output

Return findings ordered by severity. For each finding include the affected file, contract evidence, user impact, and smallest safe fix. End with checks performed and checks skipped.