Improve AI Analysis Prompts, Methodology Guides & Templates (analysis/ + workflow .md)

[pethers]

📋 Issue Type

Feature / Quality Improvement

🎯 Objective

Improve the AI-driven analysis pipeline by enhancing workflow prompts, methodology guides, and analysis output templates to produce higher-quality political intelligence with better evidence-based reasoning, richer Mermaid diagrams, and more actionable insights.

📊 Current State

• AI Analysis Guide: v4.2 (103KB) — comprehensive but verbose, agents may not efficiently consume all instructions
• Analysis Templates: v4.1 — 8 template files covering synthesis, risk, SWOT, threat, classification, stakeholder, significance
• Workflow Prompts: 5 core news workflow .md files averaging ~950 lines each (propositions: 948, motions: 933, committee-reports: 958, interpellations: 977, evening-analysis: 1369)
• Analysis Output: Daily folders (e.g., analysis/daily/2026-04-09/) produce 7-9 structured analysis files per article type
• Quality: Synthesis summaries are good (e.g., motions 2026-04-09 properly identifies 3-party opposition front) but inconsistent depth across different article types
• Confidence Levels: Often stuck at MEDIUM — analysis could provide more granular confidence scoring

🚀 Desired State

1. Streamlined prompts: Reduce workflow .md prompt verbosity by 20% while improving AI output quality — focus instructions on what matters most
2. Enhanced methodology guides: Update ai-driven-analysis-guide.md with lessons learned from 2+ months of production analysis (v4.2→v5.0)
3. Better template outputs: Improve analysis/templates/ files with richer structured sections for:
   • Historical context comparison (link current events to past voting patterns)
   • Coalition dynamics scoring (quantified government stability metrics)
   • Election 2026 implications section (every analysis should connect to upcoming election)
4. Improved per-file analysis: Enhance per-file-political-intelligence.md to produce more differentiated per-document insights
5. Better confidence calibration: Replace binary MEDIUM/HIGH with nuanced 5-level confidence scale with explicit evidence thresholds

🔧 Implementation Approach

Files to modify (NO overlap with other issues):

• analysis/methodologies/ai-driven-analysis-guide.md — v4.2→v5.0 upgrade
• analysis/methodologies/political-classification-guide.md — enhanced classification criteria
• analysis/methodologies/political-risk-methodology.md — improved risk scoring
• analysis/methodologies/political-style-guide.md — editorial consistency
• analysis/methodologies/political-swot-framework.md — richer SWOT templates
• analysis/methodologies/political-threat-framework.md — updated threat taxonomy
• analysis/methodologies/README.md — updated documentation map
• analysis/templates/*.md — all 8 template files (synthesis, risk, SWOT, etc.)
• analysis/templates/README.md — updated template documentation
• .github/workflows/news-propositions.md — optimized prompt
• .github/workflows/news-motions.md — optimized prompt
• .github/workflows/news-committee-reports.md — optimized prompt
• .github/workflows/news-interpellations.md — optimized prompt
• .github/workflows/news-evening-analysis.md — optimized prompt
• .github/workflows/news-week-ahead.md — optimized prompt
• .github/workflows/news-month-ahead.md — optimized prompt
• .github/workflows/news-realtime-monitor.md — optimized prompt
• .github/workflows/news-weekly-review.md — optimized prompt
• .github/workflows/news-monthly-review.md — optimized prompt

Key improvements:

1. Add "Election 2026 Lens" section to all analysis templates — every analysis should connect findings to upcoming election implications
2. Add historical comparison tables to synthesis template — "How does this compare to similar events in 2022-2025?"
3. Improve Mermaid diagram instructions in prompts — mandate specific diagram types per analysis (flowcharts for legislative process, timeline for policy evolution)
4. Add 5-level confidence scale definitions: VERY LOW (speculation), LOW (circumstantial), MEDIUM (multiple sources), HIGH (official records), VERY HIGH (verified data + corroboration)
5. Streamline workflow prompts: move shared instructions to methodology files (lazy-loaded), keep prompts focused on article-type-specific guidance
6. After modifying .md workflow files, recompile corresponding .lock.yml with gh aw compile

🤖 Recommended Agent

news-journalist — Best expertise in editorial standards, analysis quality, and political intelligence methodology

✅ Acceptance Criteria

• All methodology guides updated to v5.0 with improved instructions
• All analysis templates include Election 2026 implications section
• 5-level confidence scale documented and integrated into all templates
• Workflow prompts reduced in size by ≥15% while maintaining/improving output quality
• All modified workflow .md files recompiled to .lock.yml
• All existing tests pass (npx vitest run)
• README documentation updated in analysis/

📚 References

• Analysis Guide: analysis/methodologies/ai-driven-analysis-guide.md
• Templates: analysis/templates/
• Workflow Prompts: .github/workflows/news-*.md
• ISMS: Hack23 ISMS-PUBLIC
• Architecture: ARCHITECTURE.md

🏷️ Labels

analysis-data, agentic-news, documentation