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

# Implementation Tasks

## 1. Design Cover Letter Structure

- [x] 1.1 Define standard cover letter sections and order
- [x] 1.2 Determine word count targets for each section
- [x] 1.3 Design template structure for German vs English letters
- [x] 1.4 Define tone variations (Formal/Balanced/Casual) and language patterns
- [x] 1.5 Create examples of good opening hooks, closing statements

## 2. Implement Location Detection

- [x] 2.1 Reuse location detection pattern from `/validate-application`
  - Check current directory for application folder pattern
  - Accept optional application name parameter
  - Resolve parameter to full application path
- [x] 2.2 Handle missing or unclear location
  - Show error message
  - List available applications in `applications/pending/`
  - Provide usage examples
- [x] 2.3 Verify application.md exists in target location

## 3. Implement Validation Gate

- [x] 3.1 Auto-run `/validate-application` before generation
  - Execute validation command programmatically
  - Capture validation result (pass/fail)
  - Show validation progress: "🔍 Validating application..."
- [x] 3.2 Handle validation failure
  - Stop generation if validation fails
  - Show validation error details
  - Suggest fixing issues or using `--skip-validation` flag
- [x] 3.3 Implement `--skip-validation` flag
  - Parse flag from command arguments
  - Skip validation check if flag present
  - Show warning: "Skipping validation (not recommended)"
- [x] 3.4 Handle validation success
  - Show success message: "✅ Application validation passed"
  - Proceed to generation

## 4. Implement Existing File Check

- [x] 4.1 Check if `cover-letter.md` exists in application folder
- [x] 4.2 Handle existing file (stop generation)
  - Show error: "Cover letter already exists"
  - Suggest using `--force` flag to overwrite
  - Include file path in error message
- [x] 4.3 Implement `--force` / `--overwrite` flag
  - Parse flag from command arguments
  - Skip existing file check if flag present
  - Show warning: "Overwriting existing cover-letter.md"
- [x] 4.4 Proceed if no existing file

## 5. Implement Data Reading

- [x] 5.1 Read profile.md
  - Check if profile.md exists
  - Parse personal information section
  - Parse professional summary
  - Parse work experience entries
  - Parse skills and achievements
  - Parse projects section
  - Handle missing or corrupted profile.md (error and stop)
- [x] 5.2 Read application.md
  - Check if application.md exists
  - Parse organization information (company name, location)
  - Parse job information (job title, level)
  - Parse job description summary (requirements, responsibilities)
  - Parse match strategy section
  - Parse key messages section
  - Parse tone of voice section
  - Parse research notes section
  - Handle missing or corrupted application.md (error and stop)
- [x] 5.3 Cross-reference match strategy with profile
  - Identify experiences to emphasize from match strategy
  - Extract those specific experiences from profile.md
  - Identify skills to highlight
  - Identify projects to mention

## 6. Implement Tone and Language Detection

- [x] 6.1 Extract tone assessment from application.md
  - Find "Tone of Voice" section
  - Parse tone value (Formal/Balanced/Casual)
  - Default to "Balanced" if not specified
- [x] 6.2 Infer language from context
  - Check job posting language indicators
  - Check company location (German companies likely want German)
  - Check if application.md is written in German
  - Default to English if unclear
- [x] 6.3 Define language-specific formatting
  - German: "Sehr geehrte Damen und Herren" / "Mit freundlichen Grüßen"
  - English: "Dear Hiring Manager" / "Sincerely"
  - Date formats (DE: DD.MM.YYYY, EN: Month DD, YYYY)

## 7. Implement Content Generation

- [x] 7.1 Generate contact header
  - Use applicant name, email, phone from profile.md
  - Format address block
  - Add date (current date)
  - Add company address (from application.md)
- [x] 7.2 Generate salutation
  - Use recruiter name if available in application.md
  - Otherwise: "Dear Hiring Manager" (EN) or "Sehr geehrte Damen und Herren" (DE)
