neqsim-jv-cost-control-screening

JV Cost Control Screening

Public, screening-level controls for the finance-and-control work of a non-operating partner. The operator sends four kinds of material: monthly Joint Interest Billing (JIB, PDF and Excel), an annual budget issued twice a year, a monthly operations report and a quarterly cost-recovery report. This skill turns the repetitive checks on that material into tested functions so the controller spends time on explanations instead of on retyping and re-adding numbers.

It does not account, approve or dispute costs. Every output is a question for the operator or a number to review; a qualified controller decides.

When to Use

• A JIB or cost-recovery statement must be loaded into a table and proven to be complete.
• Actual cost must be compared with budget or forecast, with material variances ranked.
• Two reports that should agree (JIB vs operations report vs cost-recovery report) must be reconciled.
• A participating-interest share must be tested against gross amounts.
• A cost overrun must be split into a volume effect and a unit-rate effect.

Inputs

• Rows of a statement that uses label columns plus numeric columns (for example from openpyxl).
• Actual and reference (budget/forecast/plan) tables with matching keys, in one currency and unit.
• Participating interest(s) as fractions, for example [0.12, 0.12 / 0.9].
• Line codes and values of a statement that carries arithmetic identities.

Outputs

• ParsedStatement: tidy detail lines and totals with the sum of the lines they close.
• check_subtotals: totals that do not equal their detail lines, largest first.
• variance_table and variance_commentary: material variances and fact-only sentences with a TO BE CONFIRMED WITH OPERATOR cause placeholder.
• price_volume_split, run_rate_outlook, outlier_months.
• reconcile_tables, rollforward_check, check_identities, interest_share_check.

Engineering Method

1. Parse and prove. Statements write a hierarchy label only when it changes and close each group with TOTAL <label>. parse_hierarchical_rows forward-fills the labels, keeps TOTAL rows separately and records for each TOTAL the sum of the detail lines it closes. A TOTAL with no detail since the previous total at its level is a grand total and is checked against the sibling totals. Net-zero detail groups are not mistaken for grand totals.
2. Compare with a reference. variance_table flags a line when the absolute variance and the relative variance both exceed thresholds; spend against a zero reference is always material.
3. Explain with numbers only. variance_commentary states actual, reference, variance and percentage. The cause is left as a placeholder so that nothing is invented.
4. Split the variance. price_volume_split uses volume effect = (V_act - V_ref) x unit_ref and rate effect = (unit_act - unit_ref) x V_act; the two add to the total exactly.
5. Roll forward. YTD(t) = YTD(t-1) + month(t). When the cost-recovery report ends before the previous JIB month, the implied cost of the months in between is compared with the report's monthly run-rate.
6. Identities. check_identities evaluates only + - * /, numbers and line codes (no eval), with a rounding tolerance.
7. Share check. interest_share_check tests share = gross x PI for any of several PIs. Use it on current-month and year-to-date; inception-to-date mixes periods with different PIs.