gurixandClaude Sonnet 4.5
01b7d5b7a9
The /convert-cover-letter command was using a placeholder syntax [path-to-swiss-letter.tex] which caused inconsistent template discovery. Claude Code would sometimes skip the template or fail to find it, resulting in cover letters using Pandoc's default template instead of Swiss Norm formatting. This fix replaces the placeholder with an explicit relative path (../../../src/.claude/templates/swiss-letter.tex) that reliably resolves from the typical execution location (applications/pending/[job-folder]/) to the project root and then to the template directory. Changes: - Updated src/.claude/commands/convert-cover-letter.md with explicit template path - Enhanced specification with template path resolution requirement - Added clarification about path resolution relative to execution location Testing: - Verified PDF generation with Swiss letter template from application folders - Confirmed consistent template discovery across different working directories - Validated Swiss Norm formatting (address window positioning, KOMA-Script) Related: openspec/changes/fix-coverletter-template-path Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
154 lines
6.7 KiB
Markdown
154 lines
6.7 KiB
Markdown
# 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 with explicit path resolution to ensure consistent template usage across all execution contexts.
|
|
|
|
#### 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** the path is specified explicitly relative to the typical execution location
|
|
- **AND** passes it to Pandoc via the `--template` option with the full relative path
|
|
|
|
#### Scenario: Template path resolution
|
|
- **WHEN** converting a cover letter from an application folder location (`applications/pending/[job-folder]/`)
|
|
- **THEN** the template path `../../../src/.claude/templates/swiss-letter.tex` is used
|
|
- **AND** the path goes up three levels to the project root and then to the template directory
|
|
- **AND** the explicit path ensures consistent template discovery regardless of execution context
|
|
|
|
#### Scenario: Template customization
|
|
- **WHEN** users need to modify letter styling
|
|
- **THEN** they can edit the swiss-letter.tex template at `src/.claude/templates/swiss-letter.tex`
|
|
- **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
|
|
|