{"skill":{"slug":"financial-report-automator","displayName":"Financial Report Automator","summary":"Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly ea...","description":"---\nname: financial-report-automator\ndescription: Automated quarterly financial report generation with dividend-adjusted total return calculations. Use when generating stock performance reports, quarterly earnings summaries, or return analytics for any ticker with CSV price data.\nversion: 1.2.1\ntags: ['finance', 'reporting', 'quarterly', 'returns', 'dividends']\n---\n\n# Financial Report Automator\n\nGenerates quarterly stock performance reports with **dividend-adjusted total return**.\n\n## What It Does\n\n- Parses CSV price data (Yahoo Finance export format)\n- Computes **price return** (raw close) and **total return** (adjusted close with dividends)\n- Produces structured quarterly reports: start/end price, returns, high/low, avg volume, dividends paid\n\n## Key Fix (v1.0.1)\n\nPrevious versions used raw close for return calculations, which **understated returns for dividend-paying stocks** like AAPL. v1.0.1 introduces:\n\n1. **Column name normalization** — handles mixed-case CSV headers (`Date` → `date`)\n2. **Adjusted close computation** — backward-adjusts prices for dividends so total return reflects reinvested dividends\n3. **Separate price_return vs total_return** — both are reported for transparency\n4. **Dividend tracking** — `dividend` column is optional; defaults to 0 if absent\n\n## Usage\n\n### As a Python module\n\n```python\nfrom scripts.stock_analyzer import StockAnalyzer\n\nanalyzer = StockAnalyzer(data_path=\"finance/AAPL.csv\")\n\n# 30-day total return (dividend-adjusted)\nprint(analyzer.calculate_returns(30))\n\n# 30-day price return only (no dividends)\nprint(analyzer.calculate_returns(30, use_adj=False))\n\n# Full quarterly report\nreport = analyzer.generate_quarterly_report(quarter=2, year=2026)\nprint(report)\n```\n\n### CLI\n\n```bash\npython3 scripts/stock_analyzer.py\n```\n\n## CSV Format Expected\n\n```\nDate,Close,Volume,Open,High,Low\n01/02/2026,$269.77,21755774,$272.05,$277.82,$269.11\n```\n\nOptional columns:\n- `dividend` — per-share dividend on ex-div date\n- `adj_close` — pre-computed adjusted close (overrides internal calculation)\n\n## Report Output\n\n```json\n{\n  \"quarter\": \"Q2 2026\",\n  \"start_date\": \"2026-04-01\",\n  \"end_date\": \"2026-06-30\",\n  \"start_price\": 223.0,\n  \"end_price\": 235.5,\n  \"price_return_pct\": 5.61,\n  \"total_return_pct\": 6.12,\n  \"dividends_per_share\": 0.25,\n  \"highest_price\": 240.0,\n  \"lowest_price\": 218.5,\n  \"average_volume\": 35000000\n}\n```\n\n## Requirements\n\n- Python 3.10+\n- pandas\n","tags":{"latest":"1.2.1"},"stats":{"comments":0,"downloads":570,"installsAllTime":22,"installsCurrent":2,"stars":0,"versions":6},"createdAt":1778103100443,"updatedAt":1778548307903},"latestVersion":{"version":"1.2.1","createdAt":1778544779267,"changelog":"Fix sort order bug: ensure data is always sorted newest-first; handle both 'dividend' and 'dividends' column names from yfinance exports","license":"MIT-0"},"metadata":null,"owner":{"handle":"terrycarter1985","userId":"s17brwfrqyjhbjgadkvar20h8x8492g8","displayName":"terrycarter1985","image":"https://avatars.githubusercontent.com/u/1542987?v=4"},"moderation":null}