{"id":"historic-sql-table-digest","name":"historic_sql_table_digest","summary":"変更された履歴SQLテーブル使用バケットを、型付きテーブル使用証拠に変換し、決定性_schema投影します。","body":"# Historic SQL Table Digest\n\nUse this skill when the WorkUnit raw file is one `tables/<schema>.<name>.json` file from the `historic-sql` adapter.\n\n## Required Workflow\n\n1. Read the WorkUnit notes first.\n2. Call `read_raw_file` for the single `tables/<schema>.<name>.json` raw file.\n3. Read `manifest.json` only if the table JSON omits the dialect or the WorkUnit notes are unclear.\n4. Produce one concise usage narrative for this table from the staged table JSON.\n5. Call `emit_historic_sql_evidence` exactly once with `kind: \"table_usage\"`.\n6. Stop after the evidence tool succeeds.\n\n## Identifier Verification Protocol\n\nBefore writing a wiki page or SL source on any topic:\n\n1. `discover_data({query: \"<topic>\"})` - see what wikis, SL sources, and raw\n   tables already exist. Prefer updating existing pages over creating new ones.\n\nBefore emitting any `schema.table` or `schema.table.column` into a wiki body,\nSL source, `tables:` frontmatter, `sl_refs`, or `emit_unmapped_fallback`:\n\n2. `entity_details({connectionId, targets: [{display: \"<identifier>\"}]})` -\n   confirm the identifier resolves; inspect native types, FK/PK, and\n   sampleValues.\n3. For literal values from the source, such as status codes or plan tiers,\n   check whether they appear in `entity_details` sampleValues for the relevant\n   column. If sampleValues is short or the sample may have missed real values,\n   run a `sql_execution` probe with the same warehouse connection id:\n   `sql_execution({connectionId, sql: \"SELECT DISTINCT <col> FROM <ref> LIMIT 50\"})`.\n4. If the candidate identifier still does not resolve, do one of:\n   - Use `sql_execution({connectionId, sql: \"SELECT 1 FROM <ref> LIMIT 0\"})`.\n     If it errors, the identifier is fictional.\n   - Wrap the identifier in `[unverified - from <rawPath>]` in the wiki body,\n     citing the exact raw path that mentioned it.\n   - When recording `emit_unmapped_fallback` with `no_physical_table`, include\n     the failing probe error in `clarification`.\n5. Never copy `<schema>.<table>` placeholder strings from these instructions\n   into output.\n\n## Evidence Shape\n\nCall `emit_historic_sql_evidence` with this shape:\n\n```json\n{\n  \"kind\": \"table_usage\",\n  \"table\": \"public.orders\",\n  \"usage\": {\n    \"narrative\": \"Orders are repeatedly queried for paid/refunded lifecycle analysis and customer-level rollups.\",\n    \"frequencyTier\": \"high\",\n    \"commonFilters\": [\"status\", \"created_at\"],\n    \"commonGroupBys\": [\"status\"],\n    \"commonJoins\": [{ \"table\": \"public.customers\", \"on\": [\"customer_id\"] }],\n    \"staleSince\": null\n  }\n}\n```\n\nThe `usage` object must match `tableUsageOutputSchema`.\n\n## Interpretation Rules\n\n- Treat `columnsByClause.where` as common filters.\n- Treat `columnsByClause.groupBy` as common group-bys.\n- Treat `observedJoins` as common joins.\n- Use `stats.executionsBucket`, `stats.distinctUsersBucket`, and `stats.recencyBucket` to choose `frequencyTier`.\n- Use `frequencyTier: \"high\"` only when executions and distinct users are both broad.\n- Use `frequencyTier: \"mid\"` for repeated team usage that is not broad enough for high.\n- Use `frequencyTier: \"low\"` for low-volume but present usage.\n- Use `frequencyTier: \"unused\"` only when the table input explicitly says the table is stale or has no recent templates.\n- Keep `narrative` short and concrete.\n\n## Boundaries\n\n- Do not call wiki_write.\n- Do not call sl_write_source.\n- Do not call sl_edit_source.\n- Do not call context_candidate_write.\n- Do not emit more than one table usage evidence object.\n- Do not invent columns, joins, or tables that are absent from the staged JSON.","author":"@Kaelio","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/Kaelio/ktx/tree/main/packages/cli/src/skills/historic_sql_table_digest","license":"Apache-2.0","category":"writing","lang":"en","tokens":879,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}