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)