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