gurixandClaude
84a229c255
Archive all completed changes and create final specifications: Archived changes (2025-11-03): - add-application-email (8 requirements) - add-application-management (9 requirements) - add-application-validation (9 requirements) - add-cover-letter-generation (13 requirements) - add-cover-letter-pdf-conversion (7 requirements) - add-profile-template (4 requirements) - add-profile-validation (3 requirements) Created specifications: - applicant-profile: User profile management with validation - application-email: Email generation for job applications - application-management: Application workflow and folder structure - application-validation: Application completeness checking - cover-letter-generation: Tailored cover letter creation - cover-letter-pdf-conversion: PDF export with Swiss formatting All features are now fully documented in openspec/specs/ and ready for use. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
226 lines
8.8 KiB
Markdown
226 lines
8.8 KiB
Markdown
# application-validation Specification
|
|
|
|
## Purpose
|
|
TBD - created by archiving change add-application-validation. Update Purpose after archive.
|
|
## 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)
|
|
|