Bewerbungszauberer/openspec/specs/cover-letter-pdf-conversion/spec.md

# cover-letter-pdf-conversion Specification

## Purpose
TBD - created by archiving change add-cover-letter-pdf-conversion. Update Purpose after archive.
## Requirements
### Requirement: Cover Letter Detection

The system SHALL detect the presence of a valid cover letter markdown file in the current directory before attempting conversion.

#### Scenario: Valid cover letter found
- **WHEN** a file named `cover-letter.md` exists in the current directory
- **AND** the file contains valid markdown with frontmatter
- **THEN** the system proceeds with conversion

#### Scenario: No cover letter found
- **WHEN** no `cover-letter.md` file exists in the current directory
- **THEN** the system displays an error message indicating no cover letter was found
- **AND** suggests running `/write-cover-letter` first

#### Scenario: Invalid cover letter format
- **WHEN** `cover-letter.md` exists but lacks required frontmatter fields
- **THEN** the system displays an error listing the missing required fields
- **AND** provides an example of correct frontmatter structure

### Requirement: Environment Validation

The system SHALL validate that all required tools are installed before attempting conversion.

#### Scenario: All tools available
- **WHEN** the user runs `/convert-cover-letter`
- **AND** Pandoc is installed and accessible
- **AND** LaTeX (pdflatex) is installed and accessible
- **THEN** the system proceeds with conversion

#### Scenario: Pandoc missing
- **WHEN** the user runs `/convert-cover-letter`
- **AND** Pandoc is not installed
- **THEN** the system displays installation instructions for Pandoc
- **AND** provides platform-specific commands (apt, brew, etc.)
- **AND** stops the conversion process

#### Scenario: LaTeX missing
- **WHEN** the user runs `/convert-cover-letter`
- **AND** Pandoc is installed but LaTeX is not installed
- **THEN** the system displays installation instructions for LaTeX packages
- **AND** lists required packages (texlive-latex-base, texlive-lang-german, texlive-latex-extra)
- **AND** stops the conversion process

### Requirement: Swiss Letter Formatting

The system SHALL generate PDFs using Swiss business letter standards (scrlttr2 with SN configuration).

#### Scenario: Address window positioning
- **WHEN** converting a cover letter to PDF
- **THEN** the recipient address is positioned according to Swiss Norm (SN)
- **AND** fits within standard Swiss envelope window dimensions

#### Scenario: Swiss German formatting
- **WHEN** the cover letter content contains German text
- **THEN** Swiss German hyphenation rules are applied
- **AND** date formatting follows Swiss convention (DD.MM.YYYY)
- **AND** number formatting uses Swiss conventions

#### Scenario: Professional layout
- **WHEN** converting to PDF
- **THEN** the output includes proper margins for Swiss business letters
- **AND** sender information is positioned in the header
- **AND** contact information (phone, email) is formatted with hyperlinks

### Requirement: Metadata Extraction

The system SHALL extract metadata from markdown frontmatter and map it to LaTeX variables.

#### Scenario: Complete frontmatter
- **WHEN** the markdown contains all required frontmatter fields
- **THEN** sender information (name, street, city, phone, email) is extracted
- **AND** recipient address lines are extracted
- **AND** letter details (date, subject, opening, closing, signature) are extracted
- **AND** optional enclosures list is extracted if present

#### Scenario: Minimal frontmatter
- **WHEN** the markdown contains only required frontmatter fields
- **THEN** the system uses default values for optional fields
- **AND** generates a valid PDF without enclosures section

#### Scenario: Invalid frontmatter structure
- **WHEN** the frontmatter cannot be parsed as YAML
- **THEN** the system displays a clear error message
- **AND** points to the specific syntax error if possible

### Requirement: PDF Generation

The system SHALL convert the markdown body to PDF using Pandoc with the Swiss letter template.

#### Scenario: Successful conversion
- **WHEN** all prerequisites are met
- **AND** the markdown is valid
- **THEN** the system generates a PDF file in the same directory
- **AND** names the file `cover-letter.pdf`
- **AND** displays a success message with the file path

#### Scenario: Conversion with enclosures
- **WHEN** the frontmatter includes an `enclosures` list
- **THEN** the generated PDF includes an enclosures section after the closing
- **AND** lists each enclosure item on a separate line

#### Scenario: LaTeX compilation error
- **WHEN** Pandoc generates LaTeX but pdflatex fails to compile
- **THEN** the system displays the LaTeX error output
- **AND** suggests checking for special characters or formatting issues
- **AND** preserves the intermediate .tex file for debugging

### Requirement: Template Management

The system SHALL provide and maintain the Swiss letter LaTeX template.

#### Scenario: Template availability
- **WHEN** the `/convert-cover-letter` command is run
- **THEN** the system uses the template at `src/.claude/templates/swiss-letter.tex`
- **AND** passes it to Pandoc via the `--template` option

#### Scenario: Template customization
- **WHEN** users need to modify letter styling
- **THEN** they can edit the swiss-letter.tex template
- **AND** changes apply to all subsequent conversions
- **AND** the template includes comments explaining customizable sections

### Requirement: Error Handling

The system SHALL provide clear, actionable error messages for common failure scenarios.

#### Scenario: File permission error
- **WHEN** the PDF cannot be written due to permissions
- **THEN** the system displays a permission error message
- **AND** suggests checking directory write permissions

#### Scenario: Disk space error
- **WHEN** PDF generation fails due to insufficient disk space
- **THEN** the system displays a disk space error
- **AND** suggests freeing up space or choosing a different output location

#### Scenario: Process timeout
- **WHEN** LaTeX compilation takes longer than 30 seconds
- **THEN** the system displays a timeout warning
- **AND** suggests checking for complex formatting or large embedded content