finance-query-contract

Financial Investment Research Query Interface Design

Serves analysts and researchers at brokerages and funds, as well as those who supply data to them. The interface's main consumers are AI LLM tools and analysts. Default assumptions:existing interface field names rely on guessing, null-value semantics are chaotic, and there is no query contract. Task order: explore the data source → define the query surface → define input parameters → define disambiguation → define output parameters → define transcription → define pagination and performance → deliver.

What this skill delivers

The user provides query requirements (or an interface to be reviewed), and you produce four things:

1. Interface contract api-contract.yaml: the input parameters, output parameter schema, semantics, pagination/batch limits, units, and null-value conventions for each query.
2. Interface specification api-spec.md: design description, disambiguation rules, standardized code rules, and readable transcription rules.
3. Examples examples/: input/output parameter examples, including a json and json→str transcription comparison.
4. Troubleshooting report(troubleshooting scenario): root cause localization, evidence level, and remediation recommendations.

The interface contract and specification are the deliverables; the design rationale must be traceable to the data source contract.

Six core principles (align on these before writing any interface)

1. Simple input parameters. Primary parameters ≤ 4 (instrument, time range, field set, pagination); do not introduce nested objects, complex filter combinations, or enum magic numbers.
2. Support pagination/filtering/querying/batch querying. Batches have explicit limits; filtering retains only high-frequency dimensions.
3. Field names are unambiguous, readable, and query targeting is clear. Field names are consistent with the DDL contract; do not invent synonymous names.
4. Encapsulate disambiguation internally. Allow non-standard input (names/aliases/case/spelling variants/market-prefixed codes); the interface internally calls the existing disambiguation service to obtain top-1 the standardized code as the query key; matching correctness is the responsibility of the disambiguation service, and the query interface does not perform candidate, confidence, or ambiguity judgments.
5. Honest output. Units and magnitudes are explicit; null values are separated by convention (not found/no data yet/non-trading/not applicable/unknown); mixing bare null is prohibited.
6. Readable transcription. Provide a json→str transcription method: one paragraph, highly readable, logically clear, with fewer tokens than json.

How to use this skill (routing overview)

SKILL.md only provides the process skeleton and distribution rules. The specific methods are under references/ ,load on demand according to trigger conditions; do not read them all at once。

Stage	Action	When to load which reference
0 Boundaries	Confirm the data source tables, consumers (AI tools/analysts), invocation method (view/API/function), and deliverables	No reference needed
1 Explore the data source	Read the contract.yaml produced by the DDL, the target table structure, and existing interfaces	No reference needed; if a contract is missing, return to DDL responsibility
2 Define the query surface	List query scenarios (single instrument/batch/series/latest value)	references/query-design.md
3 Define input parameters	Primary parameters + optional filters; batch upper limit; default value semantics	Required reading references/query-design.md
4 Define disambiguation	Rules for name/alias/code → standardized code	Required reading references/disambiguation.md
5 Define output parameters	Fields, units, magnitude, null value breakdown by criterion	Required reading references/output-semantics.md
6 Define transcription	json→str transcription rules and comparison	Required reading references/json-to-text.md
7 Define pagination performance	page/page_size, batch upper limit, timeout and scan budget	references/query-design.md Section 2
8 Delivery	Produce api-contract.yaml + api-spec.md + examples	references/contract-deliverables.md

Hard requirements

1. Read-only review. During design/troubleshooting, use only read-only access; do not directly deploy or modify production interfaces unless the user explicitly approves.
2. Restrained input parameters. Input parameters must not introduce complexity beyond what is necessary; guide users who want complex combined queries to the SQL/data warehouse process, and do not pile up parameters at the interface layer.
3. Null values must have a criterion. Not found/data not yet available/non-trading/not applicable/unknown are output in separate columns; bare null mixing is prohibited, and using 0 or -1 to impersonate null values is prohibited.
4. Consistent field semantics. Output parameter fields have the same name and meaning as the DDL contract; units, enums, and time zones are consistent with the contract.
5. Units and magnitude explicit. Structured fields retain original units (yuan/share/%); magnitude conversion (ten thousand/hundred million) appears only in the readable transcription layer and is marked "approximately".
6. Honestly inform when disambiguation has no hit. When the disambiguation service returns no result, output the null value criterion NOT_FOUND("instrument not found"), do not guess or fabricate codes; incorrect matching is not the responsibility of the query interface.
7. Budget in contract. Pagination upper limit, batch upper limit, timeout, and scan budget are written into the contract; example queries are limited in scope.
8. Evidence grading. Design basis is marked OBSERVED/INFERRED/CONFIRMED; field criteria can be written into api-contract.yaml only with contract or user confirmation.

Execution process

1. Confirm boundaries. Record the data source tables, consumers, invocation method, deliverables, and whether deployment is allowed.
2. Investigate the data source. Read the contract.yamlproduced by the DDL (field semantics/keys/temporality), the target table structure, existing interfaces, and callers.
3. Define the query surface. List queries by consumption scenario: single instrument single day, single instrument interval, multi-instrument comparison, batch latest values, etc.; one interface, one positioning.
4. Define input parameters. Primary parameters (instrument, time range, field set, pagination) + high-frequency filters; specify default value semantics and batch upper limit.
5. Define disambiguation. Encapsulate the existing disambiguation service (batch query takes top-1), and use the returned standardized code as the query key; no hit → NOT_FOUND; do not make candidate, confidence, or ambiguity judgments (see disambiguation.md）。
6. Define output parameters. According to output-semantics.md define fields, units, magnitude, null value breakdown by criterion, and enum interpretation.
7. Define transcription. Follow json-to-text.md the json→str rules and produce comparison examples.
8. Define pagination and performance. page/page_size limits, batch limits, timeouts, and scan budgets.
9. Deliver. Produce api-contract.yaml、api-spec.md, examples; connect with QC interface-layer defects (see contract-deliverables.md）。

See examples/few-shots.md。

Deliverable Requirements

• Interface Contract api-contract.yaml: for each query, the query_id, input parameters (name/type/required/default/limit), output schema (field/type/unit/null-value convention/enum values), pagination and performance budget, data freshness statement.
• Interface Specification api-spec.md: query surface and locating, disambiguation rules, standardized code rules, transcription rules, mapping to data source contracts, list of items to be confirmed.
• Examples examples/: one input/output example per query type; for output, provide both the json and the json→str transcription versions.
• Troubleshooting Report(troubleshooting scenario): evidence level for root cause hypotheses, falsification conditions, fix recommendations; do not write conclusions for unconfirmed root causes.

Situations That Must Stop

• Connection information contains plaintext passwords, private keys, or tokens that would be written into deliverables.
• Only an account with write permissions is available, and a read-only review boundary cannot be established.
• The task requires direct deployment in production or modifying interfaces without explicit user approval.
• The data source structure cannot be confirmed, and a verifiable output schema cannot be written.
• The null-value convention and units cannot be confirmed, yet they are required to be hardcoded into the contract.
• The example query cannot be scoped and may result in an unbounded scan.
• The request is substantively a final conclusion on table creation, pipelines, quality checks, governance, or compliance: save the observation and return to using-data-dev to select the corresponding responsibility.