resume/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

## ⚠️ CRITICAL: NEVER FABRICATE NUMBERS OR DETAILS

**This is checked on every build-resume run. Violation is a critical error.**

- **ONLY use facts from `paul-halvorsen-resume-detailed.md`**
- DO NOT invent: team sizes, customer counts, specific metrics, percentages, achievements, scales
- If a detail isn't in the detailed resume, do not include it
- Allowed: reframe/reorder existing information, remove less relevant details
- **Examples of violations:**
  - ❌ "$9 trillion in assets" (not in detailed resume)
  - ❌ "40+ engineers" (not in detailed resume)
  - ❌ "thousands of security events daily" (not in detailed resume)
  - ✓ "10 auto-scaling clusters" (IS in detailed resume)
  - ✓ "~90% CPU reduction" (IS in detailed resume)

---

## Project Overview

This is a resume builder using Pandoc to convert Markdown resumes with YAML metadata to PDF via LaTeX templates. The build process is containerized using Podman (Docker alternative) for reproducibility and portability.

## Build and Development Commands

**Directory Structure:**
Resumes are organized by company in subdirectories for easy management:
```
.
├── paul-halvorsen-resume.md          (default/main resume)
├── paul-halvorsen-resume-detailed.md (comprehensive details)
├── templates/
│   ├── jb2resume.latex              (classic template)
│   ├── jb2resume-modern.latex       (improved modern template)
│   └── awesome-cv.latex             (modern awesome-cv inspired)
├── files/
│   ├── paul-halvorsen-files-backend-engineer.md
│   ├── paul-halvorsen-files-backend-engineer.pdf (various templates)
│   └── ...
├── valon/
│   ├── paul-halvorsen-valon-software-engineer.md
│   ├── paul-halvorsen-valon-cover-letter.md
│   └── paul-halvorsen-valon-software-engineer.pdf (various templates)
└── [company]/
    └── paul-halvorsen-[company]-[role].md
```

**Available Templates:**

1. **`jb2resume`** - Classic, traditional template
   - Conservative design
   - Best for: Traditional industries, classic look
   - Command: `make resume FILE_NAME=path/to/resume`

2. **`jb2resume-modern`** (Recommended default)
   - Modern improvements: better spacing, proper bullets, visual hierarchy
   - Clean professional look with subtle visual accents
   - Best for: Tech companies, modern look with substance
   - Command: `make resume-modern FILE_NAME=path/to/resume`

3. **`awesome-cv`** - Modern, vibrant template
   - Bold accent colors, prominent sections, contemporary design
   - Best for: Startups, tech companies, when you want to stand out
   - Command: `make resume-awesome FILE_NAME=path/to/resume`

**Build the resume PDF:**
```bash
# Build with default (modern) template
make resume FILE_NAME=paul-halvorsen-resume

# Build with modern template (improved jb2resume)
make resume-modern FILE_NAME=files/paul-halvorsen-files-backend-engineer

# Build with awesome-cv template (bold, modern design)
make resume-awesome FILE_NAME=valon/paul-halvorsen-valon-software-engineer

# Show all available commands and examples
make help
```

**Example workflow for custom resumes:**
```bash
# Using /build-resume (recommended)
/build-resume [paste job description]

# Or manual build
mkdir -p acme/backend-engineer
# Create paul-halvorsen-resume.md in acme/backend-engineer/

# Build with modern template
make resume-modern FILE_NAME=acme/backend-engineer/paul-halvorsen-resume

# Build cover letter
make cover-letter FILE_NAME=acme/backend-engineer/paul-halvorsen-cover-letter

# Output:
#   acme/backend-engineer/paul-halvorsen-resume.pdf
#   acme/backend-engineer/paul-halvorsen-cover-letter.pdf
```

**Clean commands:**
- `make clean` - Remove LaTeX log files
- `make cleanpaper` - Remove the generated PDF (uses FILE_NAME variable)
- `make cleanpodman` - Remove the Podman image and build cache (forces rebuild next time)
- `make cleanall` - Remove everything (logs, PDF, and Podman image)

## High-Level Architecture

