alchaincyf/huashu-excel

What it solves

huashu-excel addresses the critical issue of "silent errors" in AI-driven data analysis. Standard methods (like using pd.read_excel()) often fail to detect structural anomalies—such as merged cells, multi-level headers, or subtotal rows mixed with raw data—leading to mathematically incorrect results that appear valid. This project provides a rigorous, audit-ready workflow to ensure data integrity and traceability from the raw Excel cell to the final report.

How it works

The project operates as an agent-agnostic "skill" (compatible with Claude Code, Cursor, etc.) that implements a strict eight-step standard operating procedure:

1. Physical Examination: Uses openpyxl to inspect raw cells before loading into pandas to identify structural "dirt" (merged cells, headers, etc.).
2. Cleaning: Transforms data into a tidy format with a traceable audit trail.
3. Alignment: Clarifies definitions and benchmarks with the user after the data is understood.
4. Analysis: Scans for statistical traps (e.g., Simpson's Paradox, ghost groupings).
5. Reconciliation: Uses the Excel sheet's own "Total" rows as checksums to verify calculated results.
6. Delivery: Generates reports in HTML, XLSX, or DOCX.
7. Visual Verification: Checks charts for misleading elements (e.g., ensuring bar chart axes start at 0).
8. Quality Control: Employs a separate agent to independently recalculate results from raw data.

Who it’s for

It is designed for AI agents and users who need professional-grade data analysis where accuracy is non-negotiable, specifically those dealing with messy, real-world business spreadsheets that contain human-entered totals and complex formatting.

Highlights

• Raw-Cell First: Inspects original Excel structures via openpyxl before pandas processing to prevent information loss.
• Checksum Integration: Treats existing "Total" rows in spreadsheets as ground-truth verification points rather than noise.
• Perceptual Accuracy: Implements chart selection based on the Cleveland-McGill perception hierarchy (e.g., refusing pie charts for more than 3 categories).
• Robust Statistics: Defaults to five-number summaries (Tukey's resistant statistics) instead of means to handle skewed business data.
• Minimal Dependencies: Core examination scripts require only openpyxl or the standard library, ensuring they run in restricted environments.