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.

## Application Management

The framework provides a structured system for managing individual job applications. Each application gets its own workspace with organized folders for documents and strategy.

### Creating a New Application

Use `/new-application` to initialize a new job application:

```
/new-application "Company Name - Job Title"
```

This will:
1. Create a dated folder: `applications/pending/YYYY-MM-DD-CompanyName-JobTitle/`
2. Generate an `application.md` template with sections for research, strategy, and planning
3. Create an `input/` folder for storing job-related documents

**Example**:
```
/new-application "TechCorp - Senior Developer"
```
Creates: `applications/pending/2025-11-02-TechCorp-Senior-Developer/`

### Adding Input Documents

After creating an application, add all relevant documents to the `input/` folder:

**Recommended documents**:
- Job posting/advertisement (PDF, TXT, MD, DOCX)
- Recruiter emails or communications
- Company research notes (from website, LinkedIn, Glassdoor)
- Follow-up emails or additional context
- Application requirements or instructions

**Supported formats**: PDF, TXT, MD, DOCX, HTML, EML

The more context you provide, the better the analysis will be.

### Populating the Application

Once you've added documents to the `input/` folder, navigate to the application directory and run:

```
cd applications/pending/[your-application-folder]/
/populate-application
```

This will:
1. Read and analyze all documents in the `input/` folder
2. Extract job requirements, company information, and keywords
3. Read your `profile.md` to understand your background
4. Match your experience and skills to the job requirements
5. Populate `application.md` with:
   - Extracted job information
   - Company research and culture insights
   - Match strategy (which experiences/skills to emphasize)
   - Key messages to convey
   - Tone recommendations
   - Suggested projects and achievements to highlight

**The population preserves any manual notes you've added** - it merges AI analysis with your insights.

### Working with application.md

After population, review and refine the `application.md` file:

- **Review extracted information**: Ensure job details and requirements are accurate
- **Add your insights**: Enhance the strategy with your own thoughts
- **Adjust match strategy**: Fine-tune which experiences and projects to emphasize
- **Add personal notes**: Document your authentic reasons for interest in the role
- **Plan your approach**: Use the document checklist to track what needs to be created

The `application.md` serves as your strategic planning document for the entire application process.

### Re-populating Applications

You can run `/populate-application` multiple times:
- Add more documents to `input/` folder
- Re-run to merge new analysis with existing content
- Manual notes are always preserved

## 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 comprehensive 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. Initialize Application (NEW)
- Use `/new-application "Company - Job Title"` to create organized workspace
- This creates: `applications/pending/YYYY-MM-DD-Company-JobTitle/`
- Workspace includes `application.md` template and `input/` folder

### 2. Gather Documents & Context (NEW)
- User adds documents to `input/` folder:
  - Job posting/description
  - Recruiter communications
  - Company research
  - Any other relevant context
- More context = better analysis and strategy

### 3. Analyze & Populate (NEW)
- Navigate to application folder: `cd applications/pending/[folder-name]/`
- Run `/populate-application` to:
  - Read and analyze all input documents
  - Extract job requirements, keywords, company culture
  - Cross-reference with `profile.md`
  - Generate match strategy
  - Populate `application.md` with research and recommendations

### 4. Review & Refine Strategy
- User reviews `application.md` for accuracy
- User adds personal insights and authentic motivations
- Adjust which experiences and projects to emphasize
- Fine-tune key messages and tone

### 5. Validate Application (NEW - Quality Gate)
- Run `/validate-application` to ensure application.md is complete
- Check that required sections are filled (Organization, Job Title, Job Description)
- Verify no placeholder text remains (like `[To be filled]`)
- Get warnings if input/ folder is empty or application seems unpopulated
- **Must pass before document generation**

### 6. Generate Cover Letter
- Run `/write-cover-letter` to generate a tailored cover letter
- System automatically validates application first (stops if incomplete)
- Checks if cover-letter.md already exists (prevents overwriting)
- Generates 300-400 word cover letter using:
  - Profile.md for applicant background and achievements
  - Application.md for job strategy, key messages, and tone
- Standard structure: Opening → Why this role → What you bring → Cultural fit → Closing
- Applies appropriate tone (Formal/Balanced/Casual) from application.md
- Saves to `cover-letter.md` in application folder
- Flags available: `--skip-validation`, `--force` (overwrite existing)

