collect-factchart-data
Collect, inspect, validate, normalize, and document FactChart source data for an operator-authorized derivative information service, including Korean-equity prices, disclosures, news, company_info, ma
SKILL.mdskills/collect-factchart-data/SKILL.md
GitHubCollect FactChart Data
Receive FactChart source information, validate it, and prepare clearly separated raw and derived records for the authorized derivative information service.
Project boundary
- Record that the project owner states FactChart's operator has authorized source-data receipt for a derivative information service.
- Treat the actual partnership agreement as controlling for endpoints, frequency, storage, transformation, redistribution, attribution, security, and commercial use.
- Do not claim the repository independently verifies or stores the agreement.
- Keep data collection separate from buy/sell classification, portfolio advice, target-price decisions, or order execution.
Required reference
Read references/factchart-data-guide.md completely before calling or documenting FactChart endpoints. It contains the tested schemas, company-tab behavior, comparison-group logic, authorization context, known defects, request examples, and operating checklist.
Read references/factchart-output-contract.md completely before shaping or handing off collected data. Emit schema_version: "factchart-handoff/1.0" and keep raw provider fields, normalized values, quality state, discovery leads, and downstream-use allowlists separate.
Workflow
- Fix the retrieval time,
Asia/Seoultimezone, FactChart company name, KRX ticker/market, and official DART company identifier. Do not join records on company name alone when identity is ambiguous. - Confirm the intended operation is within the partnership scope. Do not infer that a browser-visible
anonkey grants additional rights. - Select only the necessary source:
stock_data.jsonfor the 348-stock bundle, market/finance snapshots, and cached discovery.- Supabase
prices,disclosures,news, orcompany_infofor one-stock retrieval. - The versioned
app.jsmetadata only when reproducing the site's client-side sector or company-tab logic.
- Pass the current API key through a session secret or environment variable. Never commit, print, log, or embed it in documents or command history.
- Collect with one concurrent request, the agreement's rate limit, deterministic secondary sorting, bounded retries, and cache reuse. Prefer a single filtered request over copying the site's parallel peer requests.
- Record HTTP status, endpoint and selected fields, retrieval time, response date range,
Content-Range, row count, schema, and response hash when reproducibility matters. - Paginate until collected rows equal the exact total. Deduplicate prices by instrument/date, disclosures by
rcp_no, news by stable ID/URL, and company rows by the verified instrument identity. - Normalize raw provider fields without overwriting them. Store provider values, normalized values, formulas, units, period labels, and validation flags separately.
- When raw records need deterministic shaping, run
python scripts/normalize_factchart_data.py normalize INPUT.json --output HANDOFF.json, then validate withpython scripts/normalize_factchart_data.py validate HANDOFF.json. Use the input envelope and output structure defined in references/factchart-output-contract.md. This tool performs no network access, accepts no credentials, preserves provider fields, deduplicates records, computes only scale-independent ratios, and leaves unsafe fields off the engine allowlist. - Apply the quality gates below. Mark an observation
unverified,delayed,stale,truncated, ordefinition_unknowninstead of silently repairing uncertainty. - Produce one
factchart-handoff/1.0object and a primary-source follow-up list. Hand off to a separate analysis skill only after material claims are checked against DART, KRX, company IR, or another documented primary source.
Company and comparison data
- Retrieve company fundamentals from
company_info; combine them with price and market snapshots only after recording each component's timestamp. - Recompute debt ratio, ROE, operating margin, equity ratio, EPS, BPS, PER, PBR, and any derived valuation from preserved inputs.
- Treat
y0/y1/y2, TTM fields, and bundlefinfields as different definitions until their accounting periods and formulas are verified. - Reconstruct comparison candidates from the versioned
STOCK_METAandbigSector()logic only when required. - Label those names
broad sector candidates, never verified competitors or related businesses. Report the valid sample count separately for every metric. - Do not promote the site's simplified PER/PBR/DCF reference values into an investment conclusion.
Hard quality gates
- Do not use REST disclosure
changedirectly. Recomputer0/r1/r5from verified prices and the DART publication time using the event-session rules in the reference. - Do not call a REST result complete unless
Content-Rangetotal equals the post-deduplication collected count or the discrepancy is explained. - Do not treat an empty array as proof that a company has no data; distinguish unsupported name, spelling, renamed issuer, temporary omission, and genuine absence.
- Do not use FactChart prices as a full quantitative price ledger: daily volume, adjustment policy, corporate actions, delistings, exchange, currency, and point-in-time universe rules are incomplete.
- Do not mix REST prices, bundled market snapshots,
company_info.updated_at, TTM fields, and annual fields without explicit timestamps and definitions. - Do not score provider-defined sentiment,
amt10, PER/PBR/ROE,tone, orprice_reactionwhen the formula or period is unknown. - Stop and report a schema or access change instead of bypassing authentication, authorization, rate limits, or service controls.
Output contract
Follow references/factchart-output-contract.md. Return or store:
- Authorization context and partnership-scope note.
- Instrument identity: FactChart name, KRX ticker/market, DART identifier, and any unresolved mismatch.
- Retrieval ledger: endpoint, fields, timestamps, row counts,
Content-Range, hashes, and application-script version when used. - Raw coverage summary for prices, disclosures, news, company information, market, finance, and comparison metadata.
- Normalized and derived fields with units, periods, formulas, and provenance.
- Data-quality findings, including freshness, truncation, nulls, duplicates, definition conflicts, and mixed timestamps.
- Broad comparison candidates with metric-specific valid sample counts and a warning that they are not confirmed competitors.
- Primary-source verification queue for DART, KRX, issuer IR, and article originals.
- A clear statement of what is safe for discovery, safe for the derivative service, or blocked from downstream quantitative analysis.
Do not emit an undocumented ad hoc shape. When a requested source is absent, retain its contract container and record null, an empty array, or a quality flag as specified; never make a downstream skill guess whether omission means unsupported, unrequested, failed, or genuinely empty.
Generate a deterministic example when testing the tool or teaching a downstream consumer the contract:
python scripts/normalize_factchart_data.py demo --output factchart-demo-handoff.json
python scripts/normalize_factchart_data.py validate factchart-demo-handoff.json