run-underwriter

Run the mortgage underwriter CLI to analyze loan documents. Use when testing document analysis, debugging underwriter output, or processing loan files. Covers setup, execution, and result interpretation.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a specialized interface to execute and debug a mortgage underwriter CLI tool for automated document analysis. It streamlines the evaluation of loan files—including W2s, paystubs, and bank statements—by providing structured insights into approval status, risk assessment, and compliance with financial guidelines, making it an essential tool for fintech developers and mortgage processors.

Use Cases

  • Automated Mortgage Underwriting: Rapidly analyze loan document directories to determine eligibility based on Fannie Mae or custom guidelines.
  • Fintech Development & Debugging: Test document analysis logic and debug underwriter outputs during the development of financial software.
  • Risk & Compliance Auditing: Identify financial risks, missing documentation, and severity levels in loan applications with high-confidence scoring.
  • Batch Document Processing: Use CLI commands to programmatically process large volumes of financial files and export results in JSON for database integration.
namerun-underwriter
descriptionRun the mortgage underwriter CLI to analyze loan documents. Use when testing document analysis, debugging underwriter output, or processing loan files. Covers setup, execution, and result interpretation.

Run Underwriter CLI

Purpose

Execute and debug the mortgage underwriter tool for document analysis.

Prerequisites

1. Set API Key

export GEMINI_API_KEY="your-gemini-api-key"

2. Build the Binary

make build

3. Fetch Guidelines (if needed)

make fetch-guidelines

Usage

Analyze a Directory of Documents

./bin/underwriter -docs /path/to/documents

Analyze Specific Files

./bin/underwriter -files w2.pdf,paystub.pdf,bank_statement.pdf

JSON Output (for programmatic use)

./bin/underwriter -docs /path/to/documents -json

Custom Guidelines Path

./bin/underwriter -docs /path/to/documents -guidelines /custom/path

All CLI Flags

-docs string       Directory containing documents to analyze
-files string      Comma-separated list of document files
-guidelines string Path to Fannie Mae guidelines (default "configs/guidelines")
-app-id string     Application ID (default "test-001")
-json              Output results as JSON

Test with Sample Documents

# Generate test documents first (if needed)
cd test_loan_files && python3 generate_loan_docs.py && cd ..

# Run on test loan file
./bin/underwriter -docs test_loan_files/loan_file_1_LN-2024-001847

Understanding Output

Analysis Result Structure

  • status: approved | conditional | denied | needs_review | incomplete
  • confidence: 0.0 to 1.0 score
  • findings: Observations with category, description, evidence, document ID
  • risks: Identified risks with severity (low/medium/high/critical) and mitigation
  • missing_documents: Required documents not provided
  • summary: Brief description of analysis

Status Meanings

Status Meaning
approved Meets all guidelines
conditional Approved with conditions
denied Does not meet guidelines
needs_review Manual review required
incomplete Missing required documents

Troubleshooting

"GEMINI_API_KEY not set"

export GEMINI_API_KEY="your-key"

"No documents found"

  • Check file paths exist
  • Supported extensions: .pdf, .png, .jpg, .jpeg

Document Type Misdetection

Files are typed by filename patterns:

  • *w2* or *w-2* -> W2
  • *paystub* or *pay* -> Paystub
  • *bank* -> Bank Statement
  • *tax* or *1040* -> Tax Return
  • *1099* -> 1099

Guidelines Not Loading

make fetch-guidelines
ls configs/guidelines/
  • cmd/underwriter/main.go - CLI implementation
  • internal/agent/income/income.go - Income agent logic
  • internal/model/analysis.go - Result structures