Faster management reporting · From one-off analysis to reusable knowledge assets
This deck answers four questions: what makes the work painful, how the method addresses it, where efficiency improves, and which gains were measured in recorded runs.
The next three statements came from a requirements meeting on 2026-07-29.
They show why monthly work remains difficult after the original owners leave.
This is the monthly management-reporting cadence. The real window is the three days between receiving workbooks on the 6th and the meeting on the 9th, when reports from dozens or hundreds of business units must become one signable management report.
3rd Business units submit forecasts 5th Accounting closes the books 6th Business units submit actuals ────┐ 7th Company-level figures produced │ These are the three days 8th Management-review materials ────┘ 9th Business performance review
skill/excel-ai-analyst/scripts/ws_init.sh ·
Dates follow the business team's working definition; the meeting did not distinguish calendar days from business days when referring to the 6th and 9thSomeone saves a values-only copy and the external links disappear. The workbook still opens and the numbers remain, but their provenance is gone.
Eleven cells in a column contain formulas, while H7 is a constant. A manual review will almost certainly miss it.
Management basis / disclosure basis / YTD / BKD... If definitions are not recorded, everyone has to remember them independently.
The next person treats “this special handling” as a rule, turning an exception into policy.
What they share: none makes the program fail. The error reaches the business-review meeting before a person spots it, if anyone spots it at all.
Converting Excel to text removes the formulas. The AI sees the result, not how the result was produced.
When it does not understand something, it may guess and make the guess sound convincing. A wrong answer with authority costs more than no answer.
Each run starts from zero. Business experts must explain this month what they already explained last month.
| In Excel | It really is | So the method should |
|---|---|---|
| Column names | Variable names | Build a field ontology first and define what every variable means |
| Formulas | Functions | Reconstruct the formula chain and map the calls |
| Cross-sheet references | Module dependencies | Map dependencies first and treat broken links like compilation errors |
| Check columns / total rows | Unit tests | Run the test cases left by the original author |
| “I understand this workbook” | A hypothesis to validate | Run regression over the full dataset and accept it only if it passes |
Software engineering already has methods for undocumented legacy code. This workflow applies those methods to workbook structure, formulas, dependencies, and checks.
=D4+E4-G4, but it cannot infer “Column G is the employee social-insurance contribution, capped by local minimum and maximum bases, and not deducted in the month of departure.”
Those definitions require AI interpretation and human review because business meaning is not fully stored in the workbook.This is the one non-negotiable rule in the method. The product enforces it by refusing to conclude when it cannot understand, instead of producing a clean-looking answer.
Every row reconciles and no table-level exception remains. Only then is the workbook understood.
The data or its definition has a problem; the report indicates where to investigate.
The configuration is invalid, so validation did not occur. It is never downgraded to “mostly passed.”
The rule passes over the full dataset and leaves evidence.
A sample is insufficient because management-reporting problems usually hide in a few exceptional rows.
A business expert confirms each item and an accountable business owner is named.
A digital worker cannot sign off. AI cannot approve or publish its own output.
① EXTRACT ② REVIEW ③ RETAIN ④ REUSE AI reads the workbook → Experts confirm each item → Save to the ontology → Next month, analysts and writes executable “Does it mean this?” registry and publish write zero config lines rules │ │ └──────── Next extraction produces fewer questions ─────┘
The second review should contain fewer items to confirm than the first. If the count does not fall, the knowledge grain or domain boundary is wrong; redesign it instead of scheduling more meetings.
Only propose a general rule after something happens at least three times and is handled consistently each time. Otherwise, keep it in the exception register. Turning an accident into policy is more dangerous than manual work.
First define how the work is done today. Without a baseline, speed figures are meaningless.
| Activity | Current state | Target |
|---|---|---|
| End-to-end monthly consolidation | Three people for two days, plus several investigation rounds | One batch run in < 30 minutes Excludes human confirmation |
| Variance localization | Review each business unit manually | At most three attribution candidates per variance Top candidate hit rate ≥60%, tested after three months |
| New analyst onboarding | Two-hour handoff recording plus months of trial and error | Read the knowledge base and run the full workflow once Rerun independently within one day |
PRD/excel-ai-analyst-PRD-v2.0.mdAnalysts hand-write every validation rule for every workbook;
business experts explain the same definitions again;
a new owner takes over → start from the beginning.
Rules confirmed by business experts in the previous period are automatically added to this period's validation list
and aligned to the current workbook using the saved column mapping.
examples/mvp_selftest.sh (real path: generate a draft directly from the workbook) ·
Two additional checks are suggested automatically from the table pattern, so the analyst does not write those eitherA rule uses an alias such as DEPT, but
only the original spec knows which column that alias means. A changed workbook next period cannot run if the alias no longer aligns.
The rule expects DEPT, while the workbook column is named “Department”; the names do not match.
Worse, “Amount” could be matched to “Amount including tax,” causing the rule to test the wrong column silently and report a clean ✅.
Store “DEPT = Department” with the rule and reuse it next period.
If alignment fails, name the failure and never guess, then list every available column for a person to select.
ontology_registry.py payload.aliasColumns ·
excel_ai.py align_aliases_to_columns() ·
self-test #44–#49 MEASUREDReport broken links, circular references, and wide-range references together. If links are broken, request the original workbook first. Ten minutes here costs less than three hours of guessing later.
When dozens or hundreds of business units run together, one failure does not stop the batch; the summary names the failed items.
Each variance identifies a routing layer and attribution candidates: check internal consistency before external reconciliation. Most mismatches originate in those internal steps.
excel_ai.py · references/patterns/ ·
executed import --from domain MEASUREDSanitized packaging once consumed disproportionate memory: a 17 MB workbook occupied 1.7 GB. With dozens or hundreds of business units in real reporting, the process would exhaust memory immediately.
73.5 seconds · about 104× amplification
The entire workbook remained in memory
32.6 seconds · one-eighth the memory and more than twice as fast
One streaming pass retains only bounded data
CHANGELOG.md · Three root causes: avoid a whole-workbook object graph,
process merged cells by region count, and locate raw-value provenance on demandH7 was independently caught by row recalculation and formula-break detectionexamples/{mvp,m,e1}_selftest.sh · run_demo.sh ·
Note: assertion count is not test coverage| Claim | Status | Evidence |
|---|---|---|
| Confirmed rules activate next period with zero analyst-authored config lines | MEASURED | Self-test #44–#47 on demo data |
| 19 checks / 18 subcommands / 9 table patterns / 57 imported knowledge records | MEASURED | Counted directly from the code at the time; 57 is the executed import result |
| Sanitized packaging uses one-eighth the memory with byte-identical output | MEASURED | 17 MB workbook, 1762 MB → 215 MB |
| One monthly consolidation batch in < 30 minutes | TARGET | Measure S1 · the current-state baseline has not itself been measured |
| At most 3 attribution candidates per variance; top-candidate hit rate ≥60% | TARGET | Measure S2 · requires a three-month retrospective test |
| A new analyst can rerun independently within one day | TARGET | Measure S6 · baseline is a two-hour recording plus months of exploration |
| Review throughput ≥30 items per hour | TARGET | Measure S4 · otherwise knowledge remains in draft |
| The second review has fewer items to confirm than the first | TARGET | Milestone MS6 · the real success criterion, requiring two periods of real data |
PRD/excel-ai-analyst-PRD-v2.0.md ·
Milestones: project development-plan documentationThe meeting was explicit: “Our most confidential data is all here” and “the entire computer can remain off the public internet.” The system was therefore designed as two tracks from the start.
INTERNAL MACHINE (DATA STAYS IN-DOMAIN) SAFE TO SEND TO AN EXTERNAL MODEL
┌────────────────────┐
│ Original workbook │ ← Always remains here
│ │ │
│ ▼ │
│ Sanitized package │ ──────▶ Multi-row headers and column shapes
│ │ Formula templates for each column
│ Numeric validation│ Cross-workbook dependency graph
│ (local, offline) │ Row/column scale and orders of magnitude
└────────────────────┘ Zero raw amounts / names / client namesStructural information is sufficient for AI to reconstruct formula chains, draw lineage, and formalize rules.
Numeric validation runs inside the internal network; it needs neither internet access nor AI.
The column-name restoration mapping is isolated separately and excluded from the sendable list.
Packaging uses a file allowlist instead of “zipping the directory.” The latter is easier, but also much riskier.
The ontology stores structures and rules. If a verbatim statement containing a specific amount enters the knowledge base,
it could propagate into cross-workspace reuse or external transfer.
Every import is scanned and the entire batch is rejected on detection.
The table below records the current limits.
| Unavailable / unfinished | What it means |
|---|---|
| Not yet run on real management-reporting data | All figures come from constructed demo data. Real scale, broken links, and dirty data have not yet been encountered |
| Steps 2 / 3 cannot be automated | AI must read the supporting material and author field meanings and formula chains; scripted guessing would harden misunderstandings |
| AI cannot approve or publish | This is an intentional governance constraint, not a capability gap. A human must remain in the loop |
| Automatic exception promotion is not implemented | The “promote only after ≥3 consistent occurrences” discipline is currently enforced by people, not the tool |
| Multi-user team spaces and permissions are not implemented | The current local fallback treats each directory as a workspace. A unified entry point and account system depend on company infrastructure |
| Flywheel compounding is unvalidated | Two periods of real data are required to learn whether the second review is genuinely easier |
CHANGELOG.md ·
“Known boundaries” in runtime/registry/README.mdThe meeting stated: “Just name one person as the interface.”
That business-expert contact is the only role that can confirm definitions. Knowledge cannot enter the platform without an accountable business owner.
this is a hard validation, not a process suggestion.
One command creates the workspace; another completes external-link mapping, structural profiling, and sanitized packaging.
The workflow needs originals, not values-only copies.
Double-click a web file, review one item per screen, and export when done.
This step does not need to wait for data preparation; review and data processing can proceed in parallel.
No matter how fast a tool runs, it only finishes this month's work.
The largest efficiency gain is avoiding the same explanation next month.
Write “who owns each issue and how to fix it,” not a pile of metrics.
Do not conclude before validation runs. A 98% pass rate is not a pass. A profile always calls itself a “machine hypothesis.”
Say clearly what cannot be calculated and never pretend an unavailable capability exists. That applies to this deck too.