Bewerbungszauberer/src/.agent/workflows/write-cover-letter.md

---
description: Generate a tailored cover letter based on application strategy and profile information.
---

# Instructions

You are generating a professional cover letter for a job application. This letter must be authentic, well-structured, and personalized based on the applicant's profile and application strategy.

## CRITICAL: Natural Writing Style

**The cover letter must sound like it was written by a real person, not AI or marketing copy.**

### Authenticity Principles

1. **Avoid Pompous/Exaggerated Language**:
   - NO: "I am thrilled and absolutely excited", "exceptional expertise", "unparalleled skills"
   - YES: "I am interested", "strong experience", "relevant skills"
   - Avoid superlatives: "best", "perfect", "incredible", "amazing", "outstanding"
   - Use modest, factual language

2. **Avoid Self-Marketing Speak**:
   - NO: "I am confident I would be an asset to your team", "I bring a proven track record"
   - YES: "I believe my experience aligns well", "In my previous role, I..."
   - Let achievements speak for themselves without embellishment
   - Don't oversell - be matter-of-fact about accomplishments

3. **Write Naturally and Conversationally**:
   - Use simple, direct sentences alongside more complex ones (vary structure)
   - Avoid corporate jargon and buzzwords: "synergy", "leverage", "drive results", "best-in-class"
   - Write how a real person would talk, not a PR statement
   - It's okay to start sentences with "And" or "But" occasionally for natural flow

4. **Be Specific, Not Generic**:
   - NO: "I'm a passionate professional with excellent communication skills"
   - YES: "In my last project, I worked with cross-functional teams to..."
   - Show through examples, don't just claim attributes

5. **Intentional Imperfections for Authenticity**:
   - Include 1-2 very minor, barely noticeable errors to appear human-written:
     - A missing comma in a compound sentence
     - Slight repetition of a common word
     - A minor grammatical quirk (e.g., "the company's mission" instead of "the mission of the company" in one place, then reverse in another)
     - These should be SUBTLE - not obvious typos or wrong words
   - **IMPORTANT**: Errors should never affect comprehension or professionalism
   - Examples of acceptable minor errors:
     - "I have worked with Python, JavaScript and Go" (missing Oxford comma)
     - "The role interested me and and I reached out" (double word, very subtle)
     - Slight informality: "I've worked" vs "I have worked" inconsistency

6. **Modesty Over Bragging**:
   - NO: "I excel at everything I do", "I'm the ideal candidate"
   - YES: "I've had good results with similar challenges", "I think I could contribute"
   - Understate slightly rather than overstate
   - Let facts demonstrate competence

### Tone-Specific Guidelines

- **Formal**: Still professional but not stuffy. Avoid sounding like a corporate press release.
- **Balanced**: Conversational professionalism. Like talking to a colleague you respect but don't know well yet.
- **Casual**: Friendly and personable, but still competent. Like an email to a friendly senior colleague.

**Remember**: The goal is to sound like a competent professional who wrote this themselves, not like they hired a marketing agency or used AI.

## Step 1: Parse Command Arguments

Check for optional flags and parameters:

**Flags:**
- `--skip-validation`: Skip automatic validation check
- `--force` or `--overwrite`: Overwrite existing cover-letter.md if it exists
- `--help`: Show usage information and exit

**Parameter:**
- Application folder name (optional): e.g., `2025-11-02-TechCorp-Developer`

If `--help` flag is present, show usage and exit:
```
Usage: /write-cover-letter [application-name] [flags]

Generates a tailored cover letter for a job application.

Options:
  [application-name]     Optional. Name of application folder.
                         If omitted, uses current directory.

  --skip-validation      Skip automatic validation check (not recommended)
  --force, --overwrite   Overwrite existing cover-letter.md
  --help                 Show this help message

Examples:
  /write-cover-letter
  /write-cover-letter 2025-11-02-TechCorp-Developer
  /write-cover-letter --force
  /write-cover-letter --skip-validation --force

The command will:
1. Validate the application (unless --skip-validation)
2. Check if cover letter already exists (unless --force)
3. Read profile.md and application.md
4. Generate a tailored 300-400 word cover letter
5. Save to cover-letter.md in the application folder
```

