Files

T

gurixandClaude Sonnet 4.5 01b7d5b7a9 fix: use explicit relative path for swiss-letter.tex template

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>

2026-01-12 21:47:20 +01:00

6.7 KiB

Raw Blame History

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

6.7 KiB Raw Blame History