Quantify the narrative of "interest eating up tax revenue" in Japan using public data, providing verifiable current-status checks, sensitivity analysis, and risk grading.
<essential_principles>
interest_tax_ratio = interest_payments / tax_revenue
This is a verifiable version of the video narrative "interest eats up 1/3 of tax revenue." Different bases (national tax vs general account tax revenue vs total revenue) produce different figures, and the choice of basis must be explicitly stated.
Basis Comparison (FY2025)：
| Basis | Calculation | Ratio |
|---|---|---|
| Interest only/Tax revenue | 10.5 trillion/70 trillion | 15.0% |
| National debt service/Tax revenue | 28.2 trillion/70 trillion | 40.3% |
Note: The media narrative "interest eats up 1/3" typically misuses the national debt service (including principal) basis.
implied_avg_rate = interest_payments / debt_stock
Measures the average financing cost of the stock of debt. Comparing it with current market rates allows assessment of refinancing pressure.
FY2025: 10.5 trillion / 1,324 trillion = 0.79% vs current 10Y yield 2.0%+ → The gap reflects that a large amount of the outstanding debt was issued during periods of low interest rates, and future refinancing will push up the interest burden.
The media often expresses Japan's debt using a "US-equivalent scale" to enhance the shock effect.
Formula(dynamic calculation):
debt_to_gdp = japan_debt_stock / japan_gdp
debt_in_us_terms = us_gdp × debt_to_gdp
Data source: GDP is fetched in real time from FRED, not hard-coded.
Example：$30.6T × 250% = $76.5T ≈ $70T (media colloquialism)
Purpose: To explain the source of the "$70T" figure in videos/news, used to unify the perception of scale in cross-country comparisons.
Map yield changes to increases in interest expenditure:
additional_interest ≈ debt_stock × pass_through × delta_yield
Where pass_through is the annual repricing/refinancing ratio (about 15%),delta_yield expressed as a decimal (200bp = 0.02).
| Range | interest_tax_ratio | Meaning |
|---|---|---|
| 🟢 Green | < 0.25 | Ample fiscal flexibility |
| 🟡 Yellow | 0.25–0.40 | Fiscal flexibility begins to decline |
| 🟠 Orange | 0.40–0.55 | Policy space clearly constrained |
| 🔴 Red | > 0.55 | Approaching the "2/3" narrative zone |
All outputs must indicate:
- Tax revenue basis (national_tax / general_account_tax / total_revenue)
- Interest basis (interest_only / debt_service)
- Data year and lag
- Repricing assumption (pass_through)
</essential_principles>
<quick_start>
Fastest way: run a quick check
cd skills/analyze-japan-debt-service-tax-burden
pip install pandas numpy requests matplotlib # 首次使用
python scripts/japan_debt_analyzer.py --quick
Output example:
{
"yield_stats": {"tenor": "10Y", "latest": 1.23, "percentile": 0.97},
"fiscal": {"interest_tax_ratio": 0.15, "risk_band": "green"},
"headline": "利息支出佔稅收 15.0%，處於🟢 GREEN 區",
"data_sources": {"jgb_10y": "FRED/IRLTLT01JPM156N", "fiscal": "config/FY2025"}
}
Full analysis (including real-time data refresh)：
python scripts/japan_debt_analyzer.py --full --refresh
Generate visualization Dashboard：
python scripts/generate_charts.py --full --output-dir ../../output
Output:output/japan_debt_dashboard_YYYYMMDD.png
Dashboard includes:
- Interest/Tax Ratio risk gauge
- Yield percentile indicator
- Fiscal data summary
- Stress test scenario comparison chart
Generate debt spiral simulation chart：
# 完整多情境螺旋模擬
python scripts/generate_spiral_chart.py --all --output-dir ../../output
# 單一壓力情境（如 +200bp）
python scripts/generate_spiral_chart.py --stress 200 --output-dir ../../output
# 自定義模擬年數
python scripts/generate_spiral_chart.py --years 15 --output-dir ../../output
Output:output/japan_debt_spiral_YYYY-MM-DD.png
Spiral simulation includes:
- Multi-scenario Interest/Tax Ratio 10-year evolution curves
- Risk zone background (green/yellow/orange/red)
- Interest expenditure decomposition stacked chart
- Final risk assessment for each scenario
Generate historical trend analysis chart（NEW!）：
# 完整歷史趨勢分析（2015-2025）
python scripts/generate_historical_trend.py --output-dir ../../output
# 自定義時間範圍
python scripts/generate_historical_trend.py --start-year 2018 --end-year 2025
Output:output/japan_debt_trend_YYYYMMDD.png
Historical trend analysis includes:
- Complete 11-year trajectory of the Interest/Tax Ratio (2015-2025)
- Trends in tax revenue, interest expenses, and debt stock
- Evolution of the implied average interest rate
- Risk classification distribution statistics
- Phased characteristic analysis (decline period/pandemic period/rebound period)
Test data fetching separately：
python scripts/fetch_jgb_yields.py --tenor 10Y
python scripts/fetch_tic_holdings.py
</quick_start>
- Quick check - View the latest interest/tax ratio and yield status
- Full analysis - Execute the complete fiscal stress test and risk assessment
- Scenario stress test - Conduct stress tests with custom interest rate shock scenarios
- Generate charts - Generate a visual Dashboard (PNG image)
- Debt spiral simulation - Simulate multi-year cumulative effects and generate spiral evolution charts
- Historical trend analysis - Analyze the complete historical trend from 2015-2025 (NEW!)
- Methodology learning - Understand the metric calculation and risk classification logic
Please select or directly provide analysis parameters.
After routing, read the corresponding workflow and follow its steps completely.
<input_schema>
Each scenario includes:
name(string): Scenario namedelta_yield_bp(int): Yield increase in bppass_through_year1(float): First-year repricing ratio (default 0.15)pass_through_year2(float): Second-year repricing ratio (default 0.15)tax_shock(float): Tax revenue shock (e.g., -0.05 means a 5% decline)
</input_schema>
<output_schema>
See templates/output-json.md for the complete structure definition.
Summary：
{
"skill": "analyze_japan_debt_service_tax_burden",
"as_of": "2026-01-20",
"yield_stats": {
"tenor": "10Y",
"latest": 1.23,
"zscore": 2.10,
"percentile": 0.97,
"interpretation": "近兩年分位數 97%，屬於偏極端區"
},
"fiscal": {
"tax_revenue_jpy": 72000000000000,
"interest_payments_jpy": 24000000000000,
"debt_stock_jpy": 1200000000000000,
"interest_tax_ratio": 0.333,
"risk_band": "yellow",
"definition": {...}
},
"stress_tests": [...],
"spillover_channel": {...},
"headline_takeaways": [...]
}
</output_schema>
<reference_index>
Reference documents (references/)
| Document | Content |
|---|---|
| data-sources.md | Data sources and API endpoints (MOF, BOJ, FRED, TIC) |
| methodology.md | Calculation methodology and risk classification logic |
| japan-fiscal-structure.md | Japan's fiscal structure and debt characteristics |
| </reference_index> |
<workflows_index>
| Workflow | Purpose |
|---|---|
| quick-check.md | Quick status check (completed within 1 minute) |
| full-analysis.md | Complete analysis workflow (including all steps) |
| stress-test.md | Custom scenario stress testing |
| generate-chart.md | Generate a visual Dashboard |
| spiral-simulate.md | Multi-year debt spiral simulation |
| historical-trend.md | Historical trend analysis (2015-2025) (NEW!) |
| </workflows_index> |
<templates_index>
| Template | Purpose |
|---|---|
| output-json.md | JSON output structure definition |
| output-markdown.md | Markdown report template |
| </templates_index> |
<scripts_index>
| Script | Command | Purpose |
|---|---|---|
| japan_debt_analyzer.py | --quick |
Quick check |
| japan_debt_analyzer.py | --full |
Full analysis |
| japan_debt_analyzer.py | --stress BP |
Stress test |
| japan_debt_analyzer.py | --refresh |
Force refresh data |
| generate_charts.py | --full --output-dir DIR |
Generate a visual Dashboard |
| generate_charts.py | --quick |
Quick mode charts |
| generate_charts.py | --data-file FILE |
Load data from JSON |
| generate_spiral_chart.py | --all --output-dir DIR |
Complete debt spiral simulation Dashboard |
| generate_spiral_chart.py | --stress BP |
Single stress scenario spiral chart |
| generate_spiral_chart.py | --years N |
Custom simulation years (default 10) |
| generate_historical_trend.py | --output-dir DIR |
Historical trend analysis (2015-2025) (NEW!) |
| generate_historical_trend.py | --start-year Y --end-year Y |
Custom time range analysis |
| fetch_jgb_yields.py | --tenor 10Y |
Fetch JGB yields (FRED) |
| fetch_tic_holdings.py | --refresh |
Fetch TIC U.S. Treasury holdings data |
| data_manager.py | --fetch-all |
Coordinate fetching from all data sources |
| </scripts_index> |
<success_criteria> When the Skill executes successfully:
- Output the current interest/tax ratio and risk classification
- Determine whether yields are extreme based on percentiles/Z-scores
- Stress test results include sensitivity analysis
- Clearly indicate data scope and lag
- If enabled, output spillover channel assessment
- Actionable headline takeaways </success_criteria>
<directory_structure>
analyze-japan-debt-service-tax-burden/
├── SKILL.md # 本文件（路由器）
├── skill.yaml # 前端展示元數據
├── manifest.json # 技能元資料
├── workflows/
│ ├── quick-check.md # 快速檢查工作流
│ ├── full-analysis.md # 完整分析工作流
│ ├── stress-test.md # 壓力測試工作流
│ ├── generate-chart.md # 圖表生成工作流
│ ├── spiral-simulate.md # 債務螺旋模擬工作流
│ └── historical-trend.md # 歷史趨勢分析工作流（NEW!）
├── references/
│ ├── data-sources.md # 資料來源說明
│ ├── methodology.md # 方法論與公式
│ └── japan-fiscal-structure.md # 日本財政結構
├── templates/
│ ├── output-json.md # JSON 輸出模板
│ └── output-markdown.md # Markdown 報告模板
├── config/
│ └── fiscal_data.json # 財政數據配置（含 2015-2025 完整數據）
├── scripts/
│ ├── japan_debt_analyzer.py # 主分析腳本
│ ├── generate_charts.py # 視覺化圖表生成
│ ├── generate_spiral_chart.py # 債務螺旋模擬圖表
│ ├── generate_historical_trend.py # 歷史趨勢分析圖表（NEW!）
│ ├── fetch_jgb_yields.py # JGB 殖利率抓取 (FRED)
│ ├── fetch_tic_holdings.py # TIC 美債持有抓取
│ └── data_manager.py # 數據協調與緩存管理
├── data/
│ └── cache/ # 自動緩存目錄（gitignore）
└── examples/
└── sample-output.json # 範例輸出
</directory_structure>