TBM Cost Pool Mapper

Finding these files: The references/ folder is in the user's local working directory — the folder where the user is running this analysis. Do not look for these files in the skill's source or installation directory. Check these locations in order and use the first match found:

1. {workspace_dir}/references/ — the user's current working directory
2. {skill_base_dir}/references/ — the skill pack's own installation directory
3. If neither location yields the files, ask the user to confirm where their reference files are located or to paste the relevant content directly into the conversation.

These references are your source of truth. When in doubt about a classification, defer to the definitions in these files rather than general knowledge.

Core Workflow

Step 1: Understand the Input Data

Ask the user to provide or describe their spend data. Common formats include:

• GL extract (CSV, XLSX) with account codes, descriptions, and amounts
• Budget file with line items and cost centers
• Chart of accounts listing
• Free-text list of spend categories they need to classify

If the user uploads a file, read it and identify the relevant columns. You need at minimum:

• Account identifier (GL code, account number, or description)
• Account description (the human-readable name — this is the primary classification input)
• Amount (for summarization; classification works without it but totals add value)
• Cost center or department (helpful context for ambiguous items)

The user must also provide information on whether the file represents actuals, forecast, or budget data. This can have a significant impact on the classification approach, as it will help establish the grain of the data for that scenario type.

If the data is messy or missing columns, work with what's available. A list of account descriptions alone is enough to classify.

Data alignment prerequisite: If the user is providing both budget and actuals data from different source systems (e.g., budget from Adaptive or Anaplan, actuals from SAP or Oracle ERP), check whether the GL account codes and cost centers align across both datasets before classifying. If GL structures differ — different account numbering, different granularity, or COA changes between periods — recommend running the TBM Data Reconciliation Mapper (A0) first. A0 produces a unified GL file with a common account structure that is then passed to this skill. Attempting to classify misaligned budget and actuals data separately and then comparing them in B2 produces false VD.4/VD.5 variance codes that obscure genuine business events.

Step 1b: Set Materiality Threshold and Scope the Work

Before classifying any line items, define the analysis scope with the user. This prevents spending time on immaterial items and produces a transparent, defensible v1 model.

Establish a materiality threshold:

Ask the user: "What is the minimum dollar amount for an item to receive individual classification?" A threshold of $5,000–$25,000 is typical depending on total spend volume. Items below the threshold are excluded from item-level analysis by design — this is a scoping choice, not a quality gap.

This creates three explicit buckets. All three must reconcile to the GL total at all times:

Reconciliation requirement — enforce this at all times:

Analyzed ($) + Not Analyzed ($) = GL Total ($)

Record the threshold chosen and the dollar amount of Not Analyzed items before proceeding. These figures must appear in the Pool-Level Summary Table and in the Narrative Summary.

Acceptable Unresolved size: Flag as a model risk if Unresolved items exceed 10% of the Analyzed amount. If Unresolved exceeds 20%, the model is not ready to present — resolve more items or explicitly frame as preliminary.

If the user provides a pre-filtered dataset, confirm the threshold they applied and ask for the total excluded dollar amount so the reconciliation holds.

Step 2: Classify Each Line Item to Cost Pool and Cost Sub-Pool

For every spend line item, assign it to exactly one of the nine TBM v5.0.1 cost pools AND one cost sub-pool within that pool. This is a two-level classification.

Pre-Classification: Check the Bundled Contract Registry

Before classifying any line item, scan its vendor name and GL description against references/Bundled_Contract_Registry.md. This check happens first — before applying any pool definition or decision rule.

If the line item matches a registered contract:

1. Replace the single bundled row with one output row per component using the registered breakdown percentages.
2. Apply the cost pool, sub-pool, and CapEx/OpEx assignment from the registry entry to each component row.
3. Set confidence based on the registry entry's Status field:
   • Confirmed → High confidence on all component rows
   • Estimated → Medium confidence on all component rows; include the stated verification action in Review Items
4. Do not carry the original bundled row forward into the output — it no longer exists as a single classification unit.

