Bewerbungszauberer/openspec/specs/cover-letter-generation/spec.md

# cover-letter-generation Specification

## Purpose
TBD - created by archiving change add-cover-letter-generation. Update Purpose after archive.
## 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)