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

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)