If the line item does not match any registered contract and appears to be a bundled or multi-component spend item (e.g., "Professional Services & Licenses - Vendor X"), apply the standard bundled contract guidance in references/Classification_Decision_Rules.md and flag it in Review Items.

This sequence — registry check first, then pool definitions, then decision rules — ensures bundled contract splits are resolved at classification time, not discovered afterward during review.

The Nine Cost Pools

Cost Sub-Pools by Pool

Each pool has standardized sub-pools. Assign every item to the most specific sub-pool that applies:

Staffing: Internal Labor | Staff Augmentation | Other Operating | Internal Labor Capital | Staff Augmentation Capital

Outside Services: Consulting | Managed Services | Other Operating | Capital

Cloud Services: Cloud Service Provider | Other Operating | Capital

Hardware: Lease | Maintenance & Support | Depreciation & Amortization | Managed Services | Other Operating | Capital

Software & SaaS: Licensing | Maintenance & Support | Depreciation & Amortization | SaaS | Other Operating | Capital

Data Center Facilities: Lease | Maintenance & Support | Depreciation & Amortization | Managed Services | Other Operating | Capital

Telecom: Lease | Maintenance & Support | Depreciation & Amortization | Managed Services | Other Operating | Capital

Misc Costs: Managed Services | Other Operating | Capital

Cross Charges: By Internal Department | Capital

Classification principles:

• Classify based on what the spend is, not where it lives in the org chart
• When a line item spans multiple pools (e.g., a bundled contract with cloud + consulting), classify to the dominant cost pool unless the user can break it apart. If components are separable and individually significant (>25% of contract value), recommend splitting.
• CapEx is handled through Capital sub-pools within each cost pool, not as a separate dimension. Items meeting capitalization criteria go to the Capital sub-pool of their respective pool.
• Cloud IaaS/PaaS consumption maps to Cloud Services, not Outside Services
• SaaS application subscriptions map to Software & SaaS / SaaS, not Outside Services or Cloud Services
• Contractor/staff augmentation labor goes to Staffing / Staff Augmentation, not Outside Services, unless it's a fully managed deliverable (vendor-managed outcome)
• Depreciation and amortization go to the Depreciation & Amortization sub-pool of the underlying asset's pool

Step 3: Assign Confidence Levels and Surface Rationale

Every classification receives a confidence level: High, Medium, or Low. Confidence is not a measure of how hard you worked — it is a signal to the practitioner about how much additional review a line item warrants before the cost model is finalized. Apply these levels consistently using the criteria below, and always state your reasoning explicitly so the practitioner can validate or override your decision.

High Confidence

The classification is unambiguous given the account description, vendor name, and/or cost center. The line item matches a clear definition in references/TBM_Cost_Pool_Definitions.md with no competing interpretations at either the pool or sub-pool level.

Assign High when:

• The account description and vendor together make both the cost pool and sub-pool obvious (e.g., "AWS Cloud Services" from Amazon Web Services → Cloud Services / Cloud Service Provider)
• The billing model is evident and points to a single pool and sub-pool (e.g., "Staff Augmentation - QA Analysts" from a staffing agency → Staffing / Staff Augmentation)
• The asset type is unambiguous (e.g., "Dell PowerEdge Servers" → Hardware / Capital)

No additional reviewer action is required for High items unless the amount is unusually large relative to the pool total.

Medium Confidence

The classification is the most defensible interpretation given available information, but a reasonable practitioner could argue for an alternative pool or sub-pool, or the correct classification depends on a contract detail or organizational policy that cannot be determined from the GL description alone.

Assign Medium when:

• The vendor provides multiple service types and the description doesn't clarify the delivery model (e.g., "Accenture Professional Services" could be Staffing / Staff Augmentation if T&M or Outside Services / Consulting if deliverable-based)
• The line item is a hybrid of two pools and the dominant component is not clear from the description
• An organizational policy choice determines the correct sub-pool (e.g., a Microsoft EA that bundles licenses, Azure, and M365 — needs contract breakdown to split correctly)
• The pool is clear but the sub-pool is ambiguous (e.g., clearly Hardware but could be Lease, Maintenance & Support, or Capital depending on the transaction type)
• The description is generic enough to match more than one pool (e.g., "Professional Services - Q3")