- [x] 7.3 Generate opening paragraph (50-70 words)
  - Reference job title and company name
  - State interest in the position
  - Include one compelling hook (from key messages or research)
  - Maintain appropriate tone
- [x] 7.4 Generate "why this role" paragraph (70-90 words)
  - Reference company research insights
  - Connect to company values or mission
  - Show genuine interest based on key messages
  - Reference company-specific news or initiatives if available
- [x] 7.5 Generate "what you bring" content (120-150 words, 1-2 paragraphs)
  - Highlight 2-3 experiences from match strategy
  - Use specific achievements from profile.md
  - Connect experiences to job requirements
  - Incorporate keywords naturally
  - Use quantifiable results when available
- [x] 7.6 Generate cultural fit paragraph (50-70 words)
  - Reference company culture insights from research notes
  - Align personal values with company values
  - Mention relevant soft skills
  - Show enthusiasm for work environment
- [x] 7.7 Generate closing paragraph (40-50 words)
  - Strong statement of interest
  - Availability for interview/discussion
  - Thank hiring manager
  - Professional call to action
- [x] 7.8 Generate sign-off
  - Use appropriate closing based on language and tone
  - Include applicant name from profile.md

## 8. Implement Quality Checks

- [x] 8.1 Verify word count (target: 300-400 words)
  - Count words in generated content
  - Adjust if too short (<280) or too long (>420)
- [x] 8.2 Verify factual accuracy
  - Ensure all experiences mentioned exist in profile.md
  - Ensure all company information matches application.md
  - No hallucinated facts or achievements
- [x] 8.3 Verify tone consistency
  - Check language matches tone assessment
  - Formal: professional vocabulary, traditional structure
  - Balanced: mix of professional and approachable
  - Casual: conversational but still professional
- [x] 8.4 Verify keyword incorporation
  - Check that key job requirements are mentioned
  - Ensure keywords flow naturally (not listed)
- [x] 8.5 Verify personalization
  - Check company-specific references are included
  - Verify it doesn't sound generic

## 9. Implement File Writing

- [x] 9.1 Format cover letter as markdown
  - Use proper heading hierarchy
  - Format contact information block
  - Format body paragraphs with spacing
  - Include metadata comment (generated date, sources)
- [x] 9.2 Write to cover-letter.md in application folder
  - Create file with proper path
  - Handle write permissions errors
  - Verify file was written successfully
- [x] 9.3 Add metadata comment at top
  - Include generation date/time
  - Note sources used (profile.md, application.md)
  - Include word count
  - Note tone and language used

## 10. Implement Progress Reporting

- [x] 10.1 Show validation progress
  - Display: "🔍 Validating application..."
  - Show validation result
- [x] 10.2 Show generation progress
  - Display: "📝 Generating cover letter..."
  - Show steps: "✓ Read profile.md", "✓ Read application.md", etc.
- [x] 10.3 Show completion status
  - Display: "✓ Analyzed match strategy ([N] key experiences identified)"
  - Display: "✓ Incorporated key messages"
  - Display: "✓ Applied tone: [tone]"
  - Display: "✓ Language: [language]"
  - Display: "✓ Generated [N] words (target: 300-400)"

## 11. Implement Success Output

- [x] 11.1 Design success message format
  - ✅ emoji and title
  - Summary of generation (word count, tone, language, experiences used)
  - File location
  - Next steps
- [x] 11.2 Generate detailed summary
  - Word count achieved
  - Tone applied
  - Language used
  - Number of experiences highlighted
  - Number of key messages incorporated
- [x] 11.3 Provide next steps
  - Suggest reviewing cover-letter.md
  - Suggest personalizing with additional insights
  - Suggest next command (generate CV when available)

## 12. Implement Error Handling

- [x] 12.1 Handle missing profile.md
  - Show error: "profile.md not found"
  - Suggest running /validate-profile first
  - Stop generation
- [x] 12.2 Handle missing application.md
  - Show error: "No application.md found"
  - Suggest creating application with /new-application
  - Stop generation
- [x] 12.3 Handle validation failure
  - Show validation errors
  - Stop generation unless --skip-validation
  - Provide guidance on fixing issues