### Resume Processing Pipeline
1. **Input**: Markdown file with YAML metadata block (`*.md`)
2. **Processing**: Pandoc converts markdown to LaTeX using a template
3. **Output**: PDF generated via LaTeX compilation
4. **Containerization**: All processing happens in a Podman container to ensure consistent output

### Key Components

**Templates** (`templates/` directory):
- `jb2resume.latex` - Default resume template (recommended)
- `jb2-modern.latex` - Alternative modern template

Both templates are dual-licensed under GPL v2+ and BSD 3-Clause.

**Dockerfile**:
- Based on `pandoc/latex:latest`
- Installs additional LaTeX packages: `enumitem`, `sectsty`, `underscore`
- Sets `/data` as the working volume

**Makefile**:
- Uses Podman (not Docker)
- `FILE_NAME=paul-halvorsen-resume` - Change this to build a different `.md` file
- `USER=paul` - Container user for file permissions
- Automatically detects if the Podman image needs rebuilding

### Resume Structure

**YAML Metadata Block** (top of `.md` file):
```yaml
---
name: [Your Name]
keywords: [comma-separated keywords for PDF metadata]
left-column:
    - [Line 1 for left column under name]
    - [Line 2 for left column]
right-column:
    - [Line 1 for right column under name]
    - [Line 2 for right column]
fontsize: [default 10pt]
fontenc: [default T1]
urlcolor: [default blue]
linkcolor: [default magenta]
numbersections: [true/false, controls section numbering]
name-color: [SVG color name like DarkSlateGray, applies to name]
section-color: [SVG color name like Tomato, applies to section headers]
---
```

The metadata block is required and must appear at the very top of the markdown file before any content.

**Resume Content**: Standard Markdown after the metadata block. Headers become sections, lists are formatted naturally.

### Multiple Resume Versions

The repository contains two main resume files:
- `paul-halvorsen-resume.md` - Concise version (built by default via Makefile)
- `paul-halvorsen-resume-detailed.md` - Extended version with more details

To build a different version, either:
1. Modify the `FILE_NAME` variable in the Makefile, or
2. Run Pandoc directly with the desired input file

### Important Notes

- The Makefile assumes Podman is installed and available
- Build output (.pdf files) and Podman artifacts (.podman-build file) are not tracked in git
- The `.podman-build` marker file prevents unnecessary image rebuilds (remove it to force rebuild)
- All LaTeX processing happens inside the container; no local LaTeX installation is needed

## Creating Customized Resumes for Job Applications

The detailed resume (`paul-halvorsen-resume-detailed.md`) contains comprehensive information across all roles and projects. To create a customized resume for a specific job application:

### Quick Start

```bash
# Use /build-resume with job description
/build-resume [paste job description]
```

Claude will:
- Check if you've already applied to this company/position (prevent duplicates)
- Create clean directory structure
- Generate customized resume and cover letter
- Build PDFs automatically
- Create job analysis document

### Directory Structure

New standardized format for all applications:

```
company/
└── position/
    ├── paul-halvorsen-resume.md
    ├── paul-halvorsen-resume.pdf
    ├── paul-halvorsen-cover-letter.md
    ├── paul-halvorsen-cover-letter.pdf
    └── job-breakdown.md (analysis & strategy)
```

**Examples:**
- `tenstorrent/devrel-engineer/paul-halvorsen-resume.md`
- `stripe/backend-engineer/paul-halvorsen-resume.md`
- `files/senior-backend-engineer/paul-halvorsen-resume.md`

### Manual Build

If manually creating/updating files:

```bash
# Build with modern template
make resume-modern FILE_NAME=company/position/paul-halvorsen-resume

# Build cover letter
make cover-letter FILE_NAME=company/position/paul-halvorsen-cover-letter

# Build both
make resume-modern FILE_NAME=company/position/paul-halvorsen-resume && \
  make cover-letter FILE_NAME=company/position/paul-halvorsen-cover-letter
```

### Application Tracking

All applications tracked in memory at:
```
~/.claude/projects/-home-paul-Public-resume/memory/applications_tracker.md
```

Prevents duplicate efforts for the same company/position combination.

### Expected Result

A 1-2 page resume tailored to the job requirements with:
- Reordered work experience (most relevant roles first)
- Emphasized skills and metrics matching the job description
- Highlighted relevant accomplishments and projects
- Customized summary/intro focused on the role
- Compelling cover letter addressing company mission and role fit
- Job analysis document with fit assessment and strategy notes