Do NOT assign Medium solely because capitalization policy was unknown. If the only unresolved question is CapEx vs. OpEx treatment (the cost pool and sub-pool are otherwise clear), consult references/Capitalization_Policy.md and resolve using the Quick-Reference Decision Table there. Items that resolve cleanly under that table are High confidence. Reserve Medium for cases where the policy document itself does not resolve the question (e.g., SaaS implementation phase is unclear from the description).

For every Medium item, state: (1) the pool and sub-pool you've assigned, (2) which alternative pool/sub-pool was considered, (3) the specific fact or contract detail that would resolve the ambiguity, and (4) what action the practitioner should take. Do not leave a Medium classification without a clear "verify by checking X" instruction.

Low Confidence

The available information is insufficient to make a defensible classification at either the pool or sub-pool level. The line item may be misrouted, mislabeled in the GL, or represent a cost type not covered by standard TBM definitions. Silently forcing a classification here would undermine the integrity of the cost model.

Assign Low when:

• The account description is too vague to distinguish between pools (e.g., "Miscellaneous IT Expense" with no vendor or cost center context)
• The vendor name alone is not enough and the description contradicts typical patterns for that vendor
• The amount is material and misclassification would meaningfully distort pool totals
• The item may not be IT spend at all and should not be in scope

For every Low item, state: (1) all plausible pool/sub-pool assignments, (2) why none can be selected with confidence, and (3) what specific information the practitioner needs to gather (vendor contract, billing statement, cost center owner) to resolve it. Flag Low items prominently in the Review Items section — they represent model risk.

When to Consult the Decision Rules Reference

Before assigning Medium or Low, check references/Classification_Decision_Rules.md. Many apparent ambiguities have established resolution patterns (cloud vs. SaaS boundary, staffing vs. outside services, bundled contract treatment). If the decision rules resolve the question, the confidence level may rise to High.

Common scenarios and their typical confidence outcomes:

Step 4: Produce the Output

Generate a structured cost pool and sub-pool mapping. The output should include:

Summary Table (Pool Level):

Classified pool amounts + Unresolved + Not Analyzed must equal the GL Total. Unresolved items carry a cost pool assignment flagged Low confidence; they are included in Review Items and planned for v2 resolution. Not Analyzed items are excluded from pool classification by the materiality threshold set in Step 1b.

Sub-Pool Detail Table:

Detailed Mapping: For each line item:

• Original account code/description
• Assigned cost pool
• Assigned cost sub-pool
• CapEx/OpEx designation (derived from sub-pool: Capital sub-pools = CapEx; all others = OpEx)
• Confidence level (High / Medium / Low)
• Notes (reasoning for Medium/Low confidence items)

Review Items: A separate section listing all Medium and Low confidence classifications with:

• The line item
• Why it's ambiguous
• Recommended classification (pool + sub-pool) with reasoning
• Alternative classification the user might prefer

If the user provided data in a file, output the results in the same format (CSV or XLSX) with the classification columns appended. If working from a text list, produce a clean markdown table.

Step 5: Validate, Version, and Prepare for Presentation

After completing the classification, run this sequence before presenting output to any stakeholder. Each step is a gate, not a suggestion.

5a. Mathematical Validation

1. Confirm: Classified ($) + Not Analyzed ($) = GL Total ($) — no money created or lost
2. Confirm every line item has exactly one cost pool and one sub-pool assignment (or is in Not Analyzed)
3. Confirm pool and sub-pool totals roll up correctly to the GL total

5b. Quality Gate Checklist

5c. Version Labeling

Every cost pool model output must carry a version label. Assign v1.0 to the first model produced. Increment to v1.1, v1.2 (minor refinements) or v2.0 (significant resolution of Unresolved items) for subsequent iterations.