## Step 2: Location Detection

### Determine Target Application

**If NO parameter provided:**
1. Check current working directory
2. Verify if inside an application folder:
   - Path pattern: ends with `applications/pending/[folder-name]/`
   - File existence: `application.md` exists in current directory
3. If yes → use this application
4. If no → show error with available applications

**If parameter PROVIDED:**
1. Resolve to application folder: `applications/pending/[folder-name]/`
2. Check if `application.md` exists in that location
3. If yes → use that application
4. If no → show error with available applications

### Error: Location Unclear

```
❌ Not in an application folder

Please either:
1. Navigate to an application folder:
   cd applications/pending/[application-folder]/
   /write-cover-letter

2. Or provide the application folder name:
   /write-cover-letter [application-folder-name]

Available applications:
[List output of: ls applications/pending/]

Example:
/write-cover-letter 2025-11-02-TechCorp-Developer
```

### Error: Application Not Found

```
❌ Application not found: [provided-name]

Available applications:
[List output of: ls applications/pending/]
```

## Step 3: Automatic Validation Check

**Unless `--skip-validation` flag is present**, run validation before generating.

### Run Validation

1. Show progress: `🔍 Validating application...`
2. Execute `/validate-application` for the target application
3. Capture result (pass/fail)

### Handle Validation Result

**If validation PASSES:**
```
✅ Application validation passed
```
Proceed to Step 4.

**If validation FAILS:**
```
❌ Application validation failed

Your application has incomplete sections. Please fix these issues first:

[Show validation error details]

Options:
1. Fix the issues in application.md and try again
2. Run /validate-application for full details
3. Use --skip-validation to proceed anyway (not recommended)

Example:
/write-cover-letter --skip-validation
```
STOP. Do not generate cover letter.

### Skip Validation Warning

**If `--skip-validation` flag is present:**
```
⚠️  Skipping validation check (not recommended)

Proceeding with cover letter generation. The application may have incomplete sections.
```
Proceed to Step 4.

## Step 4: Check for Existing Cover Letter

Check if `cover-letter.md` exists in the application folder.

### If File Exists (and --force NOT present)

```
❌ Cover letter already exists

File: [path-to-cover-letter.md]

To regenerate, use:
/write-cover-letter --force

⚠️  Warning: This will overwrite your existing cover letter.
If you've made manual edits, they will be lost.
```
STOP. Do not overwrite.

### If File Exists (and --force IS present)

```
⚠️  Overwriting existing cover letter

File: [path-to-cover-letter.md]
Your previous cover letter will be replaced.
```
Proceed to Step 5.

### If File Does Not Exist

Proceed to Step 5 (no message needed).

## Step 5: Read Data Sources

Show progress: `📝 Generating cover letter...`

### Read profile.md

1. Check if `profile.md` exists in framework root
2. Read entire file
3. Parse and extract:
   - **Personal Information**: Full name, email, phone, location, address
   - **Professional Summary**: For potential reference
   - **Work Experience**: All entries (job titles, companies, dates, responsibilities, achievements)
   - **Skills**: Technical and soft skills
   - **Projects**: Notable projects
   - **Education**: Degrees and certifications

**If profile.md is missing or unreadable:**
```
❌ Profile not found

Could not read profile.md. Please create and validate your profile first.

Steps:
1. Fill out profile.md with your information
2. Run /validate-profile to check completeness
3. Try /write-cover-letter again
```
STOP.

Show progress: `✓ Read profile.md (applicant background)`

### Read application.md

