Table Grounding

Table Grounding

Convert a table file into a structured table-grounding bundle.

This skill is for table grounding, not a polished final report. It should produce a stable intermediate bundle that is easy for downstream skills and agents to use.

When to Use

Use this skill when:

• the input is a .xlsx or .csv file
• the file mainly contains tabular data
• you need a structured grounding note before downstream follow-up work
• you want schema, preview rows, summary statistics, and simple charts before writing conclusions

Do not use this skill when:

• the input is a PDF, DOCX, Markdown, or plain text document
• the goal is a polished final report
• the input is not primarily tabular

Input

A single table file:

• .xlsx
• .csv

For .xlsx, the default behavior is to use the first sheet. If a specific sheet is provided, use that sheet instead. Do not silently merge multiple sheets in the first version.

The table may contain:

• numeric columns
• categorical columns
• date/time columns
• missing values
• duplicated rows
• messy column names
• mixed types
• derived or computed columns

Output Bundle

Write outputs under:

data/grounded_notes/<type>-<table_id>/

If a specific xlsx sheet is selected, the bundle directory may include a sheet suffix.

Examples:

• data/grounded_notes/xlsx-sales_q1/
• data/grounded_notes/xlsx-sales_q1-sheet-Summary/
• data/grounded_notes/csv-benchmark_results/

The bundle should contain:

<bundle_dir>/
├─ extracted.md
├─ extracted_meta.json
├─ schema.json
├─ summary_stats.json
├─ asset_index.json
└─ assets/
   ├─ previews/
   │  ├─ head.csv
   │  ├─ sampled_rows.csv
   │  └─ column_summary.md
   └─ charts/
      ├─ chart_001.png
      ├─ chart_002.png
      └─ ...

Important:

• The script stage must not generate a placeholder grounded.md.
• The agent must read the bundle and then write a real grounded.md.

Required Workflow

When using this skill, you must follow this workflow:

1. First run the existing script entrypoint:

   bash .cursor/skills/table-grounding/scripts/run.sh <input_path> <output_root> [sheet_selector]

2. Do not manually reimplement schema extraction, summary statistics, preview generation, or chart generation if the existing script can already do it.

3. After the bundle is generated, read:

   • extracted.md
   • extracted_meta.json
   • schema.json
   • summary_stats.json
   • asset_index.json
   • assets/previews/*
   • assets/charts/*

4. Then write a real grounded.md into the same bundle directory.

5. The task is not complete if only the bundle files exist but grounded.md has not been written.

6. The task is also not complete if grounded.md is written without first generating and using the bundle evidence.

Grounded Output

After the bundle is generated, write grounded.md in the same bundle directory.

Return markdown with exactly these sections:

# Table Grounding

## 1. Main Topic / Purpose
[2–4 sentence statement of what this table or dataset appears to describe.]

## 2. Main Fields
- [One bullet per major field or field group]

## 3. Key Signals
- [Important trends, contrasts, distributions, or clusters strongly supported by the table]

## 4. Anomalies / Outliers
- [Only clearly unusual values, missing patterns, inconsistent rows, sharp jumps, duplicates, or suspicious records]

## 5. Possible Supported Conclusions
- [Only cautious conclusions supported by the data]
- [Do not turn correlation into causality]

## 6. Risks / Data Quality Issues
- [Missing values, sparse columns, duplicated rows, unclear schema, inconsistent units, tiny sample size, etc.]

## 7. Suggested Next Checks
- [Concrete next-step analyses or validation directions grounded in the table]

## 8. Search Keywords

### Problem Keywords
- ...

### Method / Solution Keywords
- ...

### Domain / Constraint Keywords
- ...

Instructions

• Do not write a polished final report.
• Do not invent business context, causal claims, owners, deadlines, or metadata not supported by the table.
• Do not turn weak correlations into strong conclusions.
• Do not ignore missing values, duplicates, or unclear schema.
• You must reuse the existing scripts/run.sh and scripts/ground_table.py workflow directly.
• Do not replace the existing extraction / statistics / chart pipeline with ad hoc analysis unless a minimal necessary fix is required.
• The script stage is the required evidence-building stage.
• grounded.md must be based on the generated bundle rather than on direct free-form inspection alone.
• Use the generated bundle as evidence:
  • extracted.md
  • extracted_meta.json
  • schema.json
  • summary_stats.json
  • asset_index.json
  • assets/previews/*
  • assets/charts/*
• If AssetRef blocks appear in extracted.md, inspect those referenced assets before writing grounded.md.
• Keep the output concise and structured.