Include a brief version note with the output:

Model Version: v1.0 Analysis Date: [date] Materiality Threshold: $[X] — items below this threshold excluded from item-level classification Not Analyzed: $[X] ([X]% of GL total) — [N] items below threshold, intentionally excluded Unresolved (Low Confidence): $[X] ([X]% of Classified amount) — [N] items flagged for v2 resolution Pending Verification (Medium Confidence): $[X] ([X]% of Classified amount) — [N] items classified with defensible assumptions; verification actions listed in Review Items Planned next iteration: [brief description of what Low and Medium confidence items will be resolved and how]

5d. Distribution Sanity Check and Narrative Summary

1. Sanity check the distribution — if any single cost pool exceeds 60% of total spend, flag it. Typical IT spend distributions have Staffing at 30–45%, with no other pool usually exceeding 25%. Cloud Services may be higher in cloud-native organizations.
2. Check for empty pools — if a pool has zero items, note it. Most IT organizations have spend in at least 6 of the 9 pools. Cross Charges and Misc Costs may legitimately be zero.
3. Highlight the Misc Costs pool — items here represent classification gaps. If Misc Costs exceeds 5% of total, recommend further decomposition.
4. Check Cross Charges netting — if Cross Charges are present, verify they net to zero at the consolidated IT level (debits and credits should balance).
5. Provide a narrative summary — structured in two parts: an Executive Summary followed by a Detail section.

Part 1 — Executive Summary (≤ 200 words)

Write a tight paragraph covering: spend profile (dominant pools, CapEx/OpEx split, cloud posture, labor mix), model coverage ($X of $Y GL total, Not Analyzed amount), and model maturity (version, Unresolved %, Medium confidence %). Close with an unambiguous presentation readiness statement using one of the three verdicts below — no hedging, no conditional language.

Part 2 — Detail (bullet format)

Follow the Executive Summary with a structured bullet section. Include all of the following that apply:

• Spend distribution: one bullet per pool with material spend — amount, % of total, and one-line characterization
• CapEx / OpEx split: total CapEx ($, %) and OpEx ($, %) derived from Capital sub-pools; note any pools driving CapEx
• Cloud posture: cloud spend as % of total; note IaaS/PaaS vs. SaaS breakdown if separable
• Labor mix: internal vs. staff augmentation split within the Staffing pool
• Not Analyzed items: threshold applied, dollar amount excluded, number of items
• Unresolved items (Low confidence): dollar amount, % of Classified, count; one bullet per item with the specific blocker and resolution action
• Pending Verification items (Medium confidence): dollar amount, % of Classified, count; one bullet per item (or per cluster if numerous) with the verification action and who owns it
• Quality gate flags: one bullet per gate that did not pass clean (Misc Costs > 5%, distribution anomalies, Cross Charges netting issues, etc.)
• Planned next iteration: specific items targeted for v2 resolution and the recommended action for each

Example Executive Summary:

This is a cloud-forward IT cost structure with Cloud Services (32%) and Software & SaaS (18%) accounting for half of total spend. Staffing at 29% reflects a 70/30 internal-to-contractor split. CapEx represents 12% of Classified spend, concentrated in Hardware and SaaS implementation projects. This v1.0 model classifies $18.2M of $19.1M total GL spend; $0.9M (4.7%) falls below the $10K materiality threshold and is Not Analyzed by design. Zero items are Unresolved (Low confidence). Seventeen items totaling $39.4M (19.3% of Classified) carry Medium confidence, primarily bundled vendor contracts whose component splits are estimated pending contract schedule confirmation.

PRESENT AS PRELIMINARY. This model should be labeled a preliminary v1.0 when presented to finance leadership. The $39.4M in Medium confidence items — while classified using defensible estimates — requires contract schedule confirmation before the model is treated as final. Verification actions are listed below.

Execution Architecture