- [x] 12.4 Handle existing cover-letter.md
  - Show error with file path
  - Suggest --force flag to overwrite
  - Stop generation unless --force provided
- [x] 12.5 Handle file write errors
  - Show clear error message with reason
  - Suggest checking permissions or disk space
- [x] 12.6 Handle corrupted data files
  - Catch parsing errors
  - Show helpful error message
  - Identify which file is corrupted

## 13. Implement Command Flags

- [x] 13.1 Parse --skip-validation flag
  - Check command arguments for flag
  - Set validation skip flag if present
- [x] 13.2 Parse --force / --overwrite flag
  - Check command arguments for flag
  - Set overwrite flag if present
- [x] 13.3 Parse --help flag
  - Check for --help flag
  - Show usage information, available flags, examples
  - Exit without generating
- [x] 13.4 Handle combined flags
  - Support multiple flags in single command
  - Process each flag appropriately

## 14. Create Slash Command File

- [x] 14.1 Create `src/.claude/commands/write-cover-letter.md`
- [x] 14.2 Document location detection logic
- [x] 14.3 Document validation gate behavior
- [x] 14.4 Document existing file check
- [x] 14.5 Document data reading from profile.md and application.md
- [x] 14.6 Document content generation strategy
  - Opening paragraph structure
  - Why this role paragraph
  - What you bring paragraphs
  - Cultural fit paragraph
  - Closing paragraph
- [x] 14.7 Document tone and language handling
- [x] 14.8 Document word count targets and quality checks
- [x] 14.9 Document available flags (--skip-validation, --force, --help)
- [x] 14.10 Include output format examples (success, errors)
- [x] 14.11 Document edge cases and error handling

## 15. Update Framework Documentation

- [x] 15.1 Update `src/CLAUDE.md` - Add `/write-cover-letter` to Available Commands
- [x] 15.2 Update workflow section
  - Change Step 6 from "Content Generation (FUTURE)" to actual cover letter generation
  - Add detailed workflow step for cover letter generation
- [x] 15.3 Add usage examples
  - Generate from current directory
  - Generate with application parameter
  - Using flags (--skip-validation, --force)
- [x] 15.4 Update "Document Standards" section
  - Add cover letter standards (structure, length, tone)
- [x] 15.5 Add example interaction showing cover letter generation

## 16. Integration and Testing

- [x] 16.1 Test from inside application folder (no parameter)
- [x] 16.2 Test with application name parameter
- [x] 16.3 Test from wrong location (should list applications)
- [x] 16.4 Test automatic validation (passing)
- [x] 16.5 Test automatic validation (failing) - should stop
- [x] 16.6 Test --skip-validation flag
- [x] 16.7 Test existing cover-letter.md (should stop)
- [x] 16.8 Test --force flag to overwrite
- [x] 16.9 Test with complete application (should generate successfully)
- [x] 16.10 Test tone variations (Formal, Balanced, Casual)
- [x] 16.11 Test language detection (German vs English)
- [x] 16.12 Test word count (should be 300-400 words)
- [x] 16.13 Test personalization (company-specific references)
- [x] 16.14 Test factual accuracy (only uses profile.md info)
- [x] 16.15 Test missing profile.md
- [x] 16.16 Test missing application.md
- [x] 16.17 Validate proposal: `openspec validate add-cover-letter-generation --strict`

## 17. Update Test Environment

- [x] 17.1 Copy new `/write-cover-letter` command to test directory
- [x] 17.2 Update `CLAUDE.md` in test directory
- [x] 17.3 Preserve test directory's `profile.md` and `applications/` folder
- [x] 17.4 Test in actual test environment with real application

## 18. Git Workflow

- [x] 18.1 Verify all changes are on feature branch `feature/cover-letter-generation`
- [x] 18.2 Stage all files (OpenSpec proposal, slash command, documentation updates)
- [x] 18.3 Create descriptive commit message following conventional commits format
- [x] 18.4 Merge feature branch into main
- [x] 18.5 Verify final state