### 7. Review and Refine Cover Letter
- Read generated cover-letter.md carefully
- Verify factual accuracy (names, dates, achievements)
- Add personal touches or additional insights
- Ensure authentic voice and genuine enthusiasm
- Proofread for typos and flow

### 8. Generate CV (FUTURE)
- Generate tailored CV based on application.md strategy (coming soon)
- Emphasize relevant experience from profile.md
- Incorporate keywords naturally

### 9. Generate Application Email (FUTURE)
- Create professional application email (coming soon)

### 10. 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 (Generated by `/write-cover-letter`)
- **Structure**: Opening → Why this role → What you bring → Cultural fit → Closing
- **Length**: 300-400 words (approximately 1 page)
- **Tone**: Applied from application.md tone assessment (Formal/Balanced/Casual)
- **Language**: Inferred from job posting context (German/English)
- **Content**:
  - Use ONLY authentic information from profile.md (no fabrication)
  - Incorporate 2-3 key experiences from match strategy
  - Reference company research and culture insights from application.md
  - Natural incorporation of keywords from job description
  - Company-specific personalization (values, news, projects)
- **Quality checks**:
  - Automatic validation before generation
  - Protection against overwriting existing work
  - Word count target enforcement (300-400 words)
  - Factual accuracy verification

### 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
- `/new-application "Company - Job Title"` - Create a new application workspace with organized folder structure
- `/populate-application` - Analyze input documents and populate application.md with job info, research, and strategy
- `/validate-application [optional-app-name]` - Validate that application.md is complete before document generation
- `/write-cover-letter [optional-app-name] [--skip-validation] [--force]` - Generate a tailored cover letter based on application strategy

## Example Usage

### Example 1: Complete Application Workflow

**User**: "Help me apply for this software engineering position at TechCorp"

**Claude Code should**:
1. Run `/validate-profile` to check profile completeness
2. If validation passes, suggest: "Let's create an application workspace. Run: `/new-application 'TechCorp - Software Engineer'`"
3. After application is created, guide user: "Add the job posting and any other documents to `applications/pending/[folder]/input/`"
4. When user has added documents: "Navigate to the application folder and run `/populate-application`"
5. After population completes: "Review `application.md` to see the analysis and strategy"
6. Validation step: "Run `/validate-application` to ensure the application is complete"
7. If validation passes: "Generate cover letter with `/write-cover-letter`"
8. After generation: "Review cover-letter.md and personalize as needed"
9. Future: Generate tailored CV and application email

### Example 2: Quick Document Request (Legacy Flow)

**User**: "Write a cover letter for this role [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. Generate tailored cover letter using only information from `profile.md`
7. Suggest: "For better organization, consider using `/new-application` next time to manage the full application process"

### Example 3: Validating an Application

**User**: "Check if my TechCorp application is ready"

**Claude Code should**:
1. If user is in application folder: Run `/validate-application` (auto-detects current location)
2. If user is elsewhere: Run `/validate-application 2025-11-02-TechCorp-Software-Engineer`
3. If validation passes (✅): "Your application is complete! Organization: TechCorp, Position: Software Engineer. Ready for document generation."
4. If validation fails (❌): Show specific issues like "Organization Name: Contains placeholder '[To be filled]'" and suggest "Please update application.md or run `/populate-application` if you have documents in input/"
5. Provide clear next steps based on validation result

### Example 4: Generating a Cover Letter

**User**: "Generate cover letter for my TechCorp application"

**Claude Code should**:
1. If user is in application folder: Run `/write-cover-letter` (auto-detects location)
2. If user is elsewhere: Run `/write-cover-letter 2025-11-02-TechCorp-Software-Engineer`
3. System automatically validates application first:
   - If validation fails: Stop and show errors, suggest fixing or using `--skip-validation`
   - If validation passes: Proceed to generation
4. Check for existing cover-letter.md:
   - If exists: Stop and suggest using `--force` flag to overwrite
   - If doesn't exist: Proceed to generation
5. Generate cover letter:
   - Read profile.md for applicant background
   - Read application.md for job strategy and tone
   - Generate 300-400 word tailored cover letter
   - Save to cover-letter.md
6. Show success: "✅ Cover letter saved: cover-letter.md. Generated 376 words. Next: Review and personalize."

**User**: "Regenerate the cover letter with different approach"

**Claude Code should**:
1. Run `/write-cover-letter --force` to overwrite existing file
2. System warns: "⚠️ Overwriting existing cover letter"
3. Proceeds with generation
4. Suggests: "Review the new version and keep whichever you prefer"

## 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.