The classification workflow is decomposed into four discrete stages, each producing an intermediate file consumed by the next. This stage-gate model keeps each generated output under ~15K characters, eliminates the need to re-run classification if Excel generation fails, and creates a review checkpoint between the judgment-intensive stage and the mechanical stages.

Stage 1: Classify (LLM-generated, ~15K chars max)

What it does: Reads the source CSV, applies the materiality threshold, checks each GL item against the Bundled Contract Registry, and writes a 1_classification_map.csv with these columns:

Unified_GL, Cost_Pool, Sub_Pool, CapEx_OpEx, Confidence, Bundle_Component, Bundle_Pct, Classification_Notes

Key rules for this stage:

• This is the ONLY stage that requires LLM judgment. All other stages are mechanical.
• Each GL line maps to one or more output rows (one row per bundled component, one row for non-bundled items).
• Bundle_Pct = 1.0 for non-bundled items; fractional for bundled components.
• Classification_Notes must include the VERIFY action for every Medium/Low item.
• Write the CSV to the run output folder as 1_classification_map.csv.
• Print a summary to chat: item count, threshold applied, bundled items expanded.

Why this helps: The classification decisions are written as CSV rows (far more compact than embedded Python dict literals). An 89-row classification CSV is ~12K chars including notes — well under the generation budget.

Stage 2: Expand and Calculate (deterministic, ~3K chars)

What it does: Reads the source data CSV and 1_classification_map.csv, joins them on Unified_GL, multiplies Budget/Actual/Forecast amounts by Bundle_Pct, and writes 2_classified_detail.csv with these columns:

Unified_GL, Description, Cost_Center, Vendor, Budget_Amount, Actual_Amount, Forecast_Amount,
Above_Threshold, Cost_Pool, Sub_Pool, CapEx_OpEx, Confidence, Bundle_Component, Classification_Notes

Key rules:

• This is pure arithmetic. No LLM judgment required.
• Verify the reconciliation: sum of classified amounts + not-analyzed amounts = GL total. Print the check.
• Write output to 2_classified_detail.csv.

Why this helps: This stage is <50 lines of Python and produces the master data file that both the Excel generator and the quality gate consume.

Stage 3: Generate Excel (templated, ~12K chars)

What it does: Reads 2_classified_detail.csv and generates the formatted 4-tab Excel workbook (Pool Summary, Sub-Pool Detail, Line Item Detail, Review Items).

Key rules:

• The Excel formatting logic is MECHANICAL and IDENTICAL across runs. Store a reusable template script at references/excel_template.py in the skill folder. If the template exists, read and execute it instead of regenerating the formatting code. If it doesn't exist, generate it once and save it for future runs.
• The template reads 2_classified_detail.csv as its input and accepts the output path as a parameter.
• The template should define formatting constants (colors, fonts, column widths) at the top for easy customization.
• Pool-level summary, sub-pool detail, and quality gate calculations are all derived from the CSV — no hardcoded values.

Why this helps: On repeat runs, this stage requires zero LLM generation — it just executes the saved template. Even on the first run, the template is ~12K chars (formatting code only, without classification data embedded).

Stage 4: Quality Gate and Narrative (LLM-generated, ~2K chars)

What it does: Reads 2_classified_detail.csv, runs all quality gate checks from Step 5, and produces the narrative summary directly in chat (not as a file).

Key rules:

• Calculate all gate metrics from the CSV (reconciliation, Low %, Medium %, Misc Costs %, distribution sanity, cross-charge netting).
• Apply the verdict logic (READY TO PRESENT / PRESENT AS PRELIMINARY / NOT READY TO PRESENT).
• Write the Executive Summary (≤200 words) and Detail section per the format in Step 5d.
• Include the version note block from Step 5c.

Why this helps: The narrative is generated from computed metrics, not from classification logic — it is always small.

Execution Sequence

EXECUTION SEQUENCE:

1. Run Stage 1 (classify). Write 1_classification_map.csv. Pause.
   → Show user: "Classification complete. [N] items classified, [M] bundled items expanded.
     Review 1_classification_map.csv before proceeding?"
   → User can inspect/adjust the CSV at this checkpoint.

