name	caty-lessons-learned
description	North star principles from CATY equity research project - professional HTML standards, external source citations, audit-grade documentation, and target profile frameworks that work for Big 4 audiences
version	1.0.0
author	Nirvan Chitnis (PWC Audit Staff)
date	Sat Oct 25 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
reference_project	https://github.com/nirvanchitnis-cmyk/caty-equity-research-live

CATY Lessons Learned: North Star Principles

Purpose

This skill captures proven design patterns, documentation standards, and quality principles from the CATY (Cathay General Bancorp) equity research project. CATY serves as the target profile framework - a template that worked so well it became the standard for all future company analysis.

Use this skill when:

Building HTML pages for professional/Big 4 audiences
Documenting financial analysis or audit intelligence
Creating target company profiles
Designing data visualizations for partners
Ensuring audit-grade provenance and citations

Core Principles

1. Professional Visual Standards (No Clanker Slop)

CATY Standard: Off-white backgrounds, clean typography, subtle colors

What to DO:

✅ Backgrounds: Off-white (#F9F9F9, #FAFAFA), light grays (#F5F5F5)
✅ Text colors: Dark gray (#333, #2C3E50), not pure black
✅ Accent colors: Professional blues (#3498DB), greens (#27AE60), muted oranges (#E67E22)
✅ Typography: System fonts (-apple-system, BlinkMacSystemFont), Inter, Roboto
✅ Spacing: Generous padding (2-3rem between sections)
✅ Borders: Subtle (1px solid #DDD), rounded corners (border-radius: 8px)

What to AVOID:

❌ Purple gradients (screams "AI-generated slop")
❌ Neon colors (unprofessional)
❌ Pure white backgrounds (#FFF too stark)
❌ Comic Sans or decorative fonts (never)
❌ Excessive animations (distracting)
❌ Stock photos of people in suits pointing at screens (cringe)

CATY Example:

body {
  background-color: #F9F9F9;
  color: #333;
  font-family: -apple-system, BlinkMacSystemFont, "Inter", sans-serif;
  line-height: 1.6;
  padding: 2rem;
}

.section {
  background: white;
  border: 1px solid #DDD;
  border-radius: 8px;
  padding: 2rem;
  margin-bottom: 2rem;
  box-shadow: 0 2px 4px rgba(0,0,0,0.05);
}

h1 {
  color: #2C3E50;
  font-weight: 600;
  margin-bottom: 1.5rem;
}

.highlight {
  background-color: #FFF3CD; /* Subtle yellow, not neon */
  padding: 0.2rem 0.5rem;
  border-radius: 4px;
}

2. External Source Citations (Audit-Grade Provenance)

CATY Standard: Every claim has a traceable source with URL + date

Citation Format:

<p>
  CATY's total assets were $26.1B as of December 31, 2024
  <sup><a href="https://www.sec.gov/..." target="_blank">[1]</a></sup>.
</p>

<!-- Footnotes section -->
<div class="sources">
  <h3>Sources</h3>
  <ol>
    <li>
      <a href="https://www.sec.gov/Archives/edgar/data/..." target="_blank">
        SEC 10-K Filing, Cathay General Bancorp, December 31, 2024
      </a>
    </li>
  </ol>
</div>

Why This Matters:

✅ Audit trail: Partners can verify every fact
✅ Regulatory compliance: SEC/PCAOB require source documentation
✅ Credibility: Shows rigor, not just ChatGPT output
✅ Reproducibility: Anyone can re-pull the same data

CATY Practice:

Every financial metric has SEC EDGAR URL
Every industry statistic has FDIC/HMDA/regulatory source
Every market comparison has peer company 10-K citation
SHA-256 checksums on all downloaded files (ground-truth extends this)

3. Target Profile Framework (Reusable Template)

CATY Innovation: Built a company profile structure so good it works for ANY company

Sections (in order):

Executive Summary (1-page, C-suite friendly)
Business Model (revenue streams, customer segments, competitive position)
Financial Performance (5-year trends, peer benchmarks, profitability analysis)
Risk Factors (regulatory, market, operational, credit risks)
Critical Audit Matters (if public company, extracted from 10-K)
Valuation (DCF, comparables, sensitivity analysis)
Investment Thesis (bull case, bear case, recommendation)
Appendices (detailed financials, methodology, sources)

Why This Works:

✅ Big 4 teams recognize this structure (mirrors audit planning memos)
✅ Partners can skim or deep-dive (executive summary vs appendices)
✅ Modular: Drop sections not relevant to use case
✅ Scalable: Apply to 1 company or 1,000

Ground-Truth Application:

Use this structure for each extracted company
Generate HTML pages automatically (like CATY site)
Partners navigate company profiles, not JSON files

4. Data Visualization Best Practices

CATY Standard: Charts are clean, readable, and tell a story

Chart Design Principles:

✅ Simple color palette: Max 4-5 colors per chart
✅ Clear labels: Axis titles, legends, data point values
✅ Trends over time: Line charts for 5-year revenue/earnings
✅ Peer comparisons: Grouped bar charts for benchmarking
✅ Responsive: Charts scale on mobile
✅ Accessible: High contrast, no red/green only (colorblind friendly)

What to AVOID:

❌ 3D charts (distort data, look dated)
❌ Pie charts with >5 slices (unreadable)
❌ Default Excel colors (ugly)
❌ Missing axis labels (confusing)
❌ Overfitted trendlines (misleading)

CATY Example (using Chart.js):

// 5-Year Revenue Trend
const ctx = document.getElementById('revenueChart').getContext('2d');
new Chart(ctx, {
  type: 'line',
  data: {
    labels: ['2020', '2021', '2022', '2023', '2024'],
    datasets: [{
      label: 'Revenue ($M)',
      data: [1200, 1350, 1500, 1680, 1820],
      borderColor: '#3498DB',
      backgroundColor: 'rgba(52, 152, 219, 0.1)',
      tension: 0.1
    }]
  },
  options: {
    responsive: true,
    plugins: {
      title: {
        display: true,
        text: 'CATY Revenue Growth (2020-2024)',
        font: { size: 16, weight: '600' }
      }
    },
    scales: {
      y: {
        beginAtZero: true,
        ticks: {
          callback: (value) => '$' + value + 'M'
        }
      }
    }
  }
});

5. Interactive Elements (User Experience)

CATY Standard: Pages are navigable, searchable, and responsive

Interactive Features:

✅ Table of contents (sticky sidebar, jump to section)
✅ Search functionality (Ctrl+F works, or custom search)
✅ Collapsible sections (expand/collapse for long content)
✅ Hover tooltips (definitions for jargon)
✅ Mobile menu (hamburger icon, responsive nav)
✅ Print-friendly (CSS @media print rules)

CATY Example (Collapsible Section):

<details>
  <summary><h3>Risk Factors (click to expand)</h3></summary>
  <div class="risk-content">
    <p>Interest rate risk: CATY's net interest margin is sensitive to...</p>
    <!-- Full risk factors content -->
  </div>
</details>

<style>
summary {
  cursor: pointer;
  padding: 1rem;
  background: #F9F9F9;
  border-radius: 4px;
}
summary:hover {
  background: #F0F0F0;
}
</style>

6. Documentation Philosophy

CATY Mindset: Document failures with more rigor than successes

What to Document:

✅ Assumptions: "We assume CATY's loan loss reserve is adequate..."
✅ Limitations: "This analysis does not include off-balance-sheet items..."
✅ Data gaps: "HMDA data not available for 2024 yet"
✅ Methodology changes: "Switched from DCF to P/E multiples because..."
✅ Failure modes: "CAM extraction returned 0 results - regex issue documented in..."
✅ Lessons learned: "Next time, validate balance sheet reconciliation earlier"

Why This Matters:

✅ Audit teams trust transparent analysis (vs black box)
✅ Reproducibility: Others can replicate and improve
✅ Continuous improvement: Learn from mistakes

Ground-Truth Application:

MILESTONE_01_PFSI_SUCCESS.md documents bug fix (XBRL period consistency)
HANDOFF.md lists known limitations (CAM parser low yield, validation missing from batch)
open_items/ directory tracks incomplete features

7. Mobile Responsiveness (Non-Negotiable)

CATY Standard: Partners review on iPad/iPhone, not just desktop

Responsive Design Checklist:

✅ Viewport meta tag: <meta name="viewport" content="width=device-width, initial-scale=1.0">
✅ Breakpoints: 768px (tablet), 480px (mobile)
✅ Flexible grids: CSS Grid or Flexbox
✅ Readable font sizes: Min 16px on mobile
✅ Touch-friendly buttons: Min 44px × 44px
✅ No horizontal scroll: Content fits screen width

CATY Example:

/* Desktop */
.container {
  max-width: 1200px;
  margin: 0 auto;
  padding: 2rem;
}

/* Tablet */
@media (max-width: 768px) {
  .container {
    padding: 1rem;
  }

  h1 {
    font-size: 2rem; /* Smaller on tablet */
  }
}

/* Mobile */
@media (max-width: 480px) {
  .container {
    padding: 0.5rem;
  }

  h1 {
    font-size: 1.5rem;
  }

  .stats {
    flex-direction: column; /* Stack stats vertically */
  }
}

CATY-to-Ground-Truth Translation

What Ground-Truth Inherits from CATY

Professional HTML standards → ARCHITECTURE_DEMO.html uses off-white, clean typography
External citations → Every fact has SEC URL + SHA-256
Target profile framework → Each extracted company gets standardized structure
Data visualization → Charts for CAM trends, ICFR failure rates, sector benchmarks
Interactive elements → Collapsible sections, search, mobile-friendly
Transparent documentation → MILESTONE_01 documents bug fix, not just success
Mobile responsiveness → Demo page works on all devices

What Ground-Truth Extends Beyond CATY

SHA-256 provenance → CATY had URLs, ground-truth adds cryptographic verification
RAG integration → CATY was static HTML, ground-truth adds natural language queries
Skills architecture → CATY was manual, ground-truth packages expertise as reusable skills
Sector routing → CATY was one company, ground-truth handles banking/mortgage/tech with intelligent dispatch
Validation framework → CATY had manual checks, ground-truth has automated gates (balance sheet, EPS, data quality)

Anti-Patterns (What NOT to Do)

1. Purple Gradient Syndrome

Bad: background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); Why: Screams "I used a template from CodePen" (not professional) CATY Fix: Solid off-white or subtle gray gradients only

2. Unsourced Claims

Bad: "CATY is the largest bank in California" Why: No citation = no credibility CATY Fix: "CATY is the 12th largest bank in California by deposits^[1]" + FDIC source

3. Wall of Text

Bad: 10-paragraph executive summary with no headings Why: Partners won't read it CATY Fix: Use bullet points, subheadings, bold key takeaways

4. Broken Links

Bad: Link to 10-K that returns 404 Why: Destroys trust instantly CATY Fix: Verify all links before publishing, use SEC EDGAR permanent URLs

5. "Trust Me Bro" Methodology

Bad: "We valued CATY using DCF" (no details) Why: Not reproducible, not auditable CATY Fix: Full methodology section with assumptions, formulas, sensitivity analysis

Quick Reference Checklist

When building professional HTML/docs, ensure:

Visual Design:

Off-white background (#F9F9F9 or similar)
System fonts or Inter/Roboto
No purple gradients or neon colors
Generous spacing (2rem+ between sections)
Subtle borders and shadows

Citations:

Every fact has source URL
Sources section at bottom with numbered footnotes
External links open in new tab (target="_blank")
Dates included (e.g., "as of December 31, 2024")

Structure:

Executive summary first (1-page, skimmable)
Clear section headings (H1, H2, H3 hierarchy)
Table of contents for long documents
Appendices for detailed data/methodology

Interactivity:

Mobile-responsive (test on iPhone/iPad)
Collapsible sections for long content
Search functionality (or good Ctrl+F support)
Print-friendly CSS

Documentation:

Assumptions stated upfront
Limitations acknowledged
Methodology explained
Failure modes documented

Examples from CATY Project

Example 1: Financial Performance Section

<section id="financials">
  <h2>Financial Performance (2020-2024)</h2>

  <div class="metric-cards">
    <div class="card">
      <h3>Total Assets</h3>
      <p class="big-number">$26.1B</p>
      <p class="change positive">+12.3% YoY</p>
      <p class="source">
        <a href="https://www.sec.gov/..." target="_blank">Source: 10-K</a>
      </p>
    </div>

    <div class="card">
      <h3>Net Income</h3>
      <p class="big-number">$412M</p>
      <p class="change positive">+8.7% YoY</p>
      <p class="source">
        <a href="https://www.sec.gov/..." target="_blank">Source: 10-K</a>
      </p>
    </div>
  </div>

  <canvas id="revenueChart"></canvas>

  <details>
    <summary><h3>Methodology</h3></summary>
    <p>All financial data sourced from SEC EDGAR 10-K filings. YoY calculations based on fiscal year-end figures. Peer comparisons use median of 5 largest California banks by assets.</p>
  </details>
</section>

Example 2: Risk Factors Extraction

<section id="risks">
  <h2>Risk Factors</h2>

  <div class="risk-category">
    <h3>Credit Risk</h3>
    <p>
      CATY's loan portfolio is concentrated in commercial real estate (42% of total loans), exposing the bank to downturns in the California property market
      <sup><a href="https://www.sec.gov/..." target="_blank">[1]</a></sup>.
    </p>
    <p><strong>Mitigation:</strong> Diversified geographic footprint across Southern California, conservative underwriting standards.</p>
  </div>

  <div class="risk-category">
    <h3>Regulatory Risk</h3>
    <p>
      As a $20B+ bank, CATY is subject to enhanced prudential standards under Dodd-Frank
      <sup><a href="..." target="_blank">[2]</a></sup>.
    </p>
    <p><strong>Impact:</strong> Higher capital requirements, stress testing obligations, increased compliance costs.</p>
  </div>
</section>

Reference Files

CATY Project (North Star):

GitHub: https://github.com/nirvanchitnis-cmyk/caty-equity-research-live
Live site: (if deployed to GitHub Pages)
Key files: index.html, CATY_05_nim_decomposition.html, CATY_16_coe_triangulation.html

Ground-Truth Application:

ARCHITECTURE_DEMO.html — Uses CATY visual standards
README.md — Uses CATY documentation philosophy
MILESTONE_01_PFSI_SUCCESS.md — Documents failures (XBRL bug) with same rigor as successes

Notes

CATY Timeline: Built October 18, 2025 (1 week before ground-truth)

CATY Achievement: Established the canonical target profile framework — so good that it became the template for all future company analysis

CATY Legacy: Proved the 3-agent workflow (Claude ideates, Nirvan directs, Codex executes) on a hard bank analysis

Ground-Truth Evolution: Takes CATY's proven design patterns and adds:

RAG natural language queries
Automated extraction (vs manual research)
SHA-256 provenance chain
Skills-based domain expertise packaging

Philosophy: CATY is the north star because it worked — Big 4 teams understood it, partners could navigate it, and the analysis held up to scrutiny. Ground-truth inherits this DNA.

When to Apply This Skill

Use CATY principles when:

Building HTML pages for PWC/Big 4 audiences
Documenting financial analysis or audit findings
Creating company profiles or target assessments
Designing data dashboards for partners
Writing reports that will be reviewed by regulators (SEC, PCAOB)

Don't force CATY patterns when:

Internal dev docs (Markdown is fine)
Quick prototypes (perfection not needed)
Non-financial content (different audience expectations)

Remember: CATY succeeded because it respected the audience (Big 4 partners) and delivered what they needed (professional, sourced, navigable analysis). Ground-truth does the same for audit intelligence.

caty-lessons-learned

Install Skill

SKILL.md

CATY Lessons Learned: North Star Principles

Purpose

Core Principles

1. Professional Visual Standards (No Clanker Slop)

2. External Source Citations (Audit-Grade Provenance)

3. Target Profile Framework (Reusable Template)

4. Data Visualization Best Practices

5. Interactive Elements (User Experience)

6. Documentation Philosophy

7. Mobile Responsiveness (Non-Negotiable)

CATY-to-Ground-Truth Translation

What Ground-Truth Inherits from CATY

What Ground-Truth Extends Beyond CATY

Anti-Patterns (What NOT to Do)

1. Purple Gradient Syndrome

2. Unsourced Claims

3. Wall of Text

4. Broken Links

5. "Trust Me Bro" Methodology

Quick Reference Checklist

Examples from CATY Project

Example 1: Financial Performance Section

Example 2: Risk Factors Extraction

Reference Files

Notes

When to Apply This Skill