gurix/Bewerbungszauberer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add application validation command

Browse Source 
Add /validate-application slash command to ensure application.md files
are complete before document generation. Validates required sections
(Organization Info, Job Info, Job Description), detects placeholders
like [To be filled], warns if input/ folder is empty, and provides
structured pass/fail output consistent with /validate-profile.

This acts as a quality gate in the application workflow, preventing
placeholder text from appearing in generated documents.

OpenSpec: add-application-validation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
gurix
2025-11-02 21:00:05 +01:00
co-authored by Claude
parent f1ba0dd98d
commit 2b13cc4e69
6 changed files with 949 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
openspec/changes/add-application-validation/proposal.md
+120
View File
@@ -0,0 +1,120 @@
# 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
```bash
# 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
openspec/changes/add-application-validation/specs/application-validation/spec.md
+223
View File
@@ -0,0 +1,223 @@
# Application Validation
## ADDED Requirements
### Requirement: Application Validation Command
The system SHALL provide a `/validate-application` slash command that validates application.md completeness before document generation.
#### Scenario: Validate from current directory
- **WHEN** user runs `/validate-application` from inside an application folder (e.g., `applications/pending/2025-11-02-TechCorp-Developer/`)
- **THEN** system validates the `application.md` file in the current directory
#### Scenario: Validate with explicit path
- **WHEN** user runs `/validate-application 2025-11-02-TechCorp-Developer`
- **THEN** system validates `applications/pending/2025-11-02-TechCorp-Developer/application.md`
#### Scenario: Handle invalid location without parameter
- **WHEN** user runs `/validate-application` from a directory that is not an application folder
- **THEN** system displays error message and lists available applications in `applications/pending/`
#### Scenario: Handle non-existent application with parameter
- **WHEN** user runs `/validate-application non-existent-app`
- **THEN** system displays error that application doesn't exist and lists available applications
#### Scenario: Handle missing application.md
- **WHEN** validation target directory exists but has no `application.md` file
- **THEN** system displays error: "No application.md found. This doesn't appear to be a valid application folder."
### Requirement: Required Section Validation
The validation SHALL check that required sections contain real content, not placeholders.
#### Scenario: Organization Information is required
- **WHEN** Organization Information section contains placeholders like `[To be filled]` or `[Organization name]`
- **THEN** validation fails with specific error: "Organization Name: Contains placeholder '[To be filled]'"
#### Scenario: Job Title is required
- **WHEN** Job Information section has placeholder job title like `[Job Title]`
- **THEN** validation fails with specific error: "Job Title: Contains placeholder '[Job Title]'"
#### Scenario: Job Description Summary must have content
- **WHEN** Job Description Summary section is empty or only contains placeholder text
- **THEN** validation fails with error: "Job Description Summary: No content found"
#### Scenario: At least some job requirements documented
- **WHEN** Responsibilities, Required Skills, or other job description subsections all contain only placeholders
- **THEN** validation fails with error listing which subsections need content
#### Scenario: Partial completion is acceptable
- **WHEN** Organization Name and Job Title are filled, and at least one job description subsection has real content
- **THEN** validation passes even if other optional fields have placeholders
### Requirement: Optional Section Handling
The validation SHALL NOT fail for incomplete optional sections.
#### Scenario: Match Strategy is optional
- **WHEN** Match Strategy section contains placeholders or is empty
- **THEN** validation does not fail (this section is optional)
#### Scenario: Key Messages is optional
- **WHEN** Key Messages section contains placeholders
- **THEN** validation does not fail
#### Scenario: Tone of Voice is optional
- **WHEN** Tone of Voice section is empty or has placeholders
- **THEN** validation does not fail
#### Scenario: Research Notes is optional
- **WHEN** Research Notes section is empty
- **THEN** validation does not fail (user may not have research yet)
### Requirement: Placeholder Detection
The validation SHALL detect various placeholder patterns.
#### Scenario: Detect square bracket placeholders
- **WHEN** content contains `[To be filled]`, `[Organization name]`, `[Any text]`
- **THEN** system identifies these as placeholders
#### Scenario: Detect generic template text
- **WHEN** content contains unchanged template phrases like "Add organization information here"
- **THEN** system identifies these as incomplete
#### Scenario: Allow legitimate brackets
- **WHEN** content contains legitimate bracket uses like `[PhD]` in a name or `[Acquired by X]` in context
- **THEN** system does not flag these as placeholders (context-aware detection)
#### Scenario: Detect empty sections
- **WHEN** a required section exists but has no content after the heading
- **THEN** system identifies this as incomplete
### Requirement: Population Awareness
The validation SHALL check if the application has been properly populated from input documents.
#### Scenario: Warn if input folder is empty
- **WHEN** `input/` folder doesn't exist or contains no files
- **THEN** validation includes warning: "Input folder is empty. Consider adding documents and running /populate-application"
#### Scenario: Suggest population if sections are empty
- **WHEN** most sections still contain `[To be filled]` placeholders
- **THEN** validation suggests: "Application appears unpopulated. Run /populate-application after adding documents to input/"
#### Scenario: Don't warn if manually populated
- **WHEN** required sections are filled with real content (even if `input/` is empty)
- **THEN** validation does not suggest running `/populate-application`
### Requirement: Pass/Fail Reporting
The validation SHALL use binary pass/fail status with structured output.
#### Scenario: Successful validation output
- **WHEN** all required sections are complete
- **THEN** system displays:
- ✅ emoji and "Application Validation: PASSED" title
- Summary of application (organization, position, key stats)
- Encouraging message
- Clear next step: "You can now proceed with generating..."
#### Scenario: Failed validation output
- **WHEN** any required section has placeholders or is empty
- **THEN** system displays:
- ❌ emoji and "Application Validation: FAILED" title
- Explanation of the issue
- Structured list of problems organized by section
- Specific placeholder text quoted for each issue
- Actionable guidance: "Please update application.md... then run /validate-application again"
#### Scenario: Include population warnings in failure output
- **WHEN** validation fails AND input folder is empty
- **THEN** failure output includes additional "Population Status" section with suggestions
### Requirement: Error Message Clarity
The validation SHALL provide clear, actionable error messages.
#### Scenario: Quote specific placeholder text
- **WHEN** a field contains placeholder `[Company Name Here]`
- **THEN** error message shows: "Organization Name: Contains placeholder '[Company Name Here]'"
#### Scenario: Group errors by section
- **WHEN** multiple fields in Job Description Summary are incomplete
- **THEN** errors are grouped under "## Job Description Summary" heading with individual items listed
#### Scenario: Provide next steps
- **WHEN** validation fails
- **THEN** output includes clear guidance: "Please update application.md to fill in these sections, then run /validate-application again"
#### Scenario: List available applications on location error
- **WHEN** user runs command from wrong location without parameter
- **THEN** error message includes: "Available applications:" followed by list from `ls applications/pending/`
### Requirement: Edge Case Handling
The validation SHALL handle edge cases gracefully.
#### Scenario: Handle corrupted or unreadable application.md
- **WHEN** application.md exists but cannot be read or parsed
- **THEN** system displays error: "Could not read application.md. File may be corrupted."
#### Scenario: Handle very long placeholder text
- **WHEN** placeholder text is longer than 100 characters
- **THEN** error message truncates it: "Contains placeholder '[First 100 chars...]'"
#### Scenario: Handle missing required sections
- **WHEN** application.md is missing entire required sections (e.g., no Job Information section)
- **THEN** validation fails with error: "Missing required section: Job Information"
#### Scenario: Case-insensitive section matching
- **WHEN** section headings use different cases (e.g., "organization information" vs "Organization Information")
- **THEN** system correctly identifies the section
### Requirement: Workflow Integration
The validation command SHALL integrate with the existing application workflow.
#### Scenario: Documentation includes validation step
- **WHEN** user checks `src/CLAUDE.md` workflow documentation
- **THEN** validation step is shown between "Populate application" and "Generate documents"
#### Scenario: Validation mentioned in populate-application
- **WHEN** `/populate-application` completes successfully
- **THEN** output suggests: "Next: Run /validate-application to check completeness"
#### Scenario: Consistent with profile validation
- **WHEN** comparing `/validate-application` output to `/validate-profile` output
- **THEN** format, tone, and structure are consistent (both use ✅/❌, structured errors, encouraging tone)
openspec/changes/add-application-validation/tasks.md
+192
View File
@@ -0,0 +1,192 @@
# Implementation Tasks
## 1. Design Validation Logic
- [x] 1.1 Study `/validate-profile` command structure and pattern
- [x] 1.2 Define required vs optional sections for application.md
- [x] 1.3 Design placeholder detection regex patterns
- [x] 1.4 Define validation pass/fail criteria
- [x] 1.5 Design error message format and structure
## 2. Implement Location Detection
- [x] 2.1 Implement current directory detection logic
- Check if cwd ends with pattern: `applications/pending/[folder-name]/`
- Verify `application.md` exists in current directory
- [x] 2.2 Implement parameter parsing logic
- Accept folder name (e.g., `2025-11-02-TechCorp-Developer`)
- Accept relative path (e.g., `applications/pending/2025-11-02-TechCorp-Developer`)
- Accept absolute path
- [x] 2.3 Implement application discovery
- List available applications in `applications/pending/`
- Handle empty applications directory gracefully
## 3. Implement Error Handling for Location
- [x] 3.1 Handle running from wrong directory without parameter
- Show error message
- List available applications
- Provide usage examples
- [x] 3.2 Handle non-existent application with parameter
- Show error: "Application not found: [name]"
- List available applications
- [x] 3.3 Handle missing application.md
- Show error: "No application.md found in [path]"
- Suggest this may not be a valid application folder
## 4. Implement File Reading & Parsing
- [x] 4.1 Read application.md file content
- [x] 4.2 Parse markdown sections by headings
- Identify section boundaries
- Extract content for each section
- [x] 4.3 Handle corrupted or unreadable files
- Catch read errors
- Provide helpful error message
- [x] 4.4 Implement case-insensitive section matching
- Match "Organization Information", "organization information", etc.
## 5. Implement Placeholder Detection
- [x] 5.1 Create regex for square bracket placeholders: `\[([^\]]+)\]`
- [x] 5.2 Create patterns for common placeholders:
- `[To be filled]`
- `[Organization name]`
- `[Job Title]`
- `[...]`
- [x] 5.3 Detect generic template text
- "Add information here"
- "To be filled"
- Other unchanged template phrases
- [x] 5.4 Implement context-aware detection
- Don't flag legitimate brackets like `[PhD]`, `[Acquired]`
- Check surrounding context for meaningful use
- [x] 5.5 Handle very long placeholder text (truncate to 100 chars)
## 6. Implement Required Section Validation
- [x] 6.1 Validate Organization Information section
- Check for Organization Name field
- Detect placeholders in name field
- [x] 6.2 Validate Job Information section
- Check for Job Title field
- Detect placeholders in title field
- [x] 6.3 Validate Job Description Summary section
- Check if section has any content
- Verify at least one subsection (Responsibilities/Required Skills/etc.) has real content
- Detect if all subsections only have placeholders
- [x] 6.4 Implement empty section detection
- Check if required sections exist but have no content
- Report missing required sections
## 7. Implement Optional Section Handling
- [x] 7.1 Identify optional sections (don't validate):
- Match Strategy
- Key Messages
- Tone of Voice
- Research Notes
- Document Checklist
- Application Strategy Notes
- Timeline
- [x] 7.2 Ensure optional sections don't cause validation failure
- [x] 7.3 Allow these sections to contain placeholders without error
## 8. Implement Population Awareness
- [x] 8.1 Check if `input/` folder exists
- [x] 8.2 Check if `input/` folder contains files
- [x] 8.3 Implement warning logic:
- If `input/` is empty AND most sections have placeholders → suggest adding documents and running `/populate-application`
- If `input/` has files AND most sections still have placeholders → suggest running `/populate-application`
- If required sections are filled → don't warn (manually populated is fine)
- [x] 8.4 Add population warning to failure output
## 9. Implement Pass/Fail Reporting
- [x] 9.1 Design success output format:
- ✅ emoji and "Application Validation: PASSED" title
- Summary section with key information extracted from application.md
- Encouraging message
- Clear next step
- [x] 9.2 Design failure output format:
- ❌ emoji and "Application Validation: FAILED" title
- Explanation paragraph
- "Issues found:" heading
- Structured error list organized by section
- Actionable guidance
- [x] 9.3 Implement structured error grouping
- Group errors by section (## Organization Information, ## Job Description Summary, etc.)
- Use checkbox format: `- [ ] Field Name: Issue description`
- [x] 9.4 Quote specific placeholder text in errors
- Extract and quote the actual placeholder found
- Truncate if longer than 100 characters
## 10. Create Slash Command File
- [x] 10.1 Create `src/.claude/commands/validate-application.md`
- [x] 10.2 Write comprehensive instructions covering:
- Location detection logic (current directory vs parameter)
- Error handling for wrong location
- File reading and parsing
- Placeholder detection patterns
- Required vs optional section validation
- Population awareness checks
- Success/failure output formatting
- Edge case handling
- [x] 10.3 Add examples of success and failure outputs
- [x] 10.4 Include edge case handling instructions
## 11. Update Framework Documentation
- [x] 11.1 Update `src/CLAUDE.md` - Add `/validate-application` to command reference
- [x] 11.2 Update workflow section to include validation step
- Add between "Populate application" and "Generate documents" (future)
- [x] 11.3 Add best practices note about validating before generation
- [x] 11.4 Add usage examples:
- Running from inside application folder
- Running with explicit path
- [x] 11.5 Update `/populate-application` documentation to mention validation as next step
## 12. Integration Points
- [x] 12.1 Ensure consistency with `/validate-profile` pattern
- Match output format
- Match tone and language
- Match error structure
- [x] 12.2 Verify workflow integration:
- Profile validation → Application init → Add documents → Populate → **Validate** → Generate
- [x] 12.3 Consider future document generation integration
- Validation will be prerequisite for generation commands
## 13. Testing & Validation
- [x] 13.1 Test from inside application folder (no parameter)
- [x] 13.2 Test with folder name parameter
- [x] 13.3 Test with path parameter
- [x] 13.4 Test from wrong location (should show error + list)
- [x] 13.5 Test with non-existent application
- [x] 13.6 Test with complete application (should pass)
- [x] 13.7 Test with incomplete application (should fail with specific errors)
- [x] 13.8 Test with empty input/ folder (should warn)
- [x] 13.9 Test with populated input/ but empty sections (should suggest /populate-application)
- [x] 13.10 Test with manually populated application (should pass even if input/ empty)
- [x] 13.11 Test placeholder detection accuracy (catch placeholders, allow legitimate brackets)
- [x] 13.12 Test missing application.md file
- [x] 13.13 Test missing required sections
- [x] 13.14 Validate proposal: `openspec validate add-application-validation --strict`
## 14. Update Test Environment
- [x] 14.1 Copy new `/validate-application` command to test directory
- [x] 14.2 Update `CLAUDE.md` in test directory
- [x] 14.3 Preserve test directory's `profile.md` and `applications/` folder
- [x] 14.4 Test in actual test environment
## 15. Git Workflow
- [x] 15.1 Verify all changes are on feature branch `feature/application-validation`
- [x] 15.2 Stage all files (OpenSpec proposal, slash command, documentation updates)
- [x] 15.3 Create descriptive commit message following conventional commits format
- [x] 15.4 Merge feature branch into main
- [x] 15.5 Verify final state