A methodology-first credit analysis engine for global fixed-income markets — delivered as Agent Skills (
SKILL.md), installable into Claude Code, Codex, Cursor, Gemini, and OpenCode. Built for credit professionals who need rigorous, reproducible, and transparent credit analysis that goes beyond traditional financial metrics.
Version v0.3.2 (changelog) · 30 methodology documents · 16 work paths · 4 coded engines · pytest regression suite + consistency gates (CI: Ubuntu & Windows) · 🌐 English
- What Is Credence
- Engine Architecture
- The Four-Stage Pipeline
- International Paradigms & Work Paths
- Quick Start
- Agent CLI Compatibility
- Repository Map
- FAQ
- License & Disclaimer
Credence packages the methodology of a seasoned fixed-income credit analyst into a form an AI agent can load and execute directly. It is not an agent framework and not a standalone app — it is a domain-methodology skill pack designed for institutional-grade credit analysis across international bond markets.
Traditional financial analysis rests on an implicit assumption — that a firm's credit risk can be read from its financial statements. This assumption systematically fails in three industry archetypes:
| Industry Type | Why Financial Analysis Fails | Heaviest Factor Location |
|---|---|---|
| Policy-Driven (Solar, Semiconductors) | Policy cycles determine industry demand ceilings; sudden shifts can devastate an industry within weeks | Industrial policy / Geopolitics (not on balance sheet) |
| Technology-Moat (Advanced Equipment, Biopharma) | Core assets (IP, pipeline, certifications) are not on balance sheet; many pre-revenue firms cannot be valued by PE/PB | Technology roadmap / Core IP (not on balance sheet) |
| Asset-Lease (Data Centers, Infrastructure REITs) | REIT-like profile; core metrics are NOI/DSCR rather than traditional indicators | Customer lease quality (not on balance sheet) |
The heaviest credit factors are never on the balance sheet. External credit ratings lag real credit deterioration by an average of 17+ months (Enron, Lehman Brothers, Wirecard, Greece sovereign — all rated investment grade within months of default).
| Theory | Implication | Engine Implementation |
|---|---|---|
| Mosaic Theory | Individual public data fragments are meaningless in isolation; assembled together they form a complete picture | Multi-source data aggregation, signal stacking, confidence weighting |
| Information Completeness Theory | Data gaps are not defects — they are risk signals. "We do not have this data" itself tells the user that a dimension carries uncertainty | Every analysis conclusion includes a data completeness score and a gap list |
System-Intelligence Layer (Layer 4)
Contagion Map x Concentration Dashboard x Systemic Risk Index (SRI)
|
Single-Issuer Results
|
┌─────────┴─────────┐
│ Mosaic Engine │ Signal extraction + assembly + completeness
│ (Layer 1) │
└─────────┬─────────┘
|
┌────────────┼────────────┐
│ │ │
Track A Track B Track C+: Multi-Stakeholder
Fundamental Market 6 Buy-Side Roles
Analysis Pricing
│ │
└──────┬─────┘
▼
Cross-Validation Matrix
Consensus -> Mutual reinforcement
Divergence -> Most valuable insight
│
▼
Integrated Output
Rating + Signals + Completeness Report
Extracting signals from fragmented public data.
The Mosaic Engine operates as the data-inception layer of the entire analysis pipeline. It ingests unstructured, multi-source public data and transforms it into structured, confidence-weighted signals ready for downstream dual-track analysis.
The engine collects data from seven public-source categories — macro policy, industry data, supply chain pricing, corporate filings, litigation/regulatory records, bond market data, and macroeconomic indicators — all through free, publicly available channels (WebSearch, SEC EDGAR, central bank portals, FRED, TRACE, etc.).
Individual data points are assembled into an industry-pyramid-aligned mosaic using a rules engine. The assembly process stacks signals by source reliability, temporal recency, and cross-source corroboration, producing a structured signal map for each issuer.
Every analysis conclusion includes a quantitative completeness score (0-100) and an explicit gap list. The engine distinguishes between:
- Known knowns — data points confirmed from multiple sources
- Known unknowns — data gaps identified and flagged as risk signals
- Unknown unknowns — structural blind spots documented as methodological limitations
| Metric | Description |
|---|---|
| Completeness Score | 0-100 score per analysis dimension |
| Signal Confidence | Source-weighted confidence for each extracted signal |
| Gap Impact | Qualitative assessment of how each data gap affects rating reliability |
Fundamental analysis (Track A) vs. market pricing (Track B) cross-validation.
The Dual-Track engine runs two independent analysis tracks in parallel, then cross-validates their outputs. Divergence between tracks generates the engine's most valuable insights.
Applies the industry-pyramid framework — a ten-dimension scoring system (D1-D10) that evaluates:
| Dimension | Focus |
|---|---|
| D1-D3 | Structural industry position, policy environment, competitive moat |
| D4-D6 | Business model resilience, revenue stability, cost structure |
| D7-D8 | Financial policy, capital structure, liquidity |
| D9-D10 | Governance, management track record, external support |
Scoring follows a strict layer-by-layer progression: Layer 1 (heaviest structural factors) must pass before Layer 2 analysis is meaningful; layers cannot be skipped. The financial layer (L4) serves as a validation layer for upper-layer judgments.
Analyzes four tiers of market-implied signals:
| Signal Tier | Indicators |
|---|---|
| Credit Spreads | Z-spread, asset swap spread, CDS premium |
| Volatility | Price volatility, implied volatility skew |
| Fund Flows | Primary market demand, secondary turnover, investor composition |
| Rating Migration | External rating trends, outlook changes, watch list entries |
| Track A / Track B | Positive Signals | Negative Signals |
|---|---|---|
| Positive | Mutual Reinforcement — high confidence | Track B Leading — market pricing ahead of fundamentals |
| Negative | Track A Leading — fundamentals deteriorate before market prices in | Mutual Confirmation — high certainty of distress |
On conflict, Track A (auditable public financial facts) takes priority over external ratings.
The engine's internal 0-10 composite score maps to the three major international rating agencies on an 18-notch scale — higher score means higher rating (9.5-10.0 = AAA at the top, 0-0.9 = D at the bottom), with a one-vote veto locking the composite ceiling at CCC. The full tier-by-tier alignment with S&P / Moody's / Fitch is single-sourced in dev/engine/dual-track-methodology.md §6 and is not duplicated here.
Financial framework: IFRS (International Financial Reporting Standards) and US GAAP (Generally Accepted Accounting Principles) are both supported, with automatic detection of reporting standards from issuer filings and adjustments for key differences (operating lease capitalization, R&D capitalization, deferred tax recognition).
Six buy-side roles with cross-role analysis matrix.
Different market participants look at the same credit through different lenses. The Multi-Stakeholder engine runs parallel assessments across six buy-side roles, then constructs a cross-comparison matrix that highlights consensus and divergence.
| # | Role | Core Decision | Horizon | Key Data Needs |
|---|---|---|---|---|
| 1 | Credit Selector | "Does this credit belong in the book?" — single-issuer rating, default probability | 12-36 months | Industry pyramid, financial deep-dive, LGD/recovery, external support |
| 2 | Portfolio Manager | "Is this the best risk/reward?" — relative value, sector allocation | 6-24 months | Relative value metrics, comparative analysis, curve positioning |
| 3 | Risk Officer | "Where are concentration/contagion hotspots?" — portfolio risk monitoring | Continuous (monthly SRI + event-driven) | Concentration dashboard, contagion matrix, SRI, stress tests |
| 4 | Trader | "Is today the day to act?" — execution, market timing | Intraday to 2 weeks | L0 signal card, real-time spreads, liquidity conditions |
| 5 | Advisor | "What should my client do?" — allocation advice, suitability | 3-12 months | Client risk profile overlay, L1 snapshot, thematic views |
| 6 | Individual Investor | "Should I own this bond?" — personal investment decision | 6-36 months | Simplified L0/L1, buy/hold/sell signal, plain-language risk summary |
When multiple stakeholders analyze the same issuer, the engine constructs a consensus/divergence matrix:
| Aspect | Consensus Scenario | Divergence Scenario |
|---|---|---|
| Credit Quality | All roles agree on rating direction | Credit Selector bullish, Risk Officer bearish -> deeper investigation |
| Risk Appetite | Portfolio Manager and Risk Officer align on concentration | Trader sees short-term opportunity, Risk Officer warns of tail risk |
| Time Horizon | All roles' signals point to the same trigger window | Diverging time horizons expose maturity-mismatch risk |
The cross-role matrix construction is single-sourced in dev/engine/multi-stakeholder.md; the historical default cases that exercise it (Lehman Brothers, Wirecard, Valeant, Credit Suisse, Greece) are documented in dev/engine/validation-methodology.md §6.
Cross-issuer systemic risk perception — contagion, concentration, and early warning.
The System-Intelligence Layer (SIL) is the topmost aggregation layer, responsible for detecting systemic risk patterns that no single-issuer analysis can reveal. It comprises three integrated modules and a fourth coded monitoring engine.
A full 19x19 inter-industry contagion intensity matrix based on the Global Industry Classification Standard (GICS), covering all major international economic sectors:
| # | Industry | Primary Paradigm | Contagion Role |
|---|---|---|---|
| 1 | Energy (Oil & Gas) | P1: Cyclical | Super-spreader (high outbound contagion) |
| 2 | Chemicals | P1: Cyclical | Moderate transmitter |
| 3 | Metals & Mining | P1: Cyclical | Cyclical amplifier |
| 4 | Construction Materials | P1: Cyclical | Infrastructure-linked transmitter |
| 5 | Capital Goods | P1: Cyclical | Manufacturing contagion hub |
| 6 | Commercial Services | P1: Cyclical | Low systemic linkage |
| 7 | Transportation | P4: Regulated Utility | Logistics transmission vector |
| 8 | Automobiles | P1: Cyclical | Consumer-industrial bridge |
| 9 | Consumer Durables | P1: Cyclical | Demand-cyclical receiver |
| 10 | Consumer Staples | P2: Defensive | Defensive, low contagion |
| 11 | Retail | P1: Cyclical | End-demand transmission receiver |
| 12 | Technology Hardware (Semis) | P3: Growth | Geopolitical contagion super-spreader |
| 13 | Software & Services | P3: Growth | Low direct contagion, high narrative spillover |
| 14 | Biotech & Pharma | P3: Growth | Regulatory shock receiver |
| 15 | Healthcare Equipment | P2: Defensive | Low cyclical contagion |
| 16 | Utilities (Regulated) | P4: Regulated Utility | Defensive, low contagion |
| 17 | Telecommunications | P4: Regulated Utility | Infrastructure contagion receiver |
| 18 | Financials (Banks/Insurance) | P5: Financial | Systemic super-spreader (highest outbound contagion) |
| 19 | Sovereigns & GSEs | P6: Sovereign-Linked | Foundational risk factor |
Key derived metrics include the Contagion Forward Coefficient (CFC), Contagion Vulnerability Coefficient (CVC), and Contagion Net Exposure Ratio (CNER), plus stress-escalation jump tables for factor-specific intensity increases.
Evaluates portfolio concentration risk across five independent dimensions:
| Dimension | Assessment |
|---|---|
| Industry Concentration | CR3 / CR5 / HHI / MAX1 by GICS industry |
| Regional Concentration | Single country/region share + weak-region share |
| Rating Concentration | External AAA share + pseudo-high-rating share |
| Tenor Concentration | 12-month maturity share + single-month peak |
| Funding Channel Concentration | Top funding-channel share + contraction status |
Thresholds, traffic-light bands, and the notch-impact mapping for each dimension are single-sourced in dev/engine/concentration-framework.md and are not duplicated here.
The SRI aggregates multi-source signals into a single systemic risk reading, visualized as a four-tier thermometer:
| Thermometer Tier | SRI Range (0-3+ scale) | Meaning |
|---|---|---|
| 🟢 Normal | below 0.5 | Systemic risk within normal bounds |
| 🟡 Watch | 0.5 - 1.0 | Elevated risk in specific sectors |
| 🟠 Alert | 1.0 - 1.8 | Broad-based risk accumulation |
| 🔴 Danger | 1.8 and above | Systemic stress imminent |
The SRI uses a continuous 0-3+ scale — never a percentage system. Tier definitions and mandated actions are single-sourced in dev/engine/systemic-warning-framework.md §3. The SRI calculation engine (src/sri_calculator.py) implements the aggregation algorithm, and the thermometer level feeds into the L0 signal card and triggers escalation across the four-stage pipeline.
The fourth coded engine (src/outlook_engine.py) provides:
- 12-24 month rating outlook assessment with directional probability
- 90-day watchlist with automated trigger conditions
- Rating migration matrix with historical transition probabilities
- Continuous monitoring triggers that propagate through the work-path registry
Every credit analysis flows through a four-stage chained pipeline, with path_id as the join key across stages:
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ ① Intake │ -> │ ② Analysis│ -> │ ③ Report │ -> │ ④ QA │
│ (Router) │ │ (Engine) │ │ (Builder)│ │ (Verifier)│
└──────────┘ └──────────┘ └──────────┘ └──────────┘
| Stage | Name | Artifact | Hosting Skill | Status |
|---|---|---|---|---|
| S1 | Intake | Path Sheet | credit-analysis-router |
✅ Delivered |
| S2 | Analysis | Analysis Artifact | fixed-income-credit-analysis |
✅ Delivered |
| S3 | Report | Delivery Note | credit-report-builder |
✅ Delivered |
| S4 | QA | QA Verdict | credit-qa-verifier |
✅ Delivered |
S1 — Intake (Router) : The credit-analysis-router skill uses a four-question routing mechanism to classify vague user requests ("analyze this company", "what analysis should I run") into a concrete Path Sheet. The sheet carries a path_id, engine reading order, template selection, and quality gate specifications — all derived from the single source of truth in dev/engine/work-path-registry.md.
S2 — Analysis : The fixed-income-credit-analysis skill executes the analysis per the path sheet's engine reading order. For four wired paths, the orchestrator (src/pipeline.py) invokes the corresponding coded engine directly:
- WP-RO-01 ->
src/concentration_scorer.py(five-dimension concentration) - WP-RO-02 ->
src/contagion_engine.py(contagion matrix) - WP-RO-03 ->
src/sri_calculator.py(systemic risk index) - WP-X-05 ->
src/outlook_engine.py(outlook monitoring)
All non-wired paths are LLM-orchestrated per engine documentation.
S3 — Report : The credit-report-builder skill assembles the completed analysis into a deliverable HTML report. Template selection (Type 1-18) follows the path sheet specification and maps to the L0/L1/L2 three-tier output system:
- L0 (Signal Card) — 5-second summary: rating, outlook, key signals of the day
- L1 (Snapshot) — One-page dashboard with radar charts and key anomaly list
- L2 (Deep Dive) — Full analytical report with pyramid layering and cross-validation
S4 — QA : The credit-qa-verifier skill performs a pre-delivery quality gate review, enforcing signal-density rules, one-shot-veto ceiling compliance, Mode B guardrails, and single-source-of-truth integrity — plus process compliance: correct template usage, citation of engine documents for every number, registered dimension vocabulary, and chain completeness. This is the terminal stage in the four-stage chain — no report is delivered without passing QA.
Anti-drift constraint layer: to keep agents on the methodology without explicit instructions, every entry point carries a Non-Negotiables block (AGENTS.md + all four SKILL.md): no analysis without a Path Sheet, no numbers without engine citations, no reports outside the fixed templates, no delivery without a QA verdict, no invented dimensions. Each active work path additionally ships an execution contract in dev/engine/path-playbooks/ (procedure with document section pointers, dimension vocabulary, output shape, quality gates, drift blacklist), and derived tables in the engine documents are machine-generated with drift-gate checks in CI.
Executable Orchestrator: src/pipeline.py drives the entire four-stage chain in code. It reads stage definitions from dev/engine/pipeline-contract.md (never hardcodes stage names), validates path sheets using src/path_sheet.py, and invokes coded engines only for explicitly wired paths. The single source of truth for all four artifacts (path sheet, analysis artifact, delivery note, QA verdict) and their chaining edges is dev/engine/pipeline-contract.md.
The engine classifies all industries into six analytical paradigms, each with distinct weight templates, scoring priorities, and factor emphasis:
| Paradigm | Code | Core Industries | Key Differentiator |
|---|---|---|---|
| Cyclical | P1 | Energy, Chemicals, Metals & Mining, Construction Materials, Capital Goods, Commercial Services, Automobiles, Consumer Durables, Retail | Commodity/freight/spending cycles determine demand and margins |
| Defensive | P2 | Consumer Staples, Healthcare Equipment | Inelastic demand; brand moats and pricing power stabilize margins |
| Growth | P3 | Technology Hardware (Semis), Software & Services, Biotech & Pharma | R&D intensity and IP drive revenue growth; pre-revenue valuation is standard |
| Regulated Utility | P4 | Transportation, Utilities, Telecommunications | License/concession revenue; NOI/DSCR are the core metrics; infrastructure financing |
| Financial | P5 | Financials (Banks/Insurance) | Capital adequacy, asset quality, and funding structure are the core risk drivers |
| Sovereign-Linked | P6 | Sovereigns & GSEs | Fiscal capacity and institutional strength determine credit |
The engine defines 16 work paths mapped to international buy-side roles, each specifying an engine sequence, report template, and quality gate requirements.
Credit Selector (2 paths)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-CS-01 | Single-Issuer Rating | ✅ Active | Rating + Signals + Completeness Report |
| WP-CS-02 | LGD + External Support Add-On | ✅ Active | LGD Tier + Recovery Rate + Support Adjustment |
Portfolio Manager (2 paths)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-PM-01 | Investment Dashboard | ✅ Active | Four-Dimension Score + Investment Recommendation |
| WP-PM-02 | Comparative Analysis | ✅ Active | Comparison Score + Differentiation Conclusion |
Risk Officer (4 paths)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-RO-01 | Concentration Assessment | ✅ Active | Five-Dimension Concentration Score + Adjustment Recommendations |
| WP-RO-02 | Cross-Industry Contagion | ✅ Active | Contagion Path Map + Adjustment Recommendations |
| WP-RO-03 | Systemic Risk Reading | ✅ Active | SRI Reading + Thermometer Tier |
| WP-RO-04 | Portfolio Stress Test | ✅ Active | Stress Scenario Loss + Threshold Jump Results |
Trader (1 path)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-TR-01 | Market Watch Signal Card | ✅ Active | L0 Signal Card + Thermometer Reading |
Advisor (1 path)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-AD-01 | Origination Assessment | ✅ Active | Underwriting Feasibility + Pricing Range |
Individual Investor (1 path)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-II-01 | Decision Support | ✅ Active | Financing Channel Comparison + Timing Recommendation |
Meta / Special-Purpose (5 paths)
| ID | Path | Status | Output |
|---|---|---|---|
| WP-X-01 | Black Swan Backtest Validation | ✅ Active | Validation Conclusion + Framework Improvements |
| WP-X-02 | Multi-Role Parallel Assessment | ✅ Active | Multi-Role Score Matrix + Consensus/Divergence Report |
| WP-X-03 | Industry Framework Builder | ✅ Active | Industry Pyramid + D1-D10 Scores |
| WP-X-04 | ESG/Governance Risk Scan | ✅ Active | ESG Risk Scan + Governance Red-Flag List |
| WP-X-05 | Outlook & Continuous Monitoring | ✅ Active | Rating Outlook + Watchlist |
Status summary: 16 active, 0 partial, 0 planned.
Each work path maps to one or more HTML report templates:
| Template | Type | Used By |
|---|---|---|
| Type 1 | Single-Issuer Deep Dive | WP-CS-01 |
| Type 2 | Comparative Analysis | WP-PM-02 |
| Type 3 | Backtest Validation | WP-X-01 |
| Type 4 | Multi-Role Matrix | WP-X-02 |
| Type 5 | PM Dashboard | WP-PM-01 |
| Type 6 | Rating Summary Card | WP-CS-01 |
| Type 7 | Industry Framework | WP-X-03 |
| Type 8 | LGD Assessment | WP-CS-02 |
| Type 9 | External Support | WP-CS-02 |
| Type 10 | ESG/Governance Scan | WP-X-04 |
| Type 11 | Stress Test | WP-RO-04 |
| Type 13 | Contagion Map | WP-RO-02 |
| Type 14 | Concentration Dashboard | WP-RO-01 |
| Type 15 | SRI Thermometer | WP-RO-03 |
| Type 16 | Origination Feasibility | WP-AD-01 |
| Type 17 | Financing Channel Comparison | WP-II-01 |
| Type 18 | Outlook Monitoring | WP-X-05 |
Key premise: the skills are NOT self-contained — at runtime they read engine/ and templates/ from the package root (single source of truth, never copied). Under a Claude Code plugin install the harness resolves these via ${CLAUDE_PLUGIN_ROOT}; for every other client, open the package root as your project and the paths resolve with zero copying.
/plugin marketplace add tywinlu1988/Credence-Global
/plugin install credence@credence-marketplace
Installs the four-stage skill chain into Claude Code from the plugin-dist branch (the installable package root, kept in sync with each release by scripts/publish_plugin.py). Engine and template references inside the skills resolve via ${CLAUDE_PLUGIN_ROOT} automatically.
npx github:tywinlu1988/credence-globalDownloads the latest release zip from GitHub Releases, verifies its SHA-256 checksum, and unpacks it into ./credence/; open that folder with your agent CLI. Pin a specific version with --tag vX.Y.Z.
Download the latest vX.Y.Z-release.zip from the Releases page, verify it against the attached vX.Y.Z-release.zip.sha256, unzip, and open the package root as a project.
git clone git@github.com:tywinlu1988/Credence-Global.git
cd credence-global
pip install -e .python -m pytest tests/ -q # full regression suite
python scripts/consistency_check.py # Cross-document consistency validation- Open the package root in your agent CLI
- Start a conversation: "Analyze company XYZ in the semiconductor industry"
- The
credit-analysis-routerskill will route your request to a work path - Execution follows the four-stage pipeline: intake -> analysis -> report -> QA
- A Type-1 deep-dive HTML report or Type-6 rating summary is produced
For detailed engine documentation, see dev/engine/engine-overview.md.
Credence delivers its methodology as Agent Skills (SKILL.md) that any AI coding agent can load. Compatibility varies by client:
| Agent CLI | Discovery Mechanism | Setup Complexity | Notes |
|---|---|---|---|
| Claude Code | Plugin install (marketplace) or auto-discovers dev/.claude/skills/ |
None | Full support; plugin install recommended, automatic skill loading |
| Codex | Reads AGENTS.md + manual SKILL.md load |
Low | See docs/adapters/codex.md for deep-dive setup |
| Cursor | Reads AGENTS.md + manual SKILL.md load |
Low | Manual skill invocation |
| Gemini | Reads AGENTS.md + manual SKILL.md load |
Medium | May require prompt engineering for skill context |
| OpenCode | Reads AGENTS.md + manual SKILL.md load |
Low | Compatible with standard agent workflows |
Universal posture: read AGENTS.md first, then load the relevant SKILL.md for the task at hand. The AGENTS.md file at the repository root serves as the cross-CLI entry point.
credence-global/
|
|-- dev/ # Methodology & skill source
| |-- engine/ # 30 core methodology documents
| | |-- engine-overview.md # Architecture overview & document navigation
| | |-- industry-framework.md # Industry classification, 10-dimension scoring, 6 paradigms
| | |-- mosaic-engine.md # Signal extraction, puzzle assembly, completeness
| | |-- dual-track-methodology.md # Track A+B cross-validation, rating mapping, worked examples
| | |-- multi-stakeholder.md # 6 buy-side roles, cross-role matrix
| | |-- advisor-origination-framework.md # Issuance window, investor matching, comps pricing
| | |-- financing-channel-framework.md # Bond vs loan vs private credit, timing
| | |-- trader-framework.md # Execution dimensions, thermometer overlay, decision matrix
| | |-- financial-deep-dive.md # 3-statement linkage, working capital, FCF
| | |-- lgd-recovery-framework.md # LGD 5-tier, collateral valuation, recovery path
| | |-- external-support-framework.md # Government/group/strategic support
| | |-- outlook-monitoring-framework.md # 12-24m outlook, watchlist, migration matrix
| | |-- governance-fraud-risk.md # 20+ fraud signals, default evasion detection
| | |-- esg-framework.md # ESG + governance/fraud detection
| | |-- financial-bond-framework.md # FI bond analysis framework
| | |-- holding-company-framework.md
| | |-- output-layered-framework.md # L0 signal card, L1 snapshot, L2 deep dive
| | |-- contagion-theory.md # 4 contagion types, 7 transmission paths
| | |-- contagion-matrix.md # 19x19 industry contagion matrix
| | |-- concentration-framework.md # 5-dimension concentration analysis
| | |-- systemic-warning-framework.md # SRI signal aggregation, 4-tier thermometer
| | |-- validation-methodology.md # Black swan backtesting, dual-point validation
| | |-- paradigm-brand-channel.md # Brand/channel application note (P2 Defensive)
| | |-- paradigm-network-traffic.md # Network/throughput secondary-attribute application note
| | |-- dimension-registry.md # Addressable index of 6 paradigms + M0-M5 roles
| | |-- work-path-registry.md # 16 work paths, routing, pipeline integration
| | |-- pipeline-contract.md # 4-stage pipeline I/O contracts, chain edges
| | |-- path-playbooks/ # Per-path execution contracts (16 active-path playbooks)
| | |-- appendix/ # Per-doc reference material (moved sections, on-demand; not shipped)
| | |-- reference/ # Legacy on-demand library (qualitative/quantitative/non-credit; not shipped)
| |
| |-- templates/ # Report template source of truth (18 HTML files)
| | |-- template-base.css # Shared style base
| | |-- template-type{1..18}.html # Type 1-15 report templates
| | |-- template-type18.html # Type 18 outlook monitoring template
| | |-- index.yaml # Machine-generated template manifest (build_template_index.py)
| |
| |-- design/ # Report design system
| |-- data/ # Data architecture & pipeline specs
| |-- product/ # Product vision, commercial model, GTM strategy
| |-- .claude/skills/ # 4-stage skill chain
| |-- credit-analysis-router/ # Intake: 4-question routing -> Work Path Sheet
| |-- fixed-income-credit-analysis/ # Analysis: per-path execution
| |-- credit-report-builder/ # Report: HTML assembly from templates
| |-- credit-qa-verifier/ # QA: pre-delivery quality gate
|
|-- src/ # Executable orchestrator & coded engines
| |-- pipeline.py # 4-stage chain orchestrator
| |-- path_sheet.py # Path sheet validation & registry parsing
| |-- sri_calculator.py # Systemic Risk Index calculation engine
| |-- concentration_scorer.py # 5-dimension concentration scoring engine
| |-- contagion_engine.py # Contagion matrix & escalation engine
| |-- outlook_engine.py # Outlook & monitoring assessment engine
|
|-- tests/ # Regression test suite (pytest)
|-- scripts/ # Build & validation tools
| |-- build_dist.py # dev/ -> release-package assembler (zip + sha256)
| |-- consistency_check.py # Cross-document consistency validation
| |-- promote.py # Version promotion utility
| |-- publish_plugin.py # Publishes dist package to the plugin-dist branch
| |-- build_contagion_derived.py # Regenerates machine-derived contagion tables
| |-- build_template_index.py # Regenerates templates/index.yaml
| |-- smoke_install.sh # End-to-end installer smoke test
|
|-- bin/
| |-- install.js # npx installer (download + SHA-256 verify + extract)
|-- .claude-plugin/
| |-- marketplace.json # /plugin marketplace add entry point
|-- .github/workflows/
| |-- ci.yml # Gates: Ubuntu & Windows x Python 3.11/3.12
|-- docs/ # Cross-CLI adapters & version management
|-- validation/ # Capability evidence (2 public methodology reference reports)
|-- version/ # Locally built release zips (gitignored; shipped via GitHub Releases)
|-- CHANGELOG.md # Release history (Keep a Changelog)
|-- AGENTS.md # Cross-CLI universal entry point
|-- DEVELOPMENT.md # Development guide
|-- LICENSE # MIT License
|-- pyproject.toml # Python project configuration
|-- package.json # npm registry metadata
Credence addresses three systematic failures in traditional financial analysis: (1) the heaviest credit factors (policy, IP, lease quality) are never on the balance sheet, (2) external ratings lag real deterioration by 17+ months on average, and (3) single-perspective analysis misses structural weaknesses. Credence uses a layered pyramid framework, dual-track cross-validation, mosaic data assembly, and multi-stakeholder perspective to surface what traditional analysis misses.
No. Credence operates on zero-cost public data sources — SEC EDGAR, FRED, central bank portals, TRACE, industry association reports, and web search. The POC phase is intentionally data-source constrained to prove that effective credit analysis is possible with public data alone.
The engine's internal rating scale maps to S&P (AAA through D), Moody's (Aaa through C), and Fitch (AAA through D). See the rating mapping table in dev/engine/dual-track-methodology.md for the full alignment.
Yes. Credence is CLI-agnostic. It works with Claude Code (full auto-discovery), Codex, Cursor, Gemini, and OpenCode. The AGENTS.md file at the repository root serves as the universal entry point.
Paths are organized by buy-side role: Credit Selector (2 paths), Portfolio Manager (2), Risk Officer (4), Trader (1), Advisor (1), Individual Investor (1), and Meta/Special-Purpose (5). Each path specifies an engine sequence, report template, and quality gates. All 16 paths are fully active (0 partial, 0 planned).
Cyclical (P1), Defensive (P2), Growth (P3), Regulated Utility (P4), Financial (P5), and Sovereign-Linked (P6). Each paradigm determines the weight template and scoring priorities for industry analysis.
It is the topmost aggregation layer that goes beyond single-issuer analysis to detect systemic patterns: cross-industry contagion (19x19 matrix), portfolio concentration (5 dimensions), and the Systemic Risk Index (SRI) with a four-tier thermometer. Together, these modules answer "what is happening across the entire portfolio/market" rather than "is this single issuer risky."
The pytest regression suite covers the coded engines, the pipeline orchestrator, the document registries, the consistency checker, and the release-package builder. CI runs it on Python 3.11 and 3.12 via GitHub Actions. Run locally with python -m pytest tests/ -q. Cross-document consistency is validated separately with python scripts/consistency_check.py.
IFRS (International Financial Reporting Standards) and US GAAP (Generally Accepted Accounting Principles). The engine auto-detects the reporting standard from issuer filings and adjusts for key differences.
Open the package root in your CLI, then say "analyze company [X] in the [Y] industry." The credit-analysis-router skill handles the routing. For direct skill usage, load the relevant SKILL.md per the AGENTS.md instructions.
Four work paths have dedicated Python implementations (coded engines): concentration scoring, contagion matrix, SRI calculation, and outlook monitoring. These are invoked directly by the orchestrator (src/pipeline.py) when the path ID matches. All other paths are orchestrated by the LLM using the engine documentation as reference — no Python code duplicates the methodology.
Yes. Credence is released under the MIT License, which permits commercial and non-commercial use free of charge. See the LICENSE file for full terms.
This repository is released under the MIT License — free for commercial and non-commercial use, modification, and redistribution, subject to preserving the copyright notice.
Key terms:
- Free for commercial and non-commercial use, modification, and redistribution (MIT)
- The engine's output is a methodology demonstration and research artifact — it is not investment advice
- No warranty is provided; the software is offered "as is"
See the full LICENSE file for complete terms.
Methodology validation: The engine's methodology has been exercised against five documented historical default/distress cases — Lehman Brothers, Wirecard, Valeant, Credit Suisse, and the Greece sovereign restructuring (see dev/engine/validation-methodology.md §6). Two public methodology reference reports ship in the validation/ directory; the full test archive is maintained privately and available on request.
Credence · Fixed-Income Credit Analysis Engine · v0.1.0
Built for rigorous, transparent, and reproducible credit analysis.