Kaelio/ktx / packages/cli/src/skills/historic_sql_table_digest
historic_sql_table_digest
UnverifiedConvert one changed historic-SQL table usage bucket into typed table usage evidence for deterministic _schema projection.
Historic SQL Table Digest
Use this skill when the WorkUnit raw file is one tables/<schema>.<name>.json file from the historic-sql adapter.
Required Workflow
- Read the WorkUnit notes first.
- Call
read_raw_filefor the singletables/<schema>.<name>.jsonraw file. - Read
manifest.jsononly if the table JSON omits the dialect or the WorkUnit notes are unclear. - Produce one concise usage narrative for this table from the staged table JSON.
- Call
emit_historic_sql_evidenceexactly once withkind: "table_usage". - Stop after the evidence tool succeeds.
Identifier Verification Protocol
Before writing a wiki page or SL source on any topic:
discover_data({query: "<topic>"})- see what wikis, SL sources, and raw tables already exist. Prefer updating existing pages over creating new ones.
Before emitting any schema.table or schema.table.column into a wiki body,
SL source, tables: frontmatter, sl_refs, or emit_unmapped_fallback:
entity_details({connectionId, targets: [{display: "<identifier>"}]})- confirm the identifier resolves; inspect native types, FK/PK, and sampleValues.- For literal values from the source, such as status codes or plan tiers,
check whether they appear in
entity_detailssampleValues for the relevant column. If sampleValues is short or the sample may have missed real values, run asql_executionprobe with the same warehouse connection id:sql_execution({connectionId, sql: "SELECT DISTINCT <col> FROM <ref> LIMIT 50"}). - If the candidate identifier still does not resolve, do one of:
- Use
sql_execution({connectionId, sql: "SELECT 1 FROM <ref> LIMIT 0"}). If it errors, the identifier is fictional. - Wrap the identifier in
[unverified - from <rawPath>]in the wiki body, citing the exact raw path that mentioned it. - When recording
emit_unmapped_fallbackwithno_physical_table, include the failing probe error inclarification.
- Use
- Never copy
<schema>.<table>placeholder strings from these instructions into output.
Evidence Shape
Call emit_historic_sql_evidence with this shape:
{
"kind": "table_usage",
"table": "public.orders",
"usage": {
"narrative": "Orders are repeatedly queried for paid/refunded lifecycle analysis and customer-level rollups.",
"frequencyTier": "high",
"commonFilters": ["status", "created_at"],
"commonGroupBys": ["status"],
"commonJoins": [{ "table": "public.customers", "on": ["customer_id"] }],
"staleSince": null
}
}
The usage object must match tableUsageOutputSchema.
Interpretation Rules
- Treat
columnsByClause.whereas common filters. - Treat
columnsByClause.groupByas common group-bys. - Treat
observedJoinsas common joins. - Use
stats.executionsBucket,stats.distinctUsersBucket, andstats.recencyBucketto choosefrequencyTier. - Use
frequencyTier: "high"only when executions and distinct users are both broad. - Use
frequencyTier: "mid"for repeated team usage that is not broad enough for high. - Use
frequencyTier: "low"for low-volume but present usage. - Use
frequencyTier: "unused"only when the table input explicitly says the table is stale or has no recent templates. - Keep
narrativeshort and concrete.
Boundaries
- Do not call wiki_write.
- Do not call sl_write_source.
- Do not call sl_edit_source.
- Do not call context_candidate_write.
- Do not emit more than one table usage evidence object.
- Do not invent columns, joins, or tables that are absent from the staged JSON.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |
| Agent Cost Reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |