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

Cover Letter Generation

ADDED Requirements

Requirement: Cover Letter Generation Command

The system SHALL provide a /write-cover-letter slash command that generates tailored cover letters based on application strategy and profile information.

Scenario: Generate from current directory

• WHEN user runs /write-cover-letter from inside an application folder
• THEN system generates cover letter for the application in current directory

Scenario: Generate with explicit application name

• WHEN user runs /write-cover-letter 2025-11-02-TechCorp-Developer
• THEN system generates cover letter for that specific application

Scenario: Handle unclear location

• WHEN user runs /write-cover-letter from a directory that is not an application folder and no parameter is provided
• THEN system lists all applications in applications/pending/ and asks user to specify which one

Scenario: Handle non-existent application

• WHEN user provides application name that doesn't exist
• THEN system shows error and lists available applications

Requirement: Automatic Validation Check

The system SHALL automatically validate the application before generating a cover letter.

Scenario: Validation passes automatically

• WHEN user runs /write-cover-letter and application validation passes
• THEN system proceeds with cover letter generation

Scenario: Validation fails automatically

• WHEN user runs /write-cover-letter and application validation fails
• THEN system shows validation errors and stops generation (does not create cover-letter.md)

Scenario: Skip validation with flag

• WHEN user runs /write-cover-letter --skip-validation and application has incomplete sections
• THEN system shows warning but proceeds with generation anyway

Scenario: Show validation progress

• WHEN validation is running
• THEN system shows progress: "🔍 Validating application..." followed by result

Requirement: Existing File Protection

The system SHALL check if cover-letter.md already exists and prevent overwriting without explicit permission.

Scenario: Cover letter already exists

• WHEN user runs /write-cover-letter and cover-letter.md already exists in application folder
• THEN system stops and shows error: "Cover letter already exists. Use --force to overwrite."

Scenario: Force overwrite with flag

• WHEN user runs /write-cover-letter --force and cover-letter.md exists
• THEN system shows warning and overwrites the file

Scenario: No existing file

• WHEN user runs /write-cover-letter and no cover-letter.md exists
• THEN system proceeds with generation without prompting

Requirement: Multi-Source Data Reading

The system SHALL read both profile.md and application.md to gather information for the cover letter.

Scenario: Read profile for applicant background

• WHEN generating cover letter
• THEN system reads profile.md to extract:
  • Personal information (name, contact)
  • Professional summary
  • Relevant work experiences (as identified in match strategy)
  • Key skills and achievements
  • Projects to highlight

Scenario: Read application for job strategy

• WHEN generating cover letter
• THEN system reads application.md to extract:
  • Organization name and job title
  • Match strategy (which experiences to emphasize)
  • Key messages to convey
  • Tone assessment (Formal/Balanced/Casual)
  • Company research and culture insights
  • Job requirements and keywords

Scenario: Handle missing profile.md

• WHEN profile.md doesn't exist or is unreadable
• THEN system shows error: "profile.md not found. Please create your profile first." and stops

Scenario: Cross-reference match strategy

• WHEN application.md has match strategy section with specific experiences to emphasize
• THEN system prioritizes those experiences from profile.md in the cover letter content

Requirement: Standard Structure Generation

The system SHALL generate cover letters with a standard 1-page structure.

Scenario: Opening paragraph with hook

• WHEN generating cover letter
• THEN opening paragraph includes:
  • Specific job title and company name
  • Brief statement of interest
  • One compelling reason for applying (from key messages or research)

Scenario: Why this role paragraph

• WHEN generating cover letter
• THEN "why this role" section includes:
  • Connection to company mission/values
  • Reference to company research insights
  • Genuine interest in the position

Scenario: What you bring paragraphs

• WHEN generating cover letter
• THEN "what you bring" sections include:
  • 2-3 most relevant experiences from match strategy
  • Specific achievements from profile.md
  • Connection to job requirements
  • Natural incorporation of keywords

Scenario: Cultural fit paragraph

• WHEN generating cover letter
• THEN cultural fit section includes:
  • Alignment of personal values with company culture
  • Reference to soft skills that match company culture indicators
  • Enthusiasm for work environment

Scenario: Closing paragraph

• WHEN generating cover letter
• THEN closing includes:
  • Strong statement of interest
  • Availability for interview
  • Professional thank you
  • Call to action

Requirement: Length and Formatting

The system SHALL generate cover letters with appropriate length and formatting.

Scenario: Target word count

• WHEN generating cover letter
• THEN system aims for 300-400 words total (approximately 1 page)

Scenario: Paragraph structure

• WHEN generating cover letter
• THEN system creates 4-5 distinct paragraphs (Opening, Why role, What you bring 1-2 paragraphs, Cultural fit, Closing)

Scenario: Professional formatting

