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

# 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