Add literature context to OptimumDebt

.gitignore

@@ -67,6 +67,9 @@ instance/
 # Sphinx documentation
 docs/_build/
 
+# MyST Markdown build output
+_build/
+
 # PyBuilder
 target/
 
@@ -110,5 +113,18 @@ env-*/
 # mypy
 .mypy_cache/
 
+# Dotfiles
+dotfiles/to
+
+# Project-specific (local only)
+researcher-requirements.md
+proposed-revisions.md
+scripts/create_paperpile_bib.py
+scripts/ipynb_to_myst.py
+
 # Mac
 .DS_Store
+
+# Cursor / SpecStory
+.cursor*
+.specstory*/

literature-gaps.md

@@ -0,0 +1,163 @@
+# Remaining Gaps in the Literature
+
+Based on the analysis of papers citing Aiyagari & McGrattan (1998), several important gaps remain:
+
+## 1. **Empirical Validation and Calibration Updates**
+
+**Gap**: Limited empirical work validating the model's predictions or updating calibrations with recent data.
+
+**What's missing**:
+- Empirical tests of whether actual debt levels align with model-implied optimal levels across countries
+- Updated calibrations using post-2008 financial crisis data (most work uses pre-crisis parameters)
+- Cross-country comparative studies testing the model's predictions
+- Validation of the "small welfare gains" finding with real-world data
+
+**Why it matters**: The original paper's finding that welfare gains are small needs empirical validation, especially given rising debt levels globally.
+
+## 2. **Dynamic Optimal Debt Paths (Not Just Steady States)**
+
+**Gap**: Most papers focus on steady-state optimal debt levels, not optimal transition paths.
+
+**What's missing**:
+- How should debt evolve optimally over time, especially after shocks?
+- Optimal debt dynamics during recessions vs. expansions
+- Analysis of optimal debt reduction paths (if starting from high levels)
+- Time-varying optimal debt-to-GDP ratios
+
+**Why it matters**: Policy makers need guidance on how to adjust debt over time, not just what the long-run level should be.
+
+## 3. **Heterogeneity Beyond Income/Wealth**
+
+**Gap**: Models typically focus on income/wealth heterogeneity but ignore other important dimensions.
+
+**What's missing**:
+- Age heterogeneity (life-cycle considerations) combined with liquidity constraints
+- Skill/education heterogeneity and its interaction with debt policy
+- Geographic heterogeneity (urban vs. rural, regional differences)
+- Health and disability status affecting liquidity needs
+- Family structure heterogeneity (single vs. married, children)
+
+**Why it matters**: Different types of heterogeneity may have different implications for optimal debt policy.
+
+## 4. **Financial Sector and Banking Frictions**
+
+**Gap**: Limited integration of banking sector and financial intermediation frictions.
+
+**What's missing**:
+- How does optimal debt policy change when banks face capital constraints?
+- Interaction between government debt and private credit markets
+- Role of financial crises and their impact on optimal debt
+- How does government debt affect bank lending and financial stability?
+
+**Why it matters**: The 2008 crisis showed financial sector frictions matter enormously, but most models abstract from them.
+
+## 5. **Uncertainty and Robustness**
+
+**Gap**: Limited analysis of robustness to model uncertainty and parameter uncertainty.
+
+**What's missing**:
+- Robust optimal policies under model uncertainty
+- Sensitivity analysis of optimal debt to key parameters
+- Analysis of optimal debt under different assumptions about risk preferences
+- How optimal debt changes with different income process specifications
+
+**Why it matters**: Policy recommendations need to be robust given uncertainty about model parameters and structure.
+
+## 6. **Distributional Consequences in Detail**
+
+**Gap**: While some papers examine distributional effects, detailed welfare analysis by household type is limited.
+
+**What's missing**:
+- Which specific household types benefit/lose from different debt levels?
+- Welfare decomposition: liquidity benefits vs. tax costs by household characteristics
+- Optimal debt when policy makers have distributional preferences (e.g., Rawlsian)
+- Trade-offs between aggregate efficiency and distributional equity
+
+**Why it matters**: Understanding who gains and loses is crucial for political feasibility and social welfare.
+
+## 7. **State-Dependent Optimal Policies**
+
+**Gap**: Most analysis assumes constant optimal debt levels, ignoring state-dependency.
+
+**What's missing**:
+- How should optimal debt vary with aggregate productivity?
+- Optimal debt policy during financial crises vs. normal times
+- State-contingent debt policies (debt levels that depend on economic conditions)
+- Optimal automatic stabilizers in heterogeneous-agent models
+
+**Why it matters**: Optimal policy likely depends on economic conditions, but this is underexplored.
+
+## 8. **Multiple Asset Types and Portfolio Choice**
+
+**Gap**: Models typically have simple asset structures (money, bonds, capital) but ignore richer portfolios.
+
+**What's missing**:
+- Optimal debt when households hold diverse portfolios (stocks, housing, etc.)
+- Interaction between government debt and housing markets
+- How does optimal debt change when households can invest in multiple risky assets?
+- Role of government debt as a safe asset in portfolios
+
+**Why it matters**: Real households hold diverse portfolios, which may affect optimal debt policy.
+
+## 9. **Open Economy Extensions**
+
+**Gap**: While Gounopoulos et al. (2025) examines spillovers, full open-economy analysis is limited.
+
+**What's missing**:
+- Optimal debt in small open economies vs. large economies
+- How does optimal debt change with capital mobility?
+- Currency denomination of debt and exchange rate considerations
+- Optimal coordination of debt policies across countries
+
+**Why it matters**: Most economies are open, and optimal policy may differ substantially in open vs. closed settings.
+
+## 10. **Non-Linear and Regime-Dependent Effects**
+
+**Gap**: Limited analysis of non-linearities and threshold effects.
+
+**What's missing**:
+- Are there debt thresholds beyond which effects change dramatically?
+- Non-linear effects of debt on interest rates and growth
+- Regime-switching models where optimal debt depends on which regime the economy is in
+- Analysis of debt sustainability limits and their implications
+
+**Why it matters**: Real-world effects may be highly non-linear, but most models assume smooth relationships.
+
+## 11. **Political Economy and Implementation**
+
+**Gap**: While Carroll et al. (2021) introduces political economy, this area is still underdeveloped.
+
+**What's missing**:
+- How do political institutions affect optimal debt?
+- Analysis of time-consistency problems in debt policy
+- How do electoral cycles affect optimal debt?
+- Political constraints on achieving optimal debt levels
+
+**Why it matters**: Even if we know optimal debt, political constraints may prevent achieving it.
+
+## 12. **Climate and Long-Run Risks**
+
+**Gap**: No integration of climate change or other long-run risks.
+
+**What's missing**:
+- How should optimal debt account for climate-related risks?
+- Optimal debt when facing uncertain long-run productivity (climate damage)
+- Intergenerational equity considerations with climate change
+- Role of government debt in financing climate adaptation/mitigation
+
+**Why it matters**: Climate change represents a major long-run risk that may affect optimal debt policy.
+
+## Priority Gaps for Future Research
+
+**Most urgent**:
+1. **Dynamic optimal paths** (not just steady states) - Policy makers need transition guidance
+2. **Empirical validation** - Need to test model predictions with real data
+3. **Financial sector integration** - Banking frictions are crucial but underexplored
+4. **State-dependent policies** - Optimal debt likely varies with economic conditions
+
+**High potential impact**:
+5. **Distributional analysis in detail** - Understanding winners/losers is crucial
+6. **Open economy extensions** - Most economies are open
+7. **Robustness analysis** - Policy needs to work under uncertainty
+
+These gaps represent opportunities for future research that would significantly advance our understanding of optimal government debt policy in heterogeneous-agent economies.

models/We-Would-Like-In-Econ-ARK/OptimumDebt/.gitignore

@@ -0,0 +1 @@
+_build/