145 lines
6.0 KiB
Markdown
145 lines
6.0 KiB
Markdown
 
|
# Cover Letter PDF Conversion Specification
|
||
|
|
|
||
|
|
## ADDED 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
|