budget-variance-analyzer

Budget Variance Analyzer Business Case Problem Statement Cost overruns surprise project teams: - Late detection of budget issues - No systematic variance analysis - Difficult to forecast final costs - Unclear root causes Solution Systematic budget variance analysis that tracks costs against budget, identifies trends, and forecasts final project costs. Business Value - Early warning - Detect overruns early - Forecasting - Predict final costs - Accountability - Track variance causes - Decision support - Informed cost decisions Technical Implementation Quick Start Common Use Cases 1. Monthly Cos…

: item.variance_amount,\n 'Variance %': round(item.variance_percent, 1),\n 'Status': item.status.value,\n '% Complete': item.percent_complete\n })\n\n pd.DataFrame(items_data).to_excel(writer, sheet_name='Line Items', index=False)\n\n # Variance records\n if self.variance_records:\n records_df = pd.DataFrame([{\n 'ID': r.record_id,\n 'Item': r.item_code,\n 'Amount': r.variance_amount,\n 'Cause': r.cause.value,\n 'Explanation': r.explanation,\n 'Date': r.recorded_date,\n 'By': r.recorded_by\n } for r in self.variance_records])\n records_df.to_excel(writer, sheet_name='Variance Records', index=False)\n\n return output_path\n```\n\n## Quick Start\n\n```python\n# Initialize analyzer\nanalyzer = BudgetVarianceAnalyzer(\n project_name=\"Office Tower\",\n original_budget=50000000,\n currency=\"USD\"\n)\n\n# Add budget items\nanalyzer.add_budget_item(\"01-SITE\", \"Site Work\", CostCategory.SUBCONTRACTOR, 2000000)\nanalyzer.add_budget_item(\"03-CONC\", \"Concrete\", CostCategory.SUBCONTRACTOR, 8000000)\nanalyzer.add_budget_item(\"05-STEEL\", \"Structural Steel\", CostCategory.SUBCONTRACTOR, 6000000)\n\n# Update with actuals\nanalyzer.update_costs(\"03-CONC\", committed=8500000, actual=4000000, percent_complete=45)\n\n# Get summary\nsummary = analyzer.calculate_summary()\nprint(f\"Variance: ${summary['variance']:,.0f} ({summary['variance_percent']}%)\")\n```\n\n## Common Use Cases\n\n### 1. Monthly Cost Review\n```python\nsummary = analyzer.calculate_summary()\ncritical = analyzer.get_critical_items()\nprint(f\"Items needing attention: {len(critical)}\")\n```\n\n### 2. Record Variance Cause\n```python\nanalyzer.record_variance(\n item_code=\"03-CONC\",\n cause=VarianceCause.PRICE_ESCALATION,\n explanation=\"Steel rebar prices increased 15%\",\n recorded_by=\"Cost Manager\"\n)\n```\n\n### 3. Forecast Scenarios\n```python\nscenarios = analyzer.forecast_completion()\nfor name, scenario in scenarios.items():\n print(f\"{scenario.name}: ${scenario.total_forecast:,.0f}\")\n```\n\n## Resources\n- **DDC Book**: Chapter 3.1 - Cost Management\n- **Reference**: PMI Cost Management\n---","attachment_filenames":["claw.json","instructions.md"],"attachments":[{"filename":"claw.json","content":"{\n \"name\": \"budget-variance-analyzer\",\n \"version\": \"2.0.0\",\n \"description\": \"Analyze budget vs actual cost variances. Identify overruns, forecast final costs, and generate variance reports.\",\n \"author\": \"datadrivenconstruction\",\n \"license\": \"MIT\",\n \"permissions\": [\n \"filesystem\"\n ],\n \"entry\": \"instructions.md\",\n \"tags\": [\n \"construction\",\n \"estimation\",\n \"cost-management\",\n \"reporting\",\n \"machine-learning\"\n ],\n \"models\": [\n \"claude-*\",\n \"gpt-*\"\n ],\n \"minOpenClawVersion\": \"0.8.0\"\n}","content_type":"application/json; charset=utf-8","language":"json","size":522,"content_sha256":"97d5ceb845c4473165f22ed5908a0ef9fd2fdad52d3e8af9fd5a80c2a289b1c5"},{"filename":"instructions.md","content":"You are a construction industry assistant specializing in construction cost estimation and management.\n\nAnalyze budget vs actual cost variances. Identify overruns, forecast final costs, and generate variance reports.\n\nWhen the user asks to create cost estimates or analyze costs:\n1. Gather the required input data from the user\n2. Process the data using the methods described in SKILL.md\n3. Present results in a clear, structured format\n4. Offer follow-up analysis or export options\n\n## Input Format\n- The user provides project data, file paths, or parameters as described in SKILL.md\n- Accept data in common formats: CSV, Excel, JSON, or direct input\n\n## Output Format\n- Present results in structured tables when applicable\n- Include summary statistics and key findings\n- Offer export to Excel/CSV/JSON when relevant\n\n## Key Reference\n- See SKILL.md for detailed implementation code, classes, and methods\n- Follow the patterns and APIs defined in the skill documentation\n\n## Constraints\n- Only use data provided by the user or referenced in the skill\n- Validate inputs before processing\n- Report errors clearly with suggested fixes\n- Follow construction industry standards and best practices\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1193,"content_sha256":"a3ac143fb8c7f3d0d6bb2a11e141830468c9e1dcc3fc47bdf87d4204bb26982b"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Budget Variance Analyzer","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Business Case","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Problem Statement","type":"text"}]},{"type":"paragraph","content":[{"text":"Cost overruns surprise project teams:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Late detection of budget issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No systematic variance analysis","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Difficult to forecast final costs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Unclear root causes","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Solution","type":"text"}]},{"type":"paragraph","content":[{"text":"Systematic budget variance analysis that tracks costs against budget, identifies trends, and forecasts final project costs.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Business Value","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Early warning","type":"text","marks":[{"type":"strong"}]},{"text":" - Detect overruns early","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Forecasting","type":"text","marks":[{"type":"strong"}]},{"text":" - Predict final costs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Accountability","type":"text","marks":[{"type":"strong"}]},{"text":" - Track variance causes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Decision support","type":"text","marks":[{"type":"strong"}]},{"text":" - Informed cost decisions","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Technical Implementation","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"python"},"content":[{"text":"import pandas as pd\nfrom datetime import datetime, date\nfrom typing import Dict, Any, List, Optional, Tuple\nfrom dataclasses import dataclass, field\nfrom enum import Enum\n\n\nclass VarianceStatus(Enum):\n \"\"\"Variance status.\"\"\"\n UNDER_BUDGET = \"under_budget\"\n ON_BUDGET = \"on_budget\"\n OVER_BUDGET = \"over_budget\"\n CRITICAL = \"critical\"\n\n\nclass CostCategory(Enum):\n \"\"\"Cost categories.\"\"\"\n LABOR = \"labor\"\n MATERIAL = \"material\"\n EQUIPMENT = \"equipment\"\n SUBCONTRACTOR = \"subcontractor\"\n OVERHEAD = \"overhead\"\n CONTINGENCY = \"contingency\"\n OTHER = \"other\"\n\n\nclass VarianceCause(Enum):\n \"\"\"Common variance causes.\"\"\"\n SCOPE_CHANGE = \"scope_change\"\n QUANTITY_CHANGE = \"quantity_change\"\n PRICE_ESCALATION = \"price_escalation\"\n PRODUCTIVITY = \"productivity\"\n REWORK = \"rework\"\n DELAY = \"delay\"\n UNFORESEEN = \"unforeseen\"\n ESTIMATE_ERROR = \"estimate_error\"\n OTHER = \"other\"\n\n\n@dataclass\nclass BudgetItem:\n \"\"\"Single budget line item.\"\"\"\n item_code: str\n description: str\n category: CostCategory\n original_budget: float\n current_budget: float # After approved changes\n committed_cost: float # Contracts, POs\n actual_cost: float # Paid/invoiced\n forecast_cost: float # Estimate at completion\n percent_complete: float\n notes: str = \"\"\n\n @property\n def variance_amount(self) -> float:\n \"\"\"Budget variance (negative = over budget).\"\"\"\n return self.current_budget - self.forecast_cost\n\n @property\n def variance_percent(self) -> float:\n \"\"\"Variance as percentage.\"\"\"\n if self.current_budget == 0:\n return 0\n return (self.variance_amount / self.current_budget) * 100\n\n @property\n def status(self) -> VarianceStatus:\n \"\"\"Determine variance status.\"\"\"\n pct = self.variance_percent\n if pct > 5:\n return VarianceStatus.UNDER_BUDGET\n elif pct >= -5:\n return VarianceStatus.ON_BUDGET\n elif pct >= -15:\n return VarianceStatus.OVER_BUDGET\n else:\n return VarianceStatus.CRITICAL\n\n\n@dataclass\nclass VarianceRecord:\n \"\"\"Record of budget variance.\"\"\"\n record_id: str\n item_code: str\n variance_amount: float\n cause: VarianceCause\n explanation: str\n recorded_date: date\n recorded_by: str\n approved: bool = False\n approval_date: Optional[date] = None\n\n\n@dataclass\nclass ForecastScenario:\n \"\"\"Cost forecast scenario.\"\"\"\n name: str\n description: str\n adjustments: Dict[str, float] # item_code: adjustment amount\n total_forecast: float\n variance_from_budget: float\n\n\nclass BudgetVarianceAnalyzer:\n \"\"\"Analyze budget vs actual cost variances.\"\"\"\n\n VARIANCE_THRESHOLD_WARNING = -0.05 # -5%\n VARIANCE_THRESHOLD_CRITICAL = -0.15 # -15%\n\n def __init__(self, project_name: str, original_budget: float, currency: str = \"USD\"):\n self.project_name = project_name\n self.original_budget = original_budget\n self.currency = currency\n self.items: Dict[str, BudgetItem] = {}\n self.variance_records: List[VarianceRecord] = []\n self.history: List[Dict[str, Any]] = []\n\n def add_budget_item(self,\n item_code: str,\n description: str,\n category: CostCategory,\n budget: float,\n committed: float = 0,\n actual: float = 0,\n percent_complete: float = 0) -> BudgetItem:\n \"\"\"Add budget line item.\"\"\"\n forecast = max(committed, actual / percent_complete * 100) if percent_complete > 0 else budget\n\n item = BudgetItem(\n item_code=item_code,\n description=description,\n category=category,\n original_budget=budget,\n current_budget=budget,\n committed_cost=committed,\n actual_cost=actual,\n forecast_cost=forecast,\n percent_complete=percent_complete\n )\n\n self.items[item_code] = item\n return item\n\n def update_costs(self, item_code: str,\n committed: float = None,\n actual: float = None,\n percent_complete: float = None,\n forecast: float = None):\n \"\"\"Update item costs.\"\"\"\n if item_code not in self.items:\n raise ValueError(f\"Item {item_code} not found\")\n\n item = self.items[item_code]\n\n if committed is not None:\n item.committed_cost = committed\n if actual is not None:\n item.actual_cost = actual\n if percent_complete is not None:\n item.percent_complete = percent_complete\n if forecast is not None:\n item.forecast_cost = forecast\n else:\n # Auto-calculate forecast\n if item.percent_complete > 0:\n item.forecast_cost = item.actual_cost / item.percent_complete * 100\n else:\n item.forecast_cost = max(item.committed_cost, item.current_budget)\n\n self._record_history()\n\n def adjust_budget(self, item_code: str, amount: float, reason: str):\n \"\"\"Adjust current budget (approved change).\"\"\"\n if item_code not in self.items:\n raise ValueError(f\"Item {item_code} not found\")\n\n self.items[item_code].current_budget += amount\n self.items[item_code].notes += f\"\\nBudget adjusted by {amount}: {reason}\"\n\n def record_variance(self,\n item_code: str,\n cause: VarianceCause,\n explanation: str,\n recorded_by: str) -> VarianceRecord:\n \"\"\"Record variance explanation.\"\"\"\n item = self.items.get(item_code)\n if not item:\n raise ValueError(f\"Item {item_code} not found\")\n\n record_id = f\"VAR-{len(self.variance_records) + 1:04d}\"\n\n record = VarianceRecord(\n record_id=record_id,\n item_code=item_code,\n variance_amount=item.variance_amount,\n cause=cause,\n explanation=explanation,\n recorded_date=date.today(),\n recorded_by=recorded_by\n )\n\n self.variance_records.append(record)\n return record\n\n def _record_history(self):\n \"\"\"Record current state to history.\"\"\"\n snapshot = {\n 'date': date.today().isoformat(),\n 'total_budget': sum(i.current_budget for i in self.items.values()),\n 'total_committed': sum(i.committed_cost for i in self.items.values()),\n 'total_actual': sum(i.actual_cost for i in self.items.values()),\n 'total_forecast': sum(i.forecast_cost for i in self.items.values())\n }\n self.history.append(snapshot)\n\n def calculate_summary(self) -> Dict[str, Any]:\n \"\"\"Calculate overall budget summary.\"\"\"\n total_budget = sum(i.current_budget for i in self.items.values())\n total_committed = sum(i.committed_cost for i in self.items.values())\n total_actual = sum(i.actual_cost for i in self.items.values())\n total_forecast = sum(i.forecast_cost for i in self.items.values())\n\n variance = total_budget - total_forecast\n variance_pct = (variance / total_budget * 100) if total_budget > 0 else 0\n\n # By category\n by_category = {}\n for item in self.items.values():\n cat = item.category.value\n if cat not in by_category:\n by_category[cat] = {\n 'budget': 0, 'actual': 0, 'forecast': 0, 'variance': 0\n }\n by_category[cat]['budget'] += item.current_budget\n by_category[cat]['actual'] += item.actual_cost\n by_category[cat]['forecast'] += item.forecast_cost\n by_category[cat]['variance'] += item.variance_amount\n\n # Items needing attention\n critical = [i for i in self.items.values() if i.status == VarianceStatus.CRITICAL]\n over_budget = [i for i in self.items.values() if i.status == VarianceStatus.OVER_BUDGET]\n\n return {\n 'project': self.project_name,\n 'currency': self.currency,\n 'original_budget': self.original_budget,\n 'current_budget': total_budget,\n 'committed': total_committed,\n 'actual': total_actual,\n 'forecast': total_forecast,\n 'variance': variance,\n 'variance_percent': round(variance_pct, 1),\n 'status': 'ON_TRACK' if variance >= 0 else 'OVER_BUDGET',\n 'by_category': by_category,\n 'critical_items': len(critical),\n 'over_budget_items': len(over_budget),\n 'contingency_used': total_budget - self.original_budget\n }\n\n def get_critical_items(self) -> List[BudgetItem]:\n \"\"\"Get items with critical variances.\"\"\"\n return [i for i in self.items.values()\n if i.status in [VarianceStatus.CRITICAL, VarianceStatus.OVER_BUDGET]]\n\n def forecast_completion(self,\n optimistic_factor: float = 0.95,\n pessimistic_factor: float = 1.15) -> Dict[str, ForecastScenario]:\n \"\"\"Generate forecast scenarios.\"\"\"\n current_forecast = sum(i.forecast_cost for i in self.items.values())\n current_budget = sum(i.current_budget for i in self.items.values())\n\n scenarios = {\n 'optimistic': ForecastScenario(\n name=\"Optimistic\",\n description=\"Best case with no further overruns\",\n adjustments={},\n total_forecast=current_forecast * optimistic_factor,\n variance_from_budget=current_budget - (current_forecast * optimistic_factor)\n ),\n 'most_likely': ForecastScenario(\n name=\"Most Likely\",\n description=\"Current trend continues\",\n adjustments={},\n total_forecast=current_forecast,\n variance_from_budget=current_budget - current_forecast\n ),\n 'pessimistic': ForecastScenario(\n name=\"Pessimistic\",\n description=\"Additional overruns expected\",\n adjustments={},\n total_forecast=current_forecast * pessimistic_factor,\n variance_from_budget=current_budget - (current_forecast * pessimistic_factor)\n )\n }\n\n return scenarios\n\n def analyze_trends(self) -> Dict[str, Any]:\n \"\"\"Analyze cost trends from history.\"\"\"\n if len(self.history) \u003c 2:\n return {'trend': 'insufficient_data'}\n\n forecasts = [h['total_forecast'] for h in self.history]\n actuals = [h['total_actual'] for h in self.history]\n\n # Calculate trend direction\n forecast_trend = forecasts[-1] - forecasts[0]\n actual_trend = actuals[-1] - actuals[0]\n\n return {\n 'forecast_trend': 'increasing' if forecast_trend > 0 else 'decreasing',\n 'forecast_change': forecast_trend,\n 'actual_trend': 'increasing' if actual_trend > 0 else 'stable',\n 'actual_change': actual_trend,\n 'data_points': len(self.history)\n }\n\n def export_variance_report(self, output_path: str):\n \"\"\"Export detailed variance report to Excel.\"\"\"\n with pd.ExcelWriter(output_path, engine='openpyxl') as writer:\n # Summary\n summary = self.calculate_summary()\n summary_df = pd.DataFrame([\n {'Metric': k, 'Value': v}\n for k, v in summary.items()\n if not isinstance(v, dict)\n ])\n summary_df.to_excel(writer, sheet_name='Summary', index=False)\n\n # Line items\n items_data = []\n for item in self.items.values():\n items_data.append({\n 'Code': item.item_code,\n 'Description': item.description,\n 'Category': item.category.value,\n 'Budget': item.current_budget,\n 'Committed': item.committed_cost,\n 'Actual': item.actual_cost,\n 'Forecast': item.forecast_cost,\n 'Variance

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.