Bewerbungszauberer/openspec/changes/add-readme/specs/user-documentation/spec.md

user-documentation Specification

Purpose

Provide user-facing documentation that enables new users to set up and use the Job Application Framework effectively.

ADDED Requirements

Requirement: Repository README

The system SHALL provide a README.md file in the repository root that documents setup, configuration, and usage.

Scenario: README exists in root

• WHEN user clones or downloads the repository
• THEN README.md is present in the root directory
• AND is immediately visible on GitHub/GitLab repository page

Scenario: README is readable

• WHEN user opens README.md
• THEN content is formatted in clear markdown
• AND uses headings, lists, and code blocks for readability

Requirement: Framework Introduction

The system documentation SHALL provide a brief description of the framework's purpose and capabilities.

Scenario: Purpose statement

• WHEN user reads the README introduction
• THEN they understand the framework helps with job application document generation
• AND understand it uses Claude Code as the AI agent
• AND understand it works with markdown files and slash commands

Scenario: Feature overview

• WHEN user reads the features section
• THEN they see a list of implemented capabilities:
  • Application management (workspaces)
  • Profile validation
  • Cover letter generation
  • PDF conversion (Swiss format)
  • Application email generation

Requirement: Prerequisites Documentation

The system documentation SHALL list all prerequisites required before users can use the framework.

Scenario: Claude Code requirement

• WHEN user checks prerequisites
• THEN documentation states Claude Code must be installed
• AND provides link or reference to Claude Code installation

Scenario: System requirements for PDF conversion

• WHEN user checks prerequisites for PDF features
• THEN documentation mentions Pandoc and LaTeX requirements
• AND notes these are optional (only needed for /convert-cover-letter)

Requirement: Setup Instructions

The system documentation SHALL provide step-by-step setup instructions.

Scenario: Initial setup steps

• WHEN user follows setup instructions
• THEN instructions include:
  1. Install Claude Code (prerequisite)
  2. Create working directory (e.g., "my-applications")
  3. Copy contents of src/ directory to working directory
  4. Navigate to working directory in terminal

Scenario: Profile configuration step

• WHEN user reaches profile setup in instructions
• THEN documentation instructs them to fill out profile.md
• AND explains profile.md contains personal and professional information
• AND provides shortcut: create subdirectory with existing CV/docs and ask Claude to help populate profile

Scenario: Profile shortcut explanation

• WHEN user wants help filling out profile
• THEN documentation suggests:
  • Create subdirectory (e.g., "documents/")
  • Add existing CVs, certificates, portfolio materials
  • Prompt Claude: "Please read all documents in documents/ and help me fill out profile.md"
• AND explains Claude will extract and structure information automatically

Requirement: Workflow Documentation

The system documentation SHALL document the complete application workflow with all implemented slash commands.

Scenario: Command reference

• WHEN user reviews available commands
• THEN documentation lists each implemented slash command:
  • /validate-profile - Check profile completeness
  • /new-application "Company - Job Title" - Create application workspace
  • /populate-application - Analyze job documents and generate strategy
  • /validate-application - Verify application readiness
  • /write-cover-letter - Generate tailored cover letter
  • /convert-cover-letter - Convert to Swiss format PDF
  • /write-application-email - Generate professional application email

Scenario: Complete workflow example

• WHEN user reads workflow section
• THEN documentation provides end-to-end example:
  1. Validate profile
  2. Create new application
  3. Add job posting to input/ folder
  4. Populate application with analysis
  5. Review and refine application.md
  6. Validate application
  7. Generate cover letter
  8. Convert cover letter to PDF
  9. Add PDF and CV to attachments/
  10. Generate application email
  11. Review and send

Scenario: Command usage examples

• WHEN user reads about a specific command
• THEN documentation includes:
  • Command syntax with parameters
  • Example usage with realistic values
  • Expected output or result
  • Common flags (--force, --skip-validation)

Requirement: Quick Start Guide