1. Check if `application.md` exists in application folder
2. Read entire file
3. Parse and extract:
   - **Metadata**: Application status, deadlines
   - **Organization Information**: Company name, industry, location, website, contact person name
   - **Job Information**: Job title, level, department, employment type, remote status
   - **Job Description Summary**: Responsibilities, required skills, preferred skills, keywords
   - **Research Notes**: Company culture, values, recent news, competitive landscape
   - **Match Strategy**: Experiences to emphasize, skills to highlight, projects to mention, gaps and how to address
   - **Key Messages**: Main points to convey (usually 3-5 bullet points)
   - **Tone of Voice**: Tone assessment (Formal/Balanced/Casual) and reasoning

**If application.md is missing or unreadable:**
```
❌ Application not found

Could not read application.md in [path].

This doesn't appear to be a valid application folder.
Did you create this application with /new-application?
```
STOP.

Show progress: `✓ Read application.md (job strategy)`

### Cross-Reference Match Strategy

1. Identify which specific experiences from profile.md are mentioned in Match Strategy section
2. Extract those full experience entries from profile.md
3. Identify which skills to emphasize
4. Identify which projects to mention
5. Note any gaps mentioned and how to address them

Show progress: `✓ Analyzed match strategy ([N] key experiences identified)`

## Step 6: Determine Language and Tone

### Detect Language

Check these indicators in order:
1. **Job posting language** (if job description in input/ was in German)
2. **Company location** (if Germany/Austria/Switzerland → likely German)
3. **Application.md language** (if written in German → use German)
4. **Default**: English if unclear

### Extract Tone

From application.md "Tone of Voice" section:
- Look for: "Formal", "Balanced", or "Casual"
- Default to "Balanced" if not specified

Show progress: `✓ Applied tone: [Formal/Balanced/Casual]`
Show progress: `✓ Language: [German/English]`

## Step 7: Generate Cover Letter Content

Generate a professional cover letter with the following structure. Target: **300-400 words total**.

### Structure Overview

1. Contact Header (applicant + company addresses, date)
2. Salutation
3. Opening Paragraph (50-70 words)
4. Why This Role Paragraph (70-90 words)
5. What You Bring (120-150 words, split into 1-2 paragraphs)
6. Cultural Fit Paragraph (50-70 words)
7. Closing Paragraph (40-50 words)
8. Sign-off

---

### Contact Header

**Format for German:**
```
[Applicant Full Name]
[Applicant Street Address]
[Applicant ZIP] [Applicant City]
[Applicant Email] | [Applicant Phone]

[Current Date in DD.MM.YYYY format]

[Company Name]
[Contact Person Name if available, otherwise "Personalabteilung"]
[Company Street Address if available]
[Company ZIP] [Company City]
```

**Format for English:**
```
[Applicant Full Name]
[Applicant Street Address]
[Applicant City], [State/Country] [ZIP]
[Applicant Email] | [Applicant Phone]

[Current Date in Month DD, YYYY format]

[Hiring Manager Name if available]
[Company Name]
[Company Street Address if available]
[Company City], [State/Country] [ZIP]
```

Use information from profile.md and application.md. If address details are missing, use what's available (at minimum: name, email, phone).

---

### Salutation

**If contact person name is available in application.md:**
- German: `Sehr geehrte/r [Herr/Frau] [Last Name],` or `Liebe/r [First Name],` (Casual tone only)
- English: `Dear [Mr./Ms./Dr.] [Last Name],` or `Dear [First Name],` (Casual tone only)

**If no contact person:**
- German: `Sehr geehrte Damen und Herren,`
- English: `Dear Hiring Manager,`

---

### Opening Paragraph (50-70 words)

**Purpose**: Hook the reader, state the position, show genuine interest.

