Bewerbungszauberer/openspec/changes/archive/2025-11-03-add-cover-letter-generation/proposal.md

# Proposal: Cover Letter Generation

## Why

The application management system now supports creating, populating, and validating applications, but users still must manually write their cover letters. This is time-consuming and doesn't leverage the strategic analysis already captured in `application.md`.

**Problems without automated cover letter generation:**
- Users must manually translate match strategy into compelling narrative
- Risk of inconsistency between application strategy and actual cover letter content
- Time-consuming to write personalized cover letters for each application
- May not effectively incorporate key messages and tone guidance from application.md
- Difficult to maintain consistent quality across multiple applications

**Current workflow gap:**
1. ✅ Validate profile
2. ✅ Create application
3. ✅ Populate application with job analysis
4. ✅ Validate application completeness
5. ❌ **Generate cover letter** ← Missing
6. ❌ Generate CV (future)
7. ❌ Generate application email (future)

## What

Add a `/write-cover-letter` slash command that generates tailored cover letters based on the strategic analysis in `application.md` and personal information in `profile.md`.

### Core Functionality

1. **Location Detection**: Auto-detect current application folder or accept optional application name parameter
2. **Safety Gates**:
   - Automatically run `/validate-application` before generating (stop if fails)
   - Check if `cover-letter.md` already exists (stop if exists)
   - Allow explicit overrides via flags: `--skip-validation`, `--force`/`--overwrite`
3. **Multi-source Generation**:
   - Read `profile.md` for applicant background (experience, skills, achievements)
   - Read `application.md` for job-specific strategy (match strategy, key messages, tone, company insights)
4. **Standard Structure**: Generate 1-page cover letter with:
   - **Opening**: Introduction and position reference
   - **Why This Role**: Genuine interest, company research insights
   - **What You Bring**: Relevant experience and skills (from match strategy)
   - **Cultural Fit**: Alignment with company values and culture
   - **Closing**: Strong call to action, availability
5. **Tone & Language**:
   - Use tone guidance from application.md (Formal/Balanced/Casual)
   - Infer language (German/English) from job posting context
6. **Output**: Save to `cover-letter.md` in application folder

### User Experience

```bash
# From inside application folder
cd applications/pending/2025-11-02-TechCorp-Senior-Developer
/write-cover-letter

# Or from anywhere with parameter
/write-cover-letter 2025-11-02-TechCorp-Senior-Developer

# Override safety checks
/write-cover-letter --skip-validation
/write-cover-letter --force  # Overwrite existing cover-letter.md
```

**Success flow:**
```
🔍 Validating application...
✅ Application validation passed

📝 Generating cover letter...

✓ Read profile.md (applicant background)
✓ Read application.md (job strategy)
✓ Analyzed match strategy (3 key experiences identified)
✓ Incorporated key messages
✓ Applied tone: Balanced
✓ Language: English
✓ Generated 376 words (target: 300-400)

✅ Cover letter saved: cover-letter.md

Next steps:
1. Review cover-letter.md for accuracy and authenticity
2. Personalize with any additional insights
3. Generate CV: /write-cv (coming soon)
```

**Blocked flow (validation fails):**
```
🔍 Validating application...
❌ Application validation failed

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

## Job Description Summary
- [ ] Required Skills: Missing or empty

Run /validate-application for full details, or use --skip-validation to proceed anyway (not recommended).
```

**Blocked flow (cover letter exists):**
```
❌ Cover letter already exists: cover-letter.md

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

Warning: This will overwrite your existing cover letter.
```

### Content Generation Strategy

**Opening Paragraph (Hook + Position):**
- Reference specific job title and company name
- Brief statement of interest
- One compelling reason for applying (from research notes or key messages)

**Why This Role Paragraph:**
- Connection to company mission/values (from research notes)
- Genuine interest in the role (from key messages)
- Reference to company news, projects, or initiatives

**What You Bring Paragraphs (1-2):**
- Highlight 2-3 most relevant experiences from match strategy
- Use specific achievements and quantifiable results from profile.md
- Connect experiences to job requirements
- Incorporate keywords from job description

**Cultural Fit Paragraph:**
- Align personal values with company culture (from research notes)
- Reference soft skills that match company culture indicators
- Show enthusiasm for work environment or team

**Closing Paragraph:**
- Strong statement of interest
- Availability for interview
- Thank you and call to action
- Professional sign-off

**Quality Standards:**
- Length: 300-400 words (1 page)
- Tone: Match application.md tone assessment
- Language: Inferred from job posting
- Authenticity: Use real experiences from profile.md only
- Keywords: Incorporate naturally from job description
- Personalization: Reference company-specific insights

## Impact

### Benefits
- **Time savings**: Reduce cover letter writing from 1-2 hours to 10-15 minutes (review/refinement)
- **Consistency**: Ensures cover letter aligns with application strategy
- **Quality**: Leverages strategic analysis already done in application.md
- **Personalization**: Each cover letter tailored to specific job and company
- **Completeness**: Addresses all key messages identified in planning phase
- **ATS optimization**: Natural incorporation of keywords from job description

### Changes Required
- New slash command: `/write-cover-letter`
- Documentation updates in `src/CLAUDE.md`
- No changes to existing commands or templates

### User Workflow Impact

**Updated workflow:**
```
1. Validate profile (/validate-profile)
2. Initialize application (/new-application)
3. Add documents to input/ folder
4. Populate application (/populate-application)
5. Validate application (/validate-application)
6. **Generate cover letter (/write-cover-letter)** ← NEW
7. Review and refine cover-letter.md manually
8. Generate CV (future: /write-cv)
9. Generate email (future: /write-email)
```

### Risks & Mitigations

**Risk**: Generated cover letters may sound generic or AI-written
**Mitigation**:
- Use authentic experiences from profile.md only
- Incorporate company-specific research from application.md
- Apply appropriate tone from tone assessment
- Encourage manual review and personalization

**Risk**: Overwriting existing work
**Mitigation**:
- Check for existing cover-letter.md and stop
- Require explicit `--force` flag to overwrite
- Warn user about overwrite consequences

**Risk**: Generating from incomplete application
**Mitigation**:
- Auto-run /validate-application before generation
- Stop if validation fails (unless `--skip-validation`)
- Clear error messages about what needs to be fixed

## Implementation Approach

**Pattern consistency:**
- Follow same location detection as `/validate-application`
- Match command structure and error handling patterns
- Use consistent validation and safety check patterns

**Data sources:**
- Primary: application.md (match strategy, key messages, tone, research)
- Secondary: profile.md (experience, skills, achievements)
- Tertiary: Job description from input/ (if needed for additional context)

**Generation approach:**
- Use Claude to generate human-quality prose
- Maintain factual accuracy (no hallucination)
- Balance structure with natural flow
- Target specific word count (300-400 words)

**Future integration:**
- Cover letter generation is first of three document commands
- Pattern will be reused for `/write-cv` and `/write-email`
- Consider unified template system for all document types