Bewerbungszauberer/openspec/changes/archive/2025-11-03-add-application-validation/proposal.md

Proposal: Application Validation

Why

Currently, users can create and populate applications using /new-application and /populate-application, but there's no validation mechanism to ensure the application.md files are complete before generating professional documents (CV, cover letter, email).

Problems without validation:

• Users might try to generate documents with placeholder text like [To be filled] still present
• Incomplete job information could lead to poorly targeted applications
• No quality gate to catch missing critical information before document generation
• Users might forget to run /populate-application after adding input documents

Similar to /validate-profile, we need a validation command that acts as a quality gate, ensuring application.md files are ready for document generation.

What

Add a /validate-application slash command that validates the completeness of application.md files.

Core Functionality

1. Auto-detection: When run without parameters, detect if current directory is inside an application folder
2. Explicit path: Accept optional application folder name/path as parameter
3. Required section validation: Check that critical sections are filled (Organization Info, Job Info, Job Description Summary)
4. Placeholder detection: Identify unfilled template placeholders like [To be filled], [...], bracket patterns
5. Population awareness: Warn if input/ folder is empty or application seems unpopulated
6. Binary pass/fail: Clear ✅ PASSED or ❌ FAILED status (consistent with /validate-profile)
7. Actionable errors: Show specific issues with quoted placeholder text and guidance on how to fix

Optional Sections

These can remain incomplete without causing validation failure:

• Match Strategy
• Key Messages
• Tone of Voice
• Research Notes
• Document Checklist

User Experience

# Run from inside application folder
cd applications/pending/2025-11-02-TechCorp-Senior-Developer
/validate-application

# Or provide path from anywhere
/validate-application 2025-11-02-TechCorp-Senior-Developer

Success output:

✅ Application Validation: PASSED

Your application is complete and ready for document generation!

Summary:
- Organization: TechCorp
- Position: Senior Developer
- Job requirements: 12 identified
- Match strategy: Complete
- Input documents: 3 files analyzed

You can now proceed with generating tailored CV, cover letter, and application email.

Failure output:

❌ Application Validation: FAILED

Your application has incomplete sections that need attention.

Issues found:

## Organization Information
- [ ] Organization Name: Contains placeholder "[To be filled]"

## Job Description Summary
- [ ] Responsibilities: No responsibilities documented
- [ ] Required Skills: Contains placeholder "[List required skills]"

## Population Status
⚠️  Input folder appears empty. Consider:
1. Adding job posting and related documents to input/
2. Running /populate-application to extract information

Please update application.md, then run /validate-application again.

Impact

Benefits

• Quality gate: Prevents generating documents with placeholder text
• User guidance: Clear feedback on what's missing and how to fix it
• Workflow integration: Natural step before document generation
• Consistency: Matches /validate-profile pattern users already know
• Error prevention: Catches incomplete applications early

Changes Required

• New slash command: /validate-application
• Documentation updates in src/CLAUDE.md
• No changes to existing commands or templates

User Workflow Update

1. Validate profile (/validate-profile)
2. Initialize application (/new-application)
3. Add documents to input/ folder
4. Populate application (/populate-application)
5. **Validate application (/validate-application)** ← NEW
6. Generate documents (future: CV, cover letter, email)

Implementation Approach

Follow the same pattern as /validate-profile:

• Read application.md and parse sections
• Check for bracket patterns: \[([^\]]+)\]
• Validate required sections have real content
• Check input/ folder exists and has files
• Provide structured, actionable error messages
• Use encouraging tone and clear next steps