2. Run Stage 2 (expand). Write 2_classified_detail.csv.
   → Print reconciliation check to chat.

3. Run Stage 3 (generate Excel).
   → If references/excel_template.py exists: execute it.
   → If not: generate the template, save it to references/excel_template.py, then execute it.
   → Save Excel to run output folder.

4. Run Stage 4 (quality gate + narrative).
   → Print full narrative summary to chat.
   → Link the Excel file for user download.

IMPORTANT: Stages 2–4 can be combined into a single execution block after Stage 1 is approved.
The critical boundary is between Stage 1 (judgment) and Stages 2–4 (mechanical).
If the user says "run it all" or doesn't want to pause, execute all four stages sequentially
but still produce the intermediate CSV files for auditability.

Output Format Guidelines

When producing file outputs in Cowork:

• For XLSX output, save to the user's workspace folder and provide a download link
• For CSV output, same approach — workspace folder with link
• For quick classifications (< 50 items), a markdown table in the conversation is fine
• Always include both the summary (pool-level and sub-pool-level) and detailed views

What This Skill Does NOT Do

• It does not reconcile GL structures across multiple source systems — that is the TBM Data Reconciliation Mapper (A0). If budget and actuals use different GL account codes, cost center structures, or levels of granularity, run A0 first to produce a unified GL file, then pass that file to this skill.
• It does not perform Layer 2 (Technology Resource Tower) mapping — that's the Resource Tower Analyzer skill
• It does not analyze budget variances — that is the IT Budget Variance Analyst skill (B2). Once cost pool classification is complete, use B2 to compare budget vs. actuals by cost pool and sub-pool.
• It does not build allocation models — that's the Chargeback/Showback Model Builder skill
• It does not generate executive reports — that's the TBM Executive Report Generator skill
• If the user asks for any of these downstream activities, complete the cost pool and sub-pool mapping first, then let them know the next step

Practitioner Notes

This skill reflects TBM Taxonomy v5.0.1 as maintained by the TBM Council. Key changes from earlier versions:

• Dual-level hierarchy: Cost pools now have standardized cost sub-pools, enabling more granular classification without proliferating top-level categories
• 9 pools (up from 8): Cloud Services is now a standalone pool; Cross Charges added; Internal Labor and External Labor merged into Staffing; Other renamed to Misc Costs; Facilities & Power renamed to Data Center Facilities; Software renamed to Software & SaaS
• Cloud Services separation: IaaS/PaaS cloud consumption has its own pool, reflecting its scale and importance in modern IT spend
• SaaS moved to Software & SaaS: SaaS subscriptions are now in the Software & SaaS pool (SaaS sub-pool), not Outside Services, reflecting that the cost nature is software regardless of delivery model
• CapEx as sub-pools: Capital expenditures are tracked as Capital sub-pools within each pool, not just as a standalone attribute
• AI/ML guidance: AI/ML infrastructure costs now have explicit classification patterns across Cloud Services, Hardware, and Software & SaaS
• FinOps alignment: The FOCUS standard terminology is referenced for cloud cost treatment; the standalone Cloud Services pool better supports FinOps integration

Execution Scaling

This skill uses a stage-gate execution architecture to handle GL datasets of any size without hitting output token limits. The classification stage (Stage 1) is the only LLM-generated code; all other stages are mechanical and templated.

For very large datasets (200+ GL items), Stage 1 can itself be batched:

• Batch 1: Items in the 6000–6999 GL range (Staffing, typically)
• Batch 2: Items in the 7000–7499 GL range (Cloud, Software, Hardware)
• Batch 3: Items in the 7500–7999 GL range (Outside Services, Misc, DC, Telecom)
• Batch 4: Items in the 8000+ GL range (D&A, Cross Charges)

Each batch appends to the same 1_classification_map.csv. The expand, Excel, and quality gate stages run once after all batches are complete.