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

Implementation Tasks

1. Design Cover Letter Structure

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

2. Implement Location Detection

• 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
• 2.2 Handle missing or unclear location
  • Show error message
  • List available applications in applications/pending/
  • Provide usage examples
• 2.3 Verify application.md exists in target location

3. Implement Validation Gate

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

4. Implement Existing File Check

• 4.1 Check if cover-letter.md exists in application folder
• 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
• 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"
• 4.4 Proceed if no existing file

5. Implement Data Reading

• 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)
• 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)
• 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

• 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
• 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
• 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

• 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)
• 7.2 Generate salutation
  • Use recruiter name if available in application.md
  • Otherwise: "Dear Hiring Manager" (EN) or "Sehr geehrte Damen und Herren" (DE)
• 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
• 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
• 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
• 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
• 7.7 Generate closing paragraph (40-50 words)
  • Strong statement of interest
  • Availability for interview/discussion
  • Thank hiring manager
  • Professional call to action
• 7.8 Generate sign-off
  • Use appropriate closing based on language and tone
  • Include applicant name from profile.md

8. Implement Quality Checks

• 8.1 Verify word count (target: 300-400 words)
  • Count words in generated content
  • Adjust if too short (<280) or too long (>420)
• 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
• 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
• 8.4 Verify keyword incorporation
  • Check that key job requirements are mentioned
  • Ensure keywords flow naturally (not listed)
• 8.5 Verify personalization
  • Check company-specific references are included
  • Verify it doesn't sound generic

9. Implement File Writing

• 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)
• 9.2 Write to cover-letter.md in application folder
  • Create file with proper path
  • Handle write permissions errors
  • Verify file was written successfully
• 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

• 10.1 Show validation progress
  • Display: "🔍 Validating application..."
  • Show validation result
• 10.2 Show generation progress
  • Display: "📝 Generating cover letter..."
  • Show steps: "✓ Read profile.md", "✓ Read application.md", etc.
• 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

• 11.1 Design success message format
  • ✅ emoji and title
  • Summary of generation (word count, tone, language, experiences used)
  • File location
  • Next steps
• 11.2 Generate detailed summary
  • Word count achieved
  • Tone applied
  • Language used
  • Number of experiences highlighted
  • Number of key messages incorporated
• 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

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

13. Implement Command Flags

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

14. Create Slash Command File

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

15. Update Framework Documentation

• 15.1 Update src/CLAUDE.md - Add /write-cover-letter to Available Commands
• 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
• 15.3 Add usage examples
  • Generate from current directory
  • Generate with application parameter
  • Using flags (--skip-validation, --force)
• 15.4 Update "Document Standards" section
  • Add cover letter standards (structure, length, tone)
• 15.5 Add example interaction showing cover letter generation

16. Integration and Testing

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

17. Update Test Environment

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

18. Git Workflow

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