The system documentation SHALL provide a condensed quick start guide for experienced users.

Scenario: Minimal setup path

• WHEN user follows quick start
• THEN guide shows fastest path to first application:
  1. Copy src/ to working directory
  2. Fill out profile.md
  3. Run /new-application "Company - Role"
  4. Add job posting to input/
  5. Run /populate-application
  6. Run /write-cover-letter

Scenario: Quick start assumptions

• WHEN quick start is presented
• THEN it assumes user has Claude Code installed
• AND assumes basic familiarity with terminal/CLI

Requirement: Directory Structure Documentation

The system documentation SHALL explain the directory structure users will work with.

Scenario: Working directory structure

• WHEN user reviews directory structure
• THEN documentation shows example structure:

my-applications/
├── profile.md (your information)
├── CLAUDE.md (AI instructions)
├── .claude/
│   ├── commands/ (slash commands)
│   └── templates/
└── applications/
    └── pending/
        └── 2025-11-10-Company-Role/
            ├── application.md (strategy)
            ├── input/ (job posting, etc.)
            ├── cover-letter.md
            ├── application-email.md
            └── attachments/ (PDFs, CV)

Scenario: Folder purpose explanation

• WHEN user reads about directory structure
• THEN documentation explains purpose of each key folder:
  • profile.md - User's professional profile (single source of truth)
  • applications/pending/ - Active job applications
  • input/ - Job postings and research materials
  • attachments/ - Final PDFs ready to send

Requirement: Troubleshooting Section

The system documentation SHALL provide troubleshooting guidance for common issues.

Scenario: Profile validation failures

• WHEN user encounters profile validation errors
• THEN documentation explains common issues:
  • Incomplete required sections
  • Placeholder text remaining
• AND suggests running /validate-profile to identify issues

Scenario: PDF conversion issues

• WHEN user has PDF conversion problems
• THEN documentation references:
  • Pandoc installation requirements
  • LaTeX installation requirements
  • Links to /convert-cover-letter command documentation in CLAUDE.md

Requirement: No Unimplemented Features

The system documentation SHALL NOT reference features that are not implemented.

Scenario: Only implemented commands

• WHEN documentation lists available commands
• THEN it includes only commands that exist in src/.claude/commands/
• AND does not mention planned but unimplemented features

Scenario: No CV generation workflow

• WHEN documentation describes workflow
• THEN it does NOT include automated CV generation steps
• AND assumes user provides their own CV file to attachments/

Scenario: Honest feature status

• WHEN documentation mentions future features
• THEN they are clearly marked as "Coming soon" or "Planned"
• AND not included in main workflow instructions

Requirement: Practical Examples

The system documentation SHALL use realistic examples that reflect actual usage.

Scenario: Example company and job title

• WHEN documentation shows command examples
• THEN uses realistic company names and job titles
• AND shows actual command syntax (e.g., /new-application "TechCorp - Senior Developer")

Scenario: Example workflow narrative

• WHEN documentation walks through complete workflow
• THEN uses consistent example throughout:
  • Applying to specific company
  • Using actual job title
  • Showing realistic file contents where helpful

Requirement: Accessibility

The system documentation SHALL be accessible to users with varying technical backgrounds.

Scenario: Clear language

• WHEN user reads documentation
• THEN language is clear and jargon-free
• AND technical terms are explained when first introduced

Scenario: Progressive detail

• WHEN documentation presents information
• THEN starts with high-level overview
• AND provides detailed steps afterward
• AND allows users to skip to sections relevant to them

Requirement: Maintenance Notes

The system documentation SHALL include guidance on keeping the profile updated.

Scenario: Profile maintenance reminder

• WHEN user completes initial setup
• THEN documentation reminds them to keep profile.md current
• AND suggests updating after new projects, certifications, or role changes

Scenario: Framework updates

• WHEN documentation discusses framework usage
• THEN mentions that src/ directory contains the framework source
• AND notes updates should be applied by copying updated src/ files (with care not to overwrite user data)