**Elements to include:**
1. Reference to the specific job title
2. Reference to company name
3. Brief statement of interest
4. One compelling hook from:
   - Key messages (why you're excited about this role)
   - Research notes (something specific about the company)
   - Relevant achievement that positions you well

**Tone guidance:**
- **Formal**: Professional, respectful, traditional - but not pompous
- **Balanced**: Professional but warm, approachable - natural conversation
- **Casual**: Friendly and personable - like talking to a colleague

**APPLY NATURAL WRITING PRINCIPLES**: Avoid exaggeration, use modest language, be factual.

**Example (Balanced, English - Natural Tone):**
> I'm writing to apply for the Senior Software Engineer position at TechCorp. I've been working in backend development for about eight years now, mostly focused on scalable systems. Your work on cloud infrastructure caught my attention, particularly the CloudScale platform you launched recently.

**Example (Formal, German - Natural Tone):**
> Ich bewerbe mich um die Position als Senior Software Engineer bei TechCorp. Seit etwa acht Jahren arbeite ich in der Backend-Entwicklung mit Schwerpunkt auf skalierbare Systeme. Ihre Arbeit im Bereich Cloud-Infrastruktur hat mein Interesse geweckt, insbesondere die kürzlich eingeführte CloudScale-Plattform.

---

### Why This Role Paragraph (70-90 words)

**Purpose**: Show you've researched the company and explain why this specific role/company appeals to you.

**Elements to include:**
1. Reference to company research (values, mission, recent news, products)
2. Connection between your interests/values and the company's
3. Specific reasons you're drawn to this role (not just any job)
4. Demonstrate understanding of the company's work and challenges

**Sources:**
- Research Notes section from application.md
- Key Messages section
- Company culture insights

**APPLY NATURAL WRITING PRINCIPLES**: Show genuine interest without sounding like a sales pitch.

**Example (Balanced, English - Natural Tone):**
> What interests me about TechCorp is your open-source work and the CloudScale platform. I've been reading your engineering blog for a while now and find your approaches to distributed systems interesting. Working on infrastructure that serves enterprise customers is something I've done before and would like to continue doing.

---

### What You Bring Paragraphs (120-150 words total, 1-2 paragraphs)

**Purpose**: Demonstrate you're qualified by highlighting relevant experiences, skills, and achievements.

**Elements to include:**
1. 2-3 specific experiences from Match Strategy
2. Concrete achievements with quantifiable results (from profile.md)
3. Relevant skills that match job requirements
4. Natural incorporation of keywords from job description
5. Connection between your experience and their needs
6. Mention of 1-2 relevant projects if applicable

**Structure:**
- If 2 experiences: One paragraph covering both
- If 3 experiences: Split into 2 paragraphs (2 experiences in first, 1 in second)

**Sources:**
- Match Strategy section (which experiences to emphasize)
- Profile.md work experience and projects
- Job Description Summary (requirements to address)

**Important:**
- Use ONLY real experiences and achievements from profile.md
- Include specific metrics when available (e.g., "reduced latency by 40%", "managed team of 5")
- Don't list skills – demonstrate them through experiences
- Make clear connections to job requirements

**APPLY NATURAL WRITING PRINCIPLES**: Be factual, not boastful. Let numbers speak for themselves.

**Example (Balanced, English - Natural Tone, 2 experiences):**
> At DataFlow Systems, I've been working as a Lead Backend Engineer for the past three years. I helped architect a microservices platform that now handles around 10 million requests per day. We managed to reduce latency by about 45% and get reliability up to 99.95%. I've worked with Kubernetes, Go and PostgreSQL quite a bit, mostly building systems for enterprise clients.

> Before that, at CloudNet Solutions, I worked on a distributed caching layer that improved API response times by 60% and saved around $50,000 in infrastructure costs. I also spent time mentoring three junior engineers. The work was similar to what you're describing in the job posting, so I think the experience would transfer well.

---

### Cultural Fit Paragraph (50-70 words)

**Purpose**: Show you'd be a good culture match and would thrive in their environment.

**Elements to include:**
1. Reference to company culture insights from Research Notes
2. Alignment of personal values with company values
3. Relevant soft skills that match company culture indicators
4. Enthusiasm for the work environment, team, or company approach
5. Mention of collaboration style if company emphasizes teamwork

**Sources:**
- Research Notes (company culture observations)
- Company values mentioned in job description
- Your soft skills from profile.md

**APPLY NATURAL WRITING PRINCIPLES**: Be genuine, not gushing. Show fit through specifics, not claims.

**Example (Balanced, English - Natural Tone):**
> I like that TechCorp emphasizes collaborative work and learning. From what I've read, there's a good balance between technical work and team collaboration, which has worked well for me in past roles. I tend to learn best when I can share knowledge with others, so the culture you describe seems like a good fit.

---

### Closing Paragraph (40-50 words)

**Purpose**: Strong finish with call to action and expression of enthusiasm.

**Elements to include:**
1. Reiterate strong interest in the position
2. State availability for interview/discussion
3. Thank the hiring manager
4. Professional call to action

**Tone guidance:**
- **Formal**: Respectful but not flowery
- **Balanced**: Professional and straightforward
- **Casual**: Friendly but not overeager

**APPLY NATURAL WRITING PRINCIPLES**: Simple, direct closing. No need to oversell.

**Example (Balanced, English - Natural Tone):**
> I'd be happy to discuss this role further if you think my background might be a good fit. I'm available for a call or meeting whenever works for you. Thanks for taking the time to review my application.

**Example (Formal, German - Natural Tone):**
> Ich würde mich freuen, diese Position in einem persönlichen Gespräch näher zu besprechen. Für ein Interview stehe ich gerne zur Verfügung. Vielen Dank für Ihre Aufmerksamkeit.

---

### Sign-off

**German:**
- Formal: `Mit freundlichen Grüßen,`
- Balanced: `Mit freundlichen Grüßen,`
- Casual: `Herzliche Grüße,` or `Viele Grüße,`

**English:**
- Formal: `Sincerely,` or `Respectfully,`
- Balanced: `Sincerely,` or `Best regards,`
- Casual: `Best regards,` or `Warm regards,`

Follow with applicant's full name from profile.md.

---

## Step 8: Quality Checks

Before writing the file, verify:

### Word Count Check
- Count total words in body (excluding header and sign-off)
- Target: 300-400 words
- If < 280 words: Too short, add more detail to experiences or cultural fit
- If > 420 words: Too long, tighten prose and remove redundancy

Show progress: `✓ Generated [N] words (target: 300-400)`

### Factual Accuracy Check
- Every experience mentioned must exist in profile.md
- Every achievement must be from profile.md (no hallucinations)
- Company information must match application.md
- Job title and company name must be correct

### Tone Consistency Check
- Language level matches tone (Formal = elevated, Balanced = professional, Casual = conversational)
- Sentence structure matches tone (Formal = complex, Balanced = varied, Casual = simpler)
- Vocabulary matches tone

### Personalization Check
- At least 2 company-specific references (research, values, products, news)
- Keywords from job description incorporated naturally
- Connection to match strategy is clear

### Authenticity Check
- **CRITICAL**: Apply all Natural Writing Style principles from the beginning
- Sounds human, not AI-generated (no pompous or marketing language)
- Natural flow between paragraphs (conversational transitions)
- Specific rather than generic (examples, not claims)
- Shows genuine interest (not exaggerated enthusiasm)
- Modest tone (understate rather than overstate)
- Includes 1-2 minor, subtle imperfections for authenticity
- Avoids superlatives and corporate jargon

## Step 9: Format and Write File

### Format as Markdown

```markdown
<!--
Cover Letter
Generated: [YYYY-MM-DD HH:MM]
Sources: profile.md, application.md
Word count: [N] words
Tone: [Formal/Balanced/Casual]
Language: [German/English]
-->

[Applicant Full Name]
[Applicant Address Block]
[Applicant Email] | [Applicant Phone]

[Date]

[Company Name]
[Contact Person / Hiring Manager]
[Company Address if available]

[Salutation]

[Opening Paragraph]

[Why This Role Paragraph]

[What You Bring Paragraph 1]

[What You Bring Paragraph 2 if applicable]

[Cultural Fit Paragraph]

[Closing Paragraph]

[Sign-off]
[Applicant Full Name]
```

### Write to File

1. Write content to `cover-letter.md` in the application folder
2. Handle write errors gracefully:
   - Permission denied: "Could not save cover-letter.md. Check write permissions."
   - Disk full: "Could not save cover-letter.md. Check available disk space."
   - Other errors: "Could not save cover-letter.md: [error details]"

## Step 10: Success Output

Display success message:

```
✅ Cover letter saved: cover-letter.md

## Generation Summary:

📊 Statistics:
- Word count: [N] words
- Tone: [Formal/Balanced/Casual]
- Language: [German/English]
- Experiences highlighted: [N]
- Key messages incorporated: [N]

📍 Location:
[full or relative path to cover-letter.md]

## Content Included:

✓ Personalized opening with company-specific hook
✓ Research-backed explanation of interest in role
✓ [List 2-3 key experiences emphasized, e.g.:]
  - Lead Backend Engineer role at DataFlow Systems
  - Distributed caching project at CloudNet Solutions
✓ Cultural fit based on company values
✓ Professional closing with call to action

## Next Steps:

1. **Review cover-letter.md**:
   Open and read the generated letter carefully. Check for:
   - Factual accuracy (names, dates, achievements)
   - Natural tone and flow
   - Authentic representation of your interest

2. **Personalize further** (recommended):
   Add any additional personal connections:
   - Specific conversations with employees
   - Personal anecdotes relevant to the role
   - Unique insights about the company

3. **Generate CV** (coming soon):
   /write-cv

4. **Proofread before sending**:
   - Check for typos or grammar issues
   - Ensure company name and job title are correct
   - Verify contact information is up to date

---

**Tip**: This cover letter was generated based on your application strategy.
The more detailed your application.md (especially Match Strategy and Key Messages),
the more personalized and compelling your cover letter will be.
```

## Error Handling Reference

### Missing profile.md
```
❌ Profile not found

Could not read profile.md. Please create and validate your profile first.

Steps:
1. Fill out profile.md with your information
2. Run /validate-profile to check completeness
3. Try /write-cover-letter again
```

### Missing application.md
```
❌ Application not found

Could not read application.md in [path].

This doesn't appear to be a valid application folder.
Did you create this application with /new-application?
```

### Validation Failed (no --skip-validation)
```
❌ Application validation failed

[Validation error details]

Options:
1. Fix issues in application.md
2. Run /validate-application for full details
3. Use --skip-validation to proceed (not recommended)
```

### Cover Letter Exists (no --force)
```
❌ Cover letter already exists

File: [path]

Use --force to overwrite:
/write-cover-letter --force

⚠️  This will replace your existing cover letter.
```

### File Write Error
```
❌ Could not save cover letter

Error: [specific error message]

Possible causes:
- Insufficient write permissions
- Disk space full
- Path too long

Please check the issue and try again.
```

## Important Notes

### Authenticity is Critical
- Use ONLY information from profile.md (no fabrication)
- Keep experiences and achievements factual
- If profile.md lacks information for a job requirement, acknowledge the gap or focus on related transferable skills
- Better to be honest about limitations than to invent experience

### Personalization Matters
- Generic cover letters are obvious and ineffective
- Leverage research notes from application.md to make company-specific references
- Connect applicant's genuine interests (from key messages) to the role
- Show real understanding of the company and position

### Tone Appropriateness
- Formal: Traditional companies, conservative industries, senior positions, German Mittelstand
- Balanced: Most tech companies, modern corporations, professional services
- Casual: Startups, creative agencies, developer-focused roles, flat hierarchies
- When in doubt, err on the side of "Balanced"

### Quality Over Speed
- Take time to craft well-structured paragraphs
- Ensure smooth transitions between sections
- Avoid repetition and clichés
- Make every sentence count toward the 300-400 word target

### The Cover Letter's Role
- Complements the CV by adding personality and narrative
- Explains the "why" behind the "what" on the CV
- Demonstrates written communication skills
- Shows genuine interest and research effort
- Provides context for career transitions or gaps