Bewerbungszauberer/src/CLAUDE.md

# Job Application Framework - Instructions for Claude Code

This directory contains the Job Application Framework (Bewerbungszauberer), designed to help create tailored CVs, cover letters, and application emails using Claude Code.

## Core Principle: Profile as Source of Truth

**IMPORTANT**: When the user requests help with ANY job application task (CV, cover letter, email, or application advice), you MUST:

1. **Validate the profile first** - Run `/validate-profile` to ensure `profile.md` is complete (see Profile Validation section below)
2. **Always read `profile.md` first** - This file contains the applicant's verified personal and professional information
3. **Use ONLY information from `profile.md`** - Never fabricate, assume, or hallucinate details about the applicant
4. **Maintain consistency** - All generated documents must align with the information in `profile.md`

## Profile Validation

**CRITICAL**: Before generating any job application documents (CV, cover letter, or email), you MUST validate that `profile.md` is complete.

### When to Validate

Run `/validate-profile` automatically before:
- Generating a CV/resume
- Writing a cover letter
- Drafting an application email
- Creating any job application materials

### Validation Process

1. **Automatic validation**: When the user requests application generation, first run `/validate-profile`
2. **Check results**:
   - ✅ If validation passes → proceed with generation
   - ❌ If validation fails → inform the user of incomplete sections and STOP
3. **User action**: User must complete the profile sections flagged by validation
4. **Re-validate**: After user updates `profile.md`, run `/validate-profile` again before proceeding

### Handling Validation Failures

If `/validate-profile` reports incomplete sections:

1. **Do NOT generate documents** - Incomplete profiles will result in placeholder text in professional documents
2. **Show validation results** - Display which sections need completion
3. **Guide the user**: "Your profile has incomplete sections. Please update `profile.md` with your real information in the following areas: [list sections]. Run `/validate-profile` again when ready."
4. **Wait for updates**: Do not proceed until validation passes

### Explicit Skip Option

If the user explicitly requests to skip validation with phrases like:
- "Generate CV without validation"
- "I know my profile is incomplete, proceed anyway"
- "Skip validation and generate"

You MAY proceed with a clear warning:
```
⚠️  WARNING: Proceeding without validation. Your profile may contain placeholder text.
Generated documents might include [Your Name], [Company], or other template text.
Please review carefully and manually replace any placeholders before sending to employers.
```

**Default behavior**: ALWAYS validate unless explicitly told to skip.

## When to Read the Profile

Read `profile.md` automatically when the user asks for help with:

- Creating or tailoring a CV/resume
- Writing a cover letter
- Drafting an application email
- Customizing application documents for a specific job
- Reviewing or improving existing application materials
- Extracting relevant experience or skills for a position
- Advice on how to position themselves for a role

## Job Application Workflow

When helping with job applications, follow this workflow:

### 0. Profile Validation (REQUIRED FIRST STEP)
- Run `/validate-profile` to check `profile.md` is complete
- If validation fails, stop and ask user to complete profile
- If validation passes or user explicitly skips, proceed to step 1

### 1. Research & Context
- Read the job description provided by the user
- Extract key requirements, skills, and keywords
- Analyze the company culture from the job posting language
- Read `profile.md` to understand what the applicant brings

### 2. Match & Strategy
- Identify which of the applicant's experiences (from `profile.md`) best match the job requirements
- Determine which skills and projects to emphasize
- Decide on the appropriate tone (formal, balanced, or casual) based on company culture

### 3. Content Generation
- Generate CV/cover letter/email based on the strategy
- Emphasize relevant experience from `profile.md`
- Incorporate keywords from the job description naturally
- Maintain factual accuracy - use only verified information from `profile.md`

### 4. Quality Assurance
- Verify all company names, dates, and facts are correct
- Ensure consistency between all documents (CV ↔ cover letter ↔ email)
- Check that tone matches the target company culture
- Confirm ATS optimization if applicable (simple formatting, keywords, standard sections)

## Document Standards

### CV/Resume
- Use information from relevant sections of `profile.md`
- Tailor the professional summary to the specific role
- Emphasize experiences and skills that match job requirements
- Keep formatting simple and ATS-friendly
- Use quantifiable achievements when available

### Cover Letter
- Structure: Opening → Why this role → What you bring → Cultural fit → Closing
- Length: Aim for 1 page (3-4 paragraphs)
- Tone: Match company culture (formal/balanced/casual)
- Personalize: Reference specific aspects of the job/company
- Connect: Link applicant's experience to job requirements

### Application Email
- Keep it short (3-4 sentences maximum)
- Subject line: Clear and professional
- Body: Brief introduction, reference to attached documents, expression of interest
- Professional signature using contact info from `profile.md`

## Cultural Considerations

This framework is designed with the German job market in mind:

- More formal tone is often expected
- Detailed work history with exact dates is valued
- Certificates and credentials are highly regarded
- A professional photo on CV may be common (user's choice)

Adjust recommendations based on the target market if the user specifies a different region.

## Constraints

**Data Privacy**:
- All information stays local - only API calls to Claude use the data
- Never suggest uploading sensitive personal data to third-party services
- Respect GDPR and data protection principles

**Accuracy & Honesty**:
- NEVER fabricate experience, skills, or achievements
- If `profile.md` lacks information needed for a job application, ask the user to update `profile.md` first
- Be transparent about what can and cannot be emphasized from the applicant's background

**Quality Standards**:
- All generated content is a DRAFT - user must review and approve
- Fact-check company names, contact persons, and details from job postings
- Maintain consistency across all documents for a single application

## Available Commands

- `/validate-profile` - Validate that `profile.md` is complete and ready for application generation

## Example Usage

**User**: "Help me apply for this software engineering position at TechCorp [paste job description]"

**Claude Code should**:
1. Run `/validate-profile` to check profile completeness
2. If validation fails: inform user of incomplete sections and stop
3. If validation passes: Read `profile.md` to load applicant information
4. Analyze the job description for requirements and culture
5. Identify matching experiences and skills from the profile
6. Ask clarifying questions: "Would you like me to create a CV, cover letter, or both?"
7. Generate tailored documents using only information from `profile.md`
8. Ensure all documents are consistent and factually accurate

## Updating the Profile

If you notice missing or outdated information during application preparation:
- Inform the user which sections of `profile.md` need updates
- Ask them to update `profile.md` first before generating documents
- This ensures the profile remains the single source of truth

---

**Remember**: The quality of output depends on the quality of `profile.md`. Encourage users to keep it complete, accurate, and up to date.