• WHEN cover letter is generated
• THEN format includes:
  • Applicant contact information header (from profile.md)
  • Date
  • Company/recruiter address (from application.md)
  • Professional salutation
  • Body paragraphs
  • Professional sign-off

Requirement: Tone and Language

The system SHALL apply appropriate tone and language based on application.md guidance.

Scenario: Apply tone from application.md

• WHEN application.md has tone assessment of "Formal"
• THEN cover letter uses formal language, professional vocabulary, traditional business letter tone

Scenario: Apply balanced tone

• WHEN application.md has tone assessment of "Balanced"
• THEN cover letter uses professional but approachable language, moderate formality

Scenario: Apply casual tone

• WHEN application.md has tone assessment of "Casual"
• THEN cover letter uses conversational yet professional language, more personal voice

Scenario: Infer language from context

• WHEN job posting, company information, or application.md content suggests German language
• THEN cover letter is generated in German

Scenario: Default to English

• WHEN language cannot be clearly determined from context
• THEN cover letter is generated in English

Requirement: Content Quality and Authenticity

The system SHALL ensure generated content is authentic, factual, and high-quality.

Scenario: Use only real information

• WHEN generating cover letter content
• THEN system uses ONLY experiences, skills, and achievements documented in profile.md (no hallucination)

Scenario: Natural keyword incorporation

• WHEN job description has specific keywords or required skills
• THEN system incorporates them naturally in context (not as a list)

Scenario: Company-specific personalization

• WHEN application.md has research notes about company
• THEN cover letter references specific company initiatives, values, or news

Scenario: Authentic voice

• WHEN generating prose
• THEN system creates natural, human-sounding text (not obviously AI-generated)

Requirement: Success and Progress Reporting

The system SHALL provide clear feedback during the generation process.

Scenario: Show generation steps

• WHEN cover letter is being generated
• THEN system shows progress:
  • "🔍 Validating application..."
  • "📝 Generating cover letter..."
  • "✓ Read profile.md"
  • "✓ Read application.md"
  • "✓ Analyzed match strategy"
  • "✓ Generated [N] words"

Scenario: Success message

• WHEN cover letter generation completes successfully
• THEN system shows:
  • ✅ emoji and "Cover letter saved: cover-letter.md"
  • Summary (word count, tone, language, key experiences used)
  • Next steps (review, personalize, generate CV)

Scenario: Include file location

• WHEN showing success message
• THEN system includes full or relative path to cover-letter.md file

Requirement: Error Handling

The system SHALL handle errors gracefully with helpful messages.

Scenario: Missing application.md

• WHEN application folder has no application.md file
• THEN system shows error: "No application.md found. Please create application first with /new-application"

Scenario: Validation failure stops generation

• WHEN /validate-application fails with incomplete sections
• THEN system shows specific validation errors and suggests: "Fix issues or use --skip-validation to proceed anyway"

Scenario: Existing cover letter blocks generation

• WHEN cover-letter.md already exists
• THEN system shows: "Cover letter already exists. Use --force to overwrite. Warning: This will replace your existing cover letter."

Scenario: File write errors

• WHEN cover-letter.md cannot be written (permissions, disk full, etc.)
• THEN system shows clear error: "Could not save cover-letter.md: [reason]"

Requirement: Flags and Options

The system SHALL support command flags for advanced usage.

Scenario: Skip validation flag

• WHEN user provides --skip-validation flag
• THEN system skips /validate-application check and generates anyway

Scenario: Force overwrite flag

• WHEN user provides --force or --overwrite flag
• THEN system overwrites existing cover-letter.md without prompting

Scenario: Combined flags

• WHEN user provides multiple flags: /write-cover-letter --skip-validation --force
• THEN system applies both: skips validation AND overwrites existing file

Scenario: Help flag

• WHEN user runs /write-cover-letter --help
• THEN system shows usage information, available flags, and examples

Requirement: Post-Generation Guidance

The system SHALL provide clear next steps after generation.

Scenario: Review guidance

• WHEN cover letter is generated
• THEN system suggests: "Review cover-letter.md for accuracy and authenticity"

Scenario: Personalization guidance

• WHEN cover letter is generated
• THEN system suggests: "Add any additional personal insights or connections to the role"

Scenario: Next command suggestion

• WHEN cover letter is generated
• THEN system suggests next step: "Generate CV: /write-cv (coming soon)"

Requirement: Integration with Workflow

The system SHALL integrate seamlessly with existing application workflow.

Scenario: Workflow step documentation

• WHEN user checks workflow in CLAUDE.md
• THEN cover letter generation appears as Step 6 after validation

Scenario: Command availability

• WHEN user lists available commands
• THEN /write-cover-letter is documented with description and usage examples

Scenario: Consistent patterns

• WHEN using /write-cover-letter
• THEN location detection, error handling, and output format match patterns from other commands (/validate-application, /populate-application)