You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
All methodology documents published under project license for transparency
🎯 Purpose
This directory contains the political-intelligence methodology library that governs how EU Parliament Monitor's agentic workflows produce, classify, assess, and publish European Parliament analysis. It splits into two layers: six core analytical frameworks (Classification, Risk, Threat, SWOT, Style, AI-Driven Guide) and a set of horizon-conditional / cross-cutting methodologies (OSINT Tradecraft, Confidence Calibration, Source Triangulation, Synthesis, Strategic Extensions, Per-Document, Structural Metadata, Electoral Domain + Cycle, Analytical Supplementary, IMF + World Bank Indicator Mappings, Forward-Projection, Voter Segmentation). Together they transform raw European Parliament MCP data into structured, evidence-based political intelligence. The operational entry point for every run is ai-driven-analysis-guide.md §"🚀 Quick-Start Cheat-Sheet".
Core Principle: Every analytical claim requires verifiable evidence sourced from European Parliament open data. Opinion-based analysis, boilerplate summaries, and the unmodified use of software-centric threat models (such as STRIDE, DREAD, or PASTA) are explicitly rejected for political analysis. Political threat analysis uses purpose-built frameworks (Political Threat Landscape, Attack Trees, Kill Chain, Diamond Model, ICO Profiling) designed specifically for democratic process analysis. STRIDE remains in use in THREAT_MODEL.md for software security of the platform itself.
Design Philosophy: The six core frameworks form a layered analytical pipeline — classification provides the foundation, risk and threat assessments build the analytical core, SWOT synthesizes strategic implications, style standards enforce writing quality, and the AI guide orchestrates the entire pipeline with quality gates. The supporting methodologies extend that pipeline horizontally: osint-tradecraft-standards.md is the cross-cutting professional-tradecraft layer (ICD 203 · Admiralty Code · Words of Estimative Probability · SAT catalog · OSINT ethics) every artifact applies; confidence-calibration.md is the single source of truth for confidence labels (3-marker operational + 5-level heritage scale, WEP bands, Admiralty grades); synthesis-methodology.md governs the Stage-B.7 synthesis layer; strategic-extensions-methodology.md, electoral-domain-methodology.md and electoral-cycle-methodology.md cover deep-analysis and electoral-specific runs; per-document-methodology.md and structural-metadata-methodology.md cover atomic per-EP-document analysis and run-level provenance; and imf-indicator-mapping.md (primary) + worldbank-indicator-mapping.md (non-economic) govern the economic-context evidence ladder.
🔄 Methodology Pipeline — How AI Agents Apply Frameworks
The following diagram illustrates the sequential pipeline that an AI agent follows when processing an incoming European Parliament data file:
This diagram shows how the core methodology/framework documents relate to each other and feed into the final analysis output. The visualisation focuses on the six core analytical frameworks because they are the load-bearing nodes; the horizon-conditional and cross-cutting methodologies (OSINT tradecraft, confidence calibration, source triangulation, synthesis, strategic extensions, per-document, structural metadata, electoral domain + cycle, analytical supplementary, IMF + WB indicator mappings, forward-projection, voter segmentation) are layers that every framework applies and are catalogued in the Methodology Summary Table below:
Master map of every analysis markdown file produced under analysis/daily/*/ — grouped by folder with methodology + template + depth floor + Mermaid type per artifact
Construction rules for provenance layer — analysis-index.md, document-analysis-index.md, manifest.json, and the extended/cross-reference-map.md + extended/data-download-manifest.md artifacts
⚠️STRIDE is NOT used. This methodology uses 5 purpose-built political intelligence frameworks. STRIDE (Spoofing/Tampering/Repudiation/Information Disclosure/Denial of Service/Elevation of Privilege) was designed for software security threat modeling and does not meaningfully transfer to political analysis. See political-threat-framework.md §Why NOT STRIDE for full rationale.
✍️ Political Intelligence Style Guide — political-style-guide.md
Attribute
Value
Purpose
Establishes writing standards for all political intelligence output
Cross-cutting professional analytic discipline applied by every framework to every artifact
Pillars
5: ICD 203 (9 analytic standards) · Admiralty Code (source × info grading) · Words of Estimative Probability (7 bands) · SAT catalog (10 techniques) · OSINT sourcing ethics
Key Standards
Grade every source (A1–F6 → 🟢/🟡/🔴) · Calibrated estimative vocabulary · Banned ambiguous terms · ≥10 SATs attested per run · No personal-life data on MEPs
Version
1.0
✅ Cross-cutting layer. Unlike the six domain frameworks above (which each own a specific analytic task), this framework defines the professional standards every framework applies — source grading, estimative language, structured analytic techniques, and OSINT ethics. It is attested in each run's methodology-reflection.md.
🗺️ Artifact Catalog — artifact-catalog.md
Attribute
Value
Purpose
Master map between the templates in analysis/templates/ (currently 61 — ls is truth) and the methodologies above; names the canonical run-relative path for every artifact
Stage-C completeness gate — npm run validate-analysis -- <runDir> (scripts/validate-analysis-completeness.js) reads this catalog plus reference-quality-thresholds.json and fails the agentic run with exit code 1 if any artifact is missing, below the line floor, lacks a mandatory Mermaid block, or shows placeholder leakage. The duplicate src/utils/validate-analysis-completeness.ts runtime layer was purged in the April-2026 aggregator-pipeline migration; the surviving CLI is the Stage-C source of truth.
Machine-readable per-artifact line-floor and depth-floor thresholds
Consumed by
Stage-C completeness gate — npm run validate-analysis -- <runDir> (scripts/validate-analysis-completeness.js) reads this JSON in machine mode to confirm every artifact meets its line/depth floor before the agentic-workflow reviewer creates the PR. Hermetic tests pass --thresholds to inject fixture floors. The duplicate src/utils/validate-analysis-completeness.ts runtime layer was purged in the April-2026 aggregator-pipeline migration.
Update cadence
Bumped whenever per-artifact-methodologies.md tightens or loosens a floor; the two files must stay in lock-step
💱 IMF Indicator Mapping — imf-indicator-mapping.md (primary economic source)
Attribute
Value
Purpose
Canonical mapping of IMF WEO / FM / IFS / BOP / ER / PCPS / GFSR / EREO / FSI / GFS / DOT indicator codes to EP analysis use cases
Paired MCP
IMF REST SDMX 3.0 client in src/mcp/imf-mcp-client.ts (virtual tools imf-list-databases, imf-search-databases, imf-get-parameter-defs, imf-get-parameter-codes, imf-fetch-data)
🌍 World Bank Indicator Mapping — worldbank-indicator-mapping.md (non-economic)
Attribute
Value
Purpose
Canonical mapping of World Bank WDI indicator codes — non-economic domains only, education, social, environment, demographics, defence, agriculture, innovation, governance. The legacy WB economic codes are retained for backward compatibility but MUST NOT be used in new articles; economic context → IMF
Paired MCP
World Bank MCP (world-bank-* tools)
✅ Together, artifact-catalog.md (what), per-artifact-methodologies.md (how), and reference-quality-thresholds.json (how much) form the Stage B / Stage C contract enforced by the Stage-C validator (npm run validate-analysis) plus an editorial completeness review. The two indicator-mapping files provide the Stage A economic-context inputs that editorial policy requires — IMF for economic/fiscal/monetary/trade claims, WB for non-economic domains. Analysis-completeness enforcement lives in the CLI plus Stage-C editorial review.
Dual-track lens for the election-cycle horizon — extends electoral-domain-methodology.md with a protocol that promotes the electoral lens to the primary lens of the article
Tracks
Track A — Term Retrospective (vote-share delta vs prior baseline, mandate-fulfilment scorecard, defection-flow map) · Track B — Term Forecast (seat projections per group at 6/12/24/36-month horizons, coalition viability matrix, Spitzenkandidaten arithmetic, treaty-revision feasibility)
EP-Term anchors
Canonical constants for EP9 (2 Jul 2019 → 1 Jul 2024), EP10 (16 Jul 2024 → ~end of Jun 2029), EP11 (~Jul 2029 → ~Jun 2034)
Output artifacts
term-arc.md, seat-projection.md, mandate-fulfilment-scorecard.md (also referenced by forward-projection-methodology.md for the electoral-cycle track)
Tradecraft anchors
F3EAD ANALYZE; Admiralty A1/A2/B2/C2 floors per data class; WEP per seat-projection band at 6/12/24/36 mo; ICD 203 standards 3/4/7; SATs: Reference-Class Forecasting, Devil's Advocate, Outside-In, Indicators & Warnings, Pre-Mortem, Coalition Mathematics
Used by
news-election-cycle.md, news-term-outlook.md (single-PR layout, no split-PR)
🏷️ 1. Political Classification Guide
Purpose & Scope
The classification guide establishes the authoritative methodology for categorizing every European Parliament event and document entering the analysis pipeline. It serves as the mandatory first step before any other analytical framework is applied.
Key Concepts
Concept
Description
Scale
Sensitivity Levels
Determines publication handling requirements
🟢 PUBLIC → 🟡 SENSITIVE → 🔴 RESTRICTED
Policy Domain Taxonomy
Categorizes events by EU policy area
Environment, Economy, Foreign Affairs, Justice, etc.
Feeds into Threat Framework: Sensitivity level determines which threat dimensions to prioritize
Feeds into SWOT: High-classification events trigger SWOT re-assessment
⚠️ 2. Political Risk Methodology
Purpose & Scope
Provides a systematic Likelihood × Impact scoring framework for European Parliament political risks, adapted from the Hack23 ISMS Risk Assessment Methodology. Produces quantified risk scores across six EP-specific risk categories.
Key Concepts
Concept
Description
Scale
Likelihood Scale
Probability of risk materializing
Rare (1) → Unlikely (2) → Possible (3) → Likely (4) → Almost Certain (5)
Impact Scale
Severity of consequences if realized
Negligible (1) → Minor (2) → Moderate (3) → Major (4) → Severe (5)
Feeds into SWOT: Risk scores populate the Threats and Weaknesses quadrants
🎯 3. Political Threat Framework
Purpose & Scope
Provides comprehensive, multi-framework political threat analysis using purpose-built political intelligence frameworks. This framework explicitly rejects software-centric threat models (STRIDE, DREAD, PASTA) in favor of six frameworks designed for democratic process analysis.
%%{init: {"theme":"dark","themeVariables":{"primaryColor":"#1565C0","primaryTextColor":"#ffffff","primaryBorderColor":"#0A3F7F","lineColor":"#90CAF9","secondaryColor":"#2E7D32","secondaryTextColor":"#ffffff","secondaryBorderColor":"#0F3F00","tertiaryColor":"#FF9800","tertiaryTextColor":"#000000","tertiaryBorderColor":"#7F4F00","mainBkg":"#1565C0","secondBkg":"#2E7D32","tertiaryBkg":"#FF9800","noteBkgColor":"#FFC107","noteTextColor":"#000000","noteBorderColor":"#7F6000","errorBkgColor":"#D32F2F","errorTextColor":"#ffffff","fontFamily":"Inter, Helvetica, Arial, sans-serif","pie1":"#1565C0","pie2":"#2E7D32","pie3":"#FF9800","pie4":"#D32F2F","pie5":"#FFC107","pie6":"#7B1FA2","pie7":"#9E9E9E","pie8":"#0288D1","pie9":"#388E3C","pie10":"#F57C00","pie11":"#C62828","pie12":"#FBC02D","pieTitleTextSize":"18px","pieSectionTextSize":"14px","pieLegendTextSize":"13px","pieStrokeColor":"#1e1e1e","pieOuterStrokeColor":"#1e1e1e","git0":"#1565C0","git1":"#2E7D32","git2":"#FF9800","git3":"#D32F2F","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#000000","gitBranchLabel3":"#ffffff","cScale0":"#1565C0","cScale1":"#2E7D32","cScale2":"#FF9800","cScale3":"#D32F2F","cScale4":"#FFC107","cScale5":"#7B1FA2","cScale6":"#9E9E9E","cScale7":"#0288D1","xyChart":{"backgroundColor":"#1e1e1e","plotColorPalette":"#1565C0,#2E7D32,#FF9800,#D32F2F,#FFC107,#7B1FA2,#9E9E9E"}}}}%%
graph TB
PTL([🎯 Political Threat<br/>Landscape Analysis]) --> CS[🔄 Coalition Shifts<br/>Voting bloc realignment]
PTL --> TD[🔍 Transparency Deficit<br/>Information asymmetry]
PTL --> PR[↩️ Policy Reversal<br/>Legislative rollback]
PTL --> IP[🏛️ Institutional Pressure<br/>Power concentration]
PTL --> LO[⏳ Legislative Obstruction<br/>Procedural sabotage]
PTL --> DE[📉 Democratic Erosion<br/>Norm degradation]
CS --> SEV{Severity 1–5}
TD --> SEV
PR --> SEV
IP --> SEV
LO --> SEV
DE --> SEV
SEV --> DM[💎 Diamond Model]
SEV --> AT[🌳 Attack Trees]
SEV --> PE[🌍 PESTLE]
SEV --> SP[🎲 Scenario Planning]
SEV --> KC[🔗 Kill Chain]
style PTL fill:#B71C1C,stroke:#880E4F,color:#FFFFFF
style CS fill:#E65100,stroke:#BF360C,color:#FFFFFF
style TD fill:#E65100,stroke:#BF360C,color:#FFFFFF
style PR fill:#E65100,stroke:#BF360C,color:#FFFFFF
style IP fill:#E65100,stroke:#BF360C,color:#FFFFFF
style LO fill:#E65100,stroke:#BF360C,color:#FFFFFF
style DE fill:#E65100,stroke:#BF360C,color:#FFFFFF
style SEV fill:#F57F17,stroke:#E65100,color:#000000
style DM fill:#4527A0,stroke:#311B92,color:#FFFFFF
style AT fill:#4527A0,stroke:#311B92,color:#FFFFFF
style PE fill:#4527A0,stroke:#311B92,color:#FFFFFF
style SP fill:#4527A0,stroke:#311B92,color:#FFFFFF
style KC fill:#4527A0,stroke:#311B92,color:#FFFFFF
Loading
Connection to Other Methodologies
Receives from Classification: Sensitivity levels determine which threat dimensions require analysis
Receives from Risk: High-risk scores trigger multi-framework deep analysis
Feeds into SWOT: Identified threats populate the Threats quadrant with evidence chains
💼 4. Political SWOT Framework
Purpose & Scope
Establishes an evidence-based SWOT methodology where every entry in every quadrant must cite verifiable European Parliament data. This framework rejects opinion-based SWOT analysis and enforces confidence levels with a 180-day expiration rule.
Key Concepts
Concept
Description
Details
Evidence Requirement
Every SWOT entry must cite EP data sources
MCP tool calls, document references, voting records
Confidence Levels
Reliability grading for each entry
HIGH (multiple current sources) · MEDIUM (single primary) · LOW (credible but unverified)
180-Day Decay
Entries expire if not re-verified
Prevents stale assessments from persisting
Group-to-Landscape Aggregation
Individual political group SWOTs aggregate into landscape-level SWOT
Weighted by seat share and coalition significance
Minimum Density
Each quadrant must contain at least 2 entries
Prevents superficial analysis
SWOT Quadrant Flow
%%{init: {"theme":"dark","themeVariables":{"primaryColor":"#1565C0","primaryTextColor":"#ffffff","primaryBorderColor":"#0A3F7F","lineColor":"#90CAF9","secondaryColor":"#2E7D32","secondaryTextColor":"#ffffff","secondaryBorderColor":"#0F3F00","tertiaryColor":"#FF9800","tertiaryTextColor":"#000000","tertiaryBorderColor":"#7F4F00","mainBkg":"#1565C0","secondBkg":"#2E7D32","tertiaryBkg":"#FF9800","noteBkgColor":"#FFC107","noteTextColor":"#000000","noteBorderColor":"#7F6000","errorBkgColor":"#D32F2F","errorTextColor":"#ffffff","fontFamily":"Inter, Helvetica, Arial, sans-serif","pie1":"#1565C0","pie2":"#2E7D32","pie3":"#FF9800","pie4":"#D32F2F","pie5":"#FFC107","pie6":"#7B1FA2","pie7":"#9E9E9E","pie8":"#0288D1","pie9":"#388E3C","pie10":"#F57C00","pie11":"#C62828","pie12":"#FBC02D","pieTitleTextSize":"18px","pieSectionTextSize":"14px","pieLegendTextSize":"13px","pieStrokeColor":"#1e1e1e","pieOuterStrokeColor":"#1e1e1e","git0":"#1565C0","git1":"#2E7D32","git2":"#FF9800","git3":"#D32F2F","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#000000","gitBranchLabel3":"#ffffff","cScale0":"#1565C0","cScale1":"#2E7D32","cScale2":"#FF9800","cScale3":"#D32F2F","cScale4":"#FFC107","cScale5":"#7B1FA2","cScale6":"#9E9E9E","cScale7":"#0288D1","xyChart":{"backgroundColor":"#1e1e1e","plotColorPalette":"#1565C0,#2E7D32,#FF9800,#D32F2F,#FFC107,#7B1FA2,#9E9E9E"}}}}%%
graph LR
subgraph Internal
S[✅ Strengths<br/>Legislative achievements<br/>Institutional cohesion]
W[⚠️ Weaknesses<br/>Group fragmentation<br/>Legislative stalls]
end
subgraph External
O[🚀 Opportunities<br/>Landmark legislation<br/>Cross-party consensus]
T[🔴 Threats<br/>Far-right growth<br/>Legitimacy crisis]
end
S --> Synth[📊 Strategic Synthesis<br/>with Confidence Levels]
W --> Synth
O --> Synth
T --> Synth
style S fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
style W fill:#E65100,stroke:#BF360C,color:#FFFFFF
style O fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
style T fill:#B71C1C,stroke:#880E4F,color:#FFFFFF
style Synth fill:#4527A0,stroke:#311B92,color:#FFFFFF
Loading
Connection to Other Methodologies
Receives from Classification, Risk, and Threat: All three upstream frameworks feed evidence into SWOT quadrants
Feeds into Style Guide: SWOT depth determines the appropriate writing depth level
Feeds into AI Guide: SWOT completeness is a quality gate criterion (≥2 entries per quadrant)
📝 5. Political Style Guide
Purpose & Scope
Establishes mandatory writing standards for all political intelligence analysis produced by EU Parliament Monitor's agentic workflows. Defines three depth levels calibrated to the classification severity and audience needs.
Key Concepts
Concept
Description
Specification
Level 1 — Surface
News summary for breaking events
200–500 words, min. 2 citations, daily scores
Level 2 — Strategic
Analysis article for weekly/committee briefs
800–2,000 words, min. 5 citations, policy recommendations
Level 3 — Intelligence
Deep analysis for monthly reports and MEP scorecards
2,000–5,000 words, min. 10 citations, scenario projections
Evidence Density
Minimum citations per artifact type
Varies by depth level: EP document refs + MCP data points
Anti-Patterns
Prohibited writing behaviors
No tables-only, no uncited claims, no opinions without evidence
Multi-Language
Standards for 14-language output
Consistent analytical structure across all supported languages
Receives from Classification: Severity determines depth level (Level 1, 2, or 3)
Receives from SWOT: Strategic synthesis informs the narrative structure
Feeds into AI Guide: Style compliance is a quality gate criterion
🤖 6. AI-Driven Analysis Guide
Purpose & Scope
Defines the comprehensive per-file AI analysis protocol. This is the orchestrator document that AI agents must read before processing any European Parliament data file. It specifies the analysis pipeline, document-type focus templates, quality gates, and conflict resolution for parallel workflows.
Key Concepts
Concept
Description
Specification
Per-File Protocol
Each EP MCP data file receives its own analysis
Dedicated markdown output per source file
Document-Type Templates
Tailored analysis focus per EP document type
Adopted texts, procedures, votes, speeches, questions, events, etc.
%%{init: {"theme":"dark","themeVariables":{"primaryColor":"#1565C0","primaryTextColor":"#ffffff","primaryBorderColor":"#0A3F7F","lineColor":"#90CAF9","secondaryColor":"#2E7D32","secondaryTextColor":"#ffffff","secondaryBorderColor":"#0F3F00","tertiaryColor":"#FF9800","tertiaryTextColor":"#000000","tertiaryBorderColor":"#7F4F00","mainBkg":"#1565C0","secondBkg":"#2E7D32","tertiaryBkg":"#FF9800","noteBkgColor":"#FFC107","noteTextColor":"#000000","noteBorderColor":"#7F6000","errorBkgColor":"#D32F2F","errorTextColor":"#ffffff","fontFamily":"Inter, Helvetica, Arial, sans-serif","pie1":"#1565C0","pie2":"#2E7D32","pie3":"#FF9800","pie4":"#D32F2F","pie5":"#FFC107","pie6":"#7B1FA2","pie7":"#9E9E9E","pie8":"#0288D1","pie9":"#388E3C","pie10":"#F57C00","pie11":"#C62828","pie12":"#FBC02D","pieTitleTextSize":"18px","pieSectionTextSize":"14px","pieLegendTextSize":"13px","pieStrokeColor":"#1e1e1e","pieOuterStrokeColor":"#1e1e1e","git0":"#1565C0","git1":"#2E7D32","git2":"#FF9800","git3":"#D32F2F","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#000000","gitBranchLabel3":"#ffffff","cScale0":"#1565C0","cScale1":"#2E7D32","cScale2":"#FF9800","cScale3":"#D32F2F","cScale4":"#FFC107","cScale5":"#7B1FA2","cScale6":"#9E9E9E","cScale7":"#0288D1","xyChart":{"backgroundColor":"#1e1e1e","plotColorPalette":"#1565C0,#2E7D32,#FF9800,#D32F2F,#FFC107,#7B1FA2,#9E9E9E"}}}}%%
flowchart TD
Data([📥 EP MCP Data File]) --> Read[📚 Read All 6 Methodologies]
Read --> Analyze[🔬 Execute Analysis Pipeline<br/>Classify → Risk → Threat → SWOT → Write]
Analyze --> Self[🔍 Self-Assessment Scoring]
Self --> E[Evidence<br/>Weight: 25%]
Self --> D[Depth<br/>Weight: 25%]
Self --> St[Structural<br/>Weight: 20%]
Self --> A[Actionable<br/>Weight: 15%]
Self --> N[Neutrality<br/>Weight: 15%]
E --> Calc[📊 Calculate<br/>Weighted Score]
D --> Calc
St --> Calc
A --> Calc
N --> Calc
Calc --> Gate{Score ≥ 7.0?}
Gate -->|✅ Pass| Publish([📤 Publish])
Gate -->|❌ Fail| Revise[🔄 Revise Analysis]
Revise --> Analyze
style Data fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
style Read fill:#4527A0,stroke:#311B92,color:#FFFFFF
style Analyze fill:#00695C,stroke:#004D40,color:#FFFFFF
style Self fill:#F57F17,stroke:#E65100,color:#000000
style E fill:#1B5E20,stroke:#1B5E20,color:#FFFFFF
style D fill:#1B5E20,stroke:#1B5E20,color:#FFFFFF
style St fill:#1B5E20,stroke:#1B5E20,color:#FFFFFF
style A fill:#1B5E20,stroke:#1B5E20,color:#FFFFFF
style N fill:#1B5E20,stroke:#1B5E20,color:#FFFFFF
style Calc fill:#4527A0,stroke:#311B92,color:#FFFFFF
style Gate fill:#E65100,stroke:#BF360C,color:#FFFFFF
style Publish fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
style Revise fill:#B71C1C,stroke:#880E4F,color:#FFFFFF
Loading
Connection to Other Methodologies
Orchestrates all frameworks: AI Guide is the entry point that invokes Classification → Risk → Threat → SWOT → Style in sequence
Enforces quality gates: Validates outputs from every upstream methodology meet minimum standards
Handles conflicts: Resolves parallel workflow collisions via timestamp-based precedence rules
Mandates AI-driven metadata: All article titles, descriptions, and SEO keywords MUST be produced by the AI agent analysing the content — NEVER by script code or template strings. The AI agent passes --title and --description CLI flags to the generator.
🌳 Methodology Selection Decision Tree
Use this flowchart to determine which methodology to apply for a given analytical task:
%%{init: {"theme":"dark","themeVariables":{"primaryColor":"#1565C0","primaryTextColor":"#ffffff","primaryBorderColor":"#0A3F7F","lineColor":"#90CAF9","secondaryColor":"#2E7D32","secondaryTextColor":"#ffffff","secondaryBorderColor":"#0F3F00","tertiaryColor":"#FF9800","tertiaryTextColor":"#000000","tertiaryBorderColor":"#7F4F00","mainBkg":"#1565C0","secondBkg":"#2E7D32","tertiaryBkg":"#FF9800","noteBkgColor":"#FFC107","noteTextColor":"#000000","noteBorderColor":"#7F6000","errorBkgColor":"#D32F2F","errorTextColor":"#ffffff","fontFamily":"Inter, Helvetica, Arial, sans-serif","pie1":"#1565C0","pie2":"#2E7D32","pie3":"#FF9800","pie4":"#D32F2F","pie5":"#FFC107","pie6":"#7B1FA2","pie7":"#9E9E9E","pie8":"#0288D1","pie9":"#388E3C","pie10":"#F57C00","pie11":"#C62828","pie12":"#FBC02D","pieTitleTextSize":"18px","pieSectionTextSize":"14px","pieLegendTextSize":"13px","pieStrokeColor":"#1e1e1e","pieOuterStrokeColor":"#1e1e1e","git0":"#1565C0","git1":"#2E7D32","git2":"#FF9800","git3":"#D32F2F","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#000000","gitBranchLabel3":"#ffffff","cScale0":"#1565C0","cScale1":"#2E7D32","cScale2":"#FF9800","cScale3":"#D32F2F","cScale4":"#FFC107","cScale5":"#7B1FA2","cScale6":"#9E9E9E","cScale7":"#0288D1","xyChart":{"backgroundColor":"#1e1e1e","plotColorPalette":"#1565C0,#2E7D32,#FF9800,#D32F2F,#FFC107,#7B1FA2,#9E9E9E"}}}}%%
sequenceDiagram
participant WF as 🔄 Agentic Workflow
participant DL as 📥 Data Download
participant CLASS as 🏷️ Classification
participant RISK as ⚠️ Risk Assessment
participant SWOT as 💼 SWOT Analysis
participant THREAT as 🎭 Threat Analysis
participant SIG as 📈 Significance
participant SYNTH as 🧩 Synthesis
participant QG as ✅ Quality Gate
participant ART as 📰 Article Generation
WF->>DL: Fetch EP MCP feed data
DL->>CLASS: Raw documents + metadata
Note over CLASS,THREAT: AI performs ALL analysis<br/>(never scripted)
CLASS->>RISK: Classification results
CLASS->>SWOT: Document classification
CLASS->>THREAT: Document classification
par Parallel Analysis
RISK->>SIG: Risk scores + cascading analysis
SWOT->>SIG: SWOT matrices + strategic implications
THREAT->>SIG: Threat profiles + kill chains
end
SIG->>SYNTH: Significance scores
SYNTH->>QG: Synthesis summary
QG-->>QG: Validate structure,<br/>evidence, Mermaid,<br/>confidence, citations
QG->>ART: Approved analysis
ART->>WF: HTML article + 14 translations
Note over QG: Quality gate checks:<br/>✓ Evidence tables<br/>✓ Mermaid diagrams<br/>✓ EP procedure citations<br/>✓ Confidence labels<br/>✓ No stub content
Loading
🎯 Article-Type-Specific Methodology Selection
Different EP document types require different analytical emphasis. This matrix maps which methodologies are PRIMARY vs SUPPORTING for each workflow type:
Article Type
Classification
Risk
SWOT
Threat
Significance
Stakeholder
Unique Focus
Breaking News
🔴 PRIMARY
🔴 PRIMARY
✅
✅
🔴 PRIMARY
✅
Real-time urgency scoring, political temperature spike detection
Motions
🔴 PRIMARY
✅
✅
🔴 PRIMARY
✅
✅
Per-resolution vote breakdown by group, defection pattern analysis
Strategic political calendar, major policy decision forecast
Monthly Review
✅
✅
🔴 PRIMARY
✅
✅
🔴 PRIMARY
Legislative throughput, political group productivity, Grand Coalition scorecard
Reading the matrix: ✅ = always required for all types. 🔴 PRIMARY = the methodology that should receive the most analytical depth and word count for this article type. Each workflow must apply ALL methodologies but allocate more time and depth to PRIMARY ones.
Unique Analytical Sections Per Article Type
Each article type should produce unique analytical sections in its synthesis that no other workflow can produce:
Article Type
Template
Unique Section Name
What Makes It Unique
Breaking News
Significance
Breaking Urgency Rating
Real-time significance assessment with 6-hour refresh — only breaking workflow has this cadence
Motions
Threat
Defection Pattern Dashboard
Political group voting discipline per-resolution — only motion workflow analyses individual votes
Propositions
Risk
Legislative Pipeline Risk
Where the procedure sits (committee → plenary → trilogue → adoption) and risk of delay/amendment
Propositions
Stakeholder
Rapporteur Influence Scorecard
Rapporteur and shadow rapporteur influence mapping — unique to procedure-level analysis
Committee Reports
Stakeholder
Committee Productivity Matrix
Per-committee output volume, meeting frequency, document production rate
Committee Reports
Classification
Cross-Committee Comparison
Relative workload and output comparison across EP committees
Week Ahead
SWOT
Pre-Plenary Intelligence Brief
Forward-looking SWOT for upcoming plenary agenda — only week-ahead can provide this prospective view
Weekly Review
SWOT
Week-over-Week Trend Delta
How did this week's political temperature differ from last week? Only weekly scope enables this
Month Ahead
Risk
Strategic Calendar Risk Map
Forward-looking risk landscape tied to specific scheduled events (budget debates, EU summits)
Monthly Review
Synthesis
Grand Coalition Scorecard
Comprehensive monthly assessment of Grand Coalition legislative effectiveness and cohesion
✅ Quality Gate Requirements
All analysis produced under these methodologies must meet the following minimum quality requirements before publication:
Weighted Quality Score (Minimum 7.0/10)
Dimension
Weight
Criteria
Fail Indicators
Evidence
25%
Every claim cites EP MCP data; confidence levels stated; no opinion-only entries
Uncited claims, missing confidence, assertions without data
Depth
25%
Appropriate depth level (L1/L2/L3) applied; word count within range; citation count met
Wrong depth level, under minimum citations, superficial coverage
All opinions must cite verifiable EP MCP data sources
Hardcoded Mermaid values
Static diagrams become stale and misleading
Use data-driven values sourced from EP MCP tool results
Shallow classification
Single-dimension classification misses complexity
Apply all 7 classification dimensions; score each independently
Stale SWOT entries
Entries older than 180 days without re-verification are unreliable
Enforce 180-day decay rule; re-verify or remove expired entries
Missing stakeholder analysis
Analysis without impact assessment has no actionable value
Identify affected political groups, MEPs, committees, and citizens
Ignoring multi-language requirements
Analysis must serve 14-language platform
Structure content for translation; avoid idioms and culture-specific references
🔗 ISMS Reference Adaptations
The analysis methodologies are adapted from Hack23's ISO 27001/NIST CSF/CIS Controls ISMS framework. The reference/ directory contains mapping documents showing how cybersecurity risk concepts translate to political intelligence:
Each agentic workflow applies the methodologies with unique emphasis tailored to its article type. The following shows which methodologies are primary vs. supporting for each workflow:
%%{init: {"theme":"dark","themeVariables":{"primaryColor":"#1565C0","primaryTextColor":"#ffffff","primaryBorderColor":"#0A3F7F","lineColor":"#90CAF9","secondaryColor":"#2E7D32","secondaryTextColor":"#ffffff","secondaryBorderColor":"#0F3F00","tertiaryColor":"#FF9800","tertiaryTextColor":"#000000","tertiaryBorderColor":"#7F4F00","mainBkg":"#1565C0","secondBkg":"#2E7D32","tertiaryBkg":"#FF9800","noteBkgColor":"#FFC107","noteTextColor":"#000000","noteBorderColor":"#7F6000","errorBkgColor":"#D32F2F","errorTextColor":"#ffffff","fontFamily":"Inter, Helvetica, Arial, sans-serif","pie1":"#1565C0","pie2":"#2E7D32","pie3":"#FF9800","pie4":"#D32F2F","pie5":"#FFC107","pie6":"#7B1FA2","pie7":"#9E9E9E","pie8":"#0288D1","pie9":"#388E3C","pie10":"#F57C00","pie11":"#C62828","pie12":"#FBC02D","pieTitleTextSize":"18px","pieSectionTextSize":"14px","pieLegendTextSize":"13px","pieStrokeColor":"#1e1e1e","pieOuterStrokeColor":"#1e1e1e","git0":"#1565C0","git1":"#2E7D32","git2":"#FF9800","git3":"#D32F2F","gitBranchLabel0":"#ffffff","gitBranchLabel1":"#ffffff","gitBranchLabel2":"#000000","gitBranchLabel3":"#ffffff","cScale0":"#1565C0","cScale1":"#2E7D32","cScale2":"#FF9800","cScale3":"#D32F2F","cScale4":"#FFC107","cScale5":"#7B1FA2","cScale6":"#9E9E9E","cScale7":"#0288D1","xyChart":{"backgroundColor":"#1e1e1e","plotColorPalette":"#1565C0,#2E7D32,#FF9800,#D32F2F,#FFC107,#7B1FA2,#9E9E9E"}}}}%%
flowchart TD
subgraph "🏷️ Classification"
CG["Political Classification Guide"]
end
subgraph "⚠️ Risk"
RM["Risk Methodology"]
end
subgraph "🎯 Threat"
TF["Political Threat Framework"]
end
subgraph "💼 SWOT"
SW["SWOT Framework"]
end
subgraph "📰 Workflow Article Types"
BK["🔴 Breaking\n= CG + RM primary"]
MO["📋 Motions\n= CG + TF primary"]
PR["📜 Propositions\n= RM + SW primary"]
CR["🏛️ Committee\n= RM + CG primary"]
WA["📅 Week Ahead\n= SW + RM primary"]
WR["📊 Weekly Review\n= CG + SW primary"]
MA["📆 Month Ahead\n= SW + TF primary"]
MR["📈 Monthly Review\n= ALL primary"]
end
CG --> BK & MO & CR & WR
RM --> BK & PR & CR & WA & MR
TF --> MO & MA & MR
SW --> PR & WA & WR & MA & MR
style CG fill:#00695C,stroke:#004D40,color:#fff
style RM fill:#E65100,stroke:#BF360C,color:#fff
style TF fill:#B71C1C,stroke:#880E4F,color:#fff
style SW fill:#1B5E20,stroke:#1B5E20,color:#fff
style BK fill:#dc3545,stroke:#b02a37,color:#fff
style MO fill:#fd7e14,stroke:#ca6510,color:#fff
style PR fill:#ffc107,stroke:#cc9a06,color:#000
style CR fill:#198754,stroke:#146c43,color:#fff
style WA fill:#0d6efd,stroke:#0a58ca,color:#fff
style WR fill:#6f42c1,stroke:#59359a,color:#fff
style MA fill:#d63384,stroke:#ab296a,color:#fff
style MR fill:#0dcaf0,stroke:#0aa2c0,color:#000
📈 Comprehensive trend analysis; inter-temporal pattern detection; political landscape evolution
Key principle: Every article type must produce analysis that is unique and specific to its focus area. A breaking news analysis looks fundamentally different from a monthly review analysis — different data sources, different methodology emphasis, different analytical depth.
📝 Changelog
v3.3 (2026-05-03)
Document
Change
Rationale
examples/ (new directory)
Added four worked "good-output" excerpts under examples/ — SWOT, stakeholder map, risk matrix, scenario forecast — each cross-linked to its companion methodology section and template, with a Pass-2 checklist that mirrors the methodology's quality-signal language.
Closes the issue's "worked example" deliverable; gives an AI agent a concrete, evidence-dense reference to diff Pass-1 drafts against during Pass-2 read-back.
test/unit/methodology-catalog.test.js (new test)
Drift-guard asserts the four-way match between artifact-catalog.md, reference-quality-thresholds.json, per-artifact-methodologies.md, and analysis/templates/. Six assertions: catalog parses ≥54 rows (tight enough to catch any dropped section), every template link resolves, every methodology link resolves, every per-artifact-methodologies.md#anchor resolves to a real ### section, every numeric breaking floor in the catalog has a row in the threshold registry, and every threshold path is known to the catalog (reverse check).
Promotes the catalog ↔ thresholds ↔ templates ↔ per-artifact-methodologies invariant from a manual review item to a CI-enforced contract; future drift fails fast in unit tests rather than during a 60-minute agentic run.
examples/README.md (new)
Index + anti-patterns + "how to add a new example" pointer.
Makes the examples directory self-documenting and discoverable from this index.
v3.2 (2026-04-25)
Document
Change
Rationale
README.md (v3.1→v3.2)
Headline corrected from “seven frameworks” to “fourteen interlocking methodologies”; the seven core frameworks are kept and the seven supporting methodologies (Synthesis · Strategic Extensions · Per-Document · Structural Metadata · Electoral Domain · IMF + WB Indicator Mappings) are now first-class in the index
Documentation drift — directory carries 18 docs; old headline understated the discipline
README.md (v3.1→v3.2)
Template count updated 39 → 51 across catalog and template-pairing prose
Reconciliation with disk-truth: analysis/templates/ carries 51 numbered templates plus the README
“Legacy validator was purged” language replaced with the correct two-layer fact: the duplicate src/utils/validate-analysis-completeness.ts was purged, but the surviving scripts/validate-analysis-completeness.js remains the Stage-C completeness gate (npm run validate-analysis -- <runDir>)
Drift fix — the surviving CLI is wired into package.json and is the truth-source per test/unit/validate-analysis-completeness.test.js; READMEs incorrectly described it as removed
templates/README.md (v3.1→v3.2)
Cover line updated 39 → 51; v3.2 changelog entry added; badge dates and Next-Review aligned with methodology release
Same reconciliation as above
political-threat-framework.md (v4.0→v4.1)
Date refresh + cross-link tightening to the five threat-assessment templates (political-threat-landscape, actor-threat-profiles, consequence-trees, legislative-disruption, threat-analysis); explicit “STRIDE rejected” statement preserved
Metadata refreshed to v3.2 / 2026-04-25 / Next Review 2026-07-31; cross-references between methodologies tightened so each ### artifact section in per-artifact-methodologies.md resolves both ways
Single coherent v3.2 release — every methodology stamped with the same effective date and review window
reference-quality-thresholds.json
Floors held stable at v3.1 levels; no artifact line-floor was lowered; missing artifact rows added so the validator stops emitting THRESHOLD_MISSING warnings on rare extended artifacts
Avoids retroactively failing older runs while closing the catalog → thresholds gap