The detailed resume includes proficiency levels, performance metrics, specializations, and comprehensive technical details that allow Claude Code to intelligently match your background to specific job requirements.

## Template Selection Guide

### When to Use Each Template

**`jb2resume` (Classic)**
- Traditional companies (finance, government, law)
- Conservative industries
- When you want a proven, time-tested design
- Important: ATS compatibility is high priority
- Example: Financial institutions, government agencies

**`jb2resume-modern` (Recommended for Most Tech)**
- Tech startups and established tech companies
- Modern, professional look without being flashy
- Better spacing and readability than classic
- Still ATS-friendly and traditional enough for conservative industries
- Best balance of modern and professional
- **Default recommendation for Files.com, Valon, and similar companies**

**`awesome-cv` (Modern & Bold)**
- Early-stage startups and growth-stage companies (Series A-C)
- Design-forward or forward-thinking companies
- When you want to make a visual impression
- Companies that explicitly value design and attention to detail
- Use when: "We're disrupting X industry" is in the job description
- Example: Files.com, Valon, and similar Series C companies

### Quick Decision Tree

```
Is the company a startup or growth-stage company?
├─ YES → Use awesome-cv (bold, modern, stands out)
└─ NO → Is it a traditional/conservative industry?
    ├─ YES → Use jb2resume (classic, proven)
    └─ NO → Use jb2resume-modern (modern but professional)
```

### For Paul's Current Applications

- **Files.com** (Series C, a16z-backed): awesome-cv recommended
- **Valon** (Series C, a16z-backed): awesome-cv recommended
- **Enterprise customers**: jb2resume-modern
- **Government/DoD contracts**: jb2resume (classic)

## CRITICAL: Resume Content Rules

### Never Fabricate Numbers, Metrics, or Details

**⚠️ BLOCKING REQUIREMENT: DO THIS CHECK BEFORE WRITING EACH RESUME SECTION**

**ONLY use facts from `paul-halvorsen-resume-detailed.md` as the source of truth.**

**Do NOT invent:**
- Team sizes ("40+ engineers across company")
- Customer/endpoint counts unless explicitly documented
- Specific metrics not stated in detailed resume
- Job responsibilities not listed
- Percentages, scales, or achievements without documentation
- Any number or quantifiable claim not in detailed resume

**Pre-write checklist (do this for EVERY bullet point):**
- [ ] Is this number/metric in paul-halvorsen-resume-detailed.md?
- [ ] If NO, do not include it
- [ ] Am I reframing documented information, or inventing new information?
- [ ] If inventing, stop and remove the bullet

**What IS allowed:**
- Reorder existing information for job relevance
- Rephrase/reframe documentation for clarity
- Remove less relevant details to save space
- Use exact metrics/percentages from detailed resume

**Violations Paul has caught (do not repeat):**
- ❌ "$9 trillion in assets" (Addepar) — Not in detailed resume
- ❌ "40+ engineers across company" (DOPE) — Not in detailed resume
- ❌ "thousands of security events daily" (made up) — Not documented anywhere

**Valid examples (these ARE documented):**
- ✓ "Performance improvements: reduced CPU usage ~90%" → Binary Defense section
- ✓ "Customers: Fortune 500 companies, thousands of endpoints" → Binary Defense section
- ✓ "10 auto-scaling clusters in AWS" → Abnormal AI section
- ✓ "MySQL database (thousands of records)" → NSA section

**Apply this rule to:**
- Work experience descriptions
- Metrics and achievements
- Team structures
- Customer information
- Technical details
- ANY quantifiable claim

### Job Breakdown File Checklist

When creating `job-breakdown.md` files:
- [ ] All numbers in "Requirements Analysis" table come from job posting OR documented facts
- [ ] All numbers in "Strengths in Context" are from paul-halvorsen-resume-detailed.md
- [ ] No invented metrics like "years of experience with technology X" unless documented
- [ ] Salary recommendations are conservative estimates, not fabricated
- [ ] Keyword match % is realistic based on actual resume content
- [ ] All claims about Paul's background are verifiable from detailed resume