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

Implementation Tasks

1. Design Validation Logic

• 1.1 Study /validate-profile command structure and pattern
• 1.2 Define required vs optional sections for application.md
• 1.3 Design placeholder detection regex patterns
• 1.4 Define validation pass/fail criteria
• 1.5 Design error message format and structure

2. Implement Location Detection

• 2.1 Implement current directory detection logic
  • Check if cwd ends with pattern: applications/pending/[folder-name]/
  • Verify application.md exists in current directory
• 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
• 2.3 Implement application discovery
  • List available applications in applications/pending/
  • Handle empty applications directory gracefully

3. Implement Error Handling for Location

• 3.1 Handle running from wrong directory without parameter
  • Show error message
  • List available applications
  • Provide usage examples
• 3.2 Handle non-existent application with parameter
  • Show error: "Application not found: [name]"
  • List available applications
• 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

• 4.1 Read application.md file content
• 4.2 Parse markdown sections by headings
  • Identify section boundaries
  • Extract content for each section
• 4.3 Handle corrupted or unreadable files
  • Catch read errors
  • Provide helpful error message
• 4.4 Implement case-insensitive section matching
  • Match "Organization Information", "organization information", etc.

5. Implement Placeholder Detection

• 5.1 Create regex for square bracket placeholders: \[([^\]]+)\]
• 5.2 Create patterns for common placeholders:
  • [To be filled]
  • [Organization name]
  • [Job Title]
  • [...]
• 5.3 Detect generic template text
  • "Add information here"
  • "To be filled"
  • Other unchanged template phrases
• 5.4 Implement context-aware detection
  • Don't flag legitimate brackets like [PhD], [Acquired]
  • Check surrounding context for meaningful use
• 5.5 Handle very long placeholder text (truncate to 100 chars)

6. Implement Required Section Validation

• 6.1 Validate Organization Information section
  • Check for Organization Name field
  • Detect placeholders in name field
• 6.2 Validate Job Information section
  • Check for Job Title field
  • Detect placeholders in title field
• 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
• 6.4 Implement empty section detection
  • Check if required sections exist but have no content
  • Report missing required sections

7. Implement Optional Section Handling

• 7.1 Identify optional sections (don't validate):
  • Match Strategy
  • Key Messages
  • Tone of Voice
  • Research Notes
  • Document Checklist
  • Application Strategy Notes
  • Timeline
• 7.2 Ensure optional sections don't cause validation failure
• 7.3 Allow these sections to contain placeholders without error

8. Implement Population Awareness

• 8.1 Check if input/ folder exists
• 8.2 Check if input/ folder contains files
• 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)
• 8.4 Add population warning to failure output

9. Implement Pass/Fail Reporting

• 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
• 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
• 9.3 Implement structured error grouping
  • Group errors by section (## Organization Information, ## Job Description Summary, etc.)
  • Use checkbox format: - [ ] Field Name: Issue description
• 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

• 10.1 Create src/.claude/commands/validate-application.md
• 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
• 10.3 Add examples of success and failure outputs
• 10.4 Include edge case handling instructions

11. Update Framework Documentation

• 11.1 Update src/CLAUDE.md - Add /validate-application to command reference
• 11.2 Update workflow section to include validation step
  • Add between "Populate application" and "Generate documents" (future)
• 11.3 Add best practices note about validating before generation
• 11.4 Add usage examples:
  • Running from inside application folder
  • Running with explicit path
• 11.5 Update /populate-application documentation to mention validation as next step

12. Integration Points

• 12.1 Ensure consistency with /validate-profile pattern
  • Match output format
  • Match tone and language
  • Match error structure
• 12.2 Verify workflow integration:
  • Profile validation → Application init → Add documents → Populate → Validate → Generate
• 12.3 Consider future document generation integration
  • Validation will be prerequisite for generation commands

13. Testing & Validation

• 13.1 Test from inside application folder (no parameter)
• 13.2 Test with folder name parameter
• 13.3 Test with path parameter
• 13.4 Test from wrong location (should show error + list)
• 13.5 Test with non-existent application
• 13.6 Test with complete application (should pass)
• 13.7 Test with incomplete application (should fail with specific errors)
• 13.8 Test with empty input/ folder (should warn)
• 13.9 Test with populated input/ but empty sections (should suggest /populate-application)
• 13.10 Test with manually populated application (should pass even if input/ empty)
• 13.11 Test placeholder detection accuracy (catch placeholders, allow legitimate brackets)
• 13.12 Test missing application.md file
• 13.13 Test missing required sections
• 13.14 Validate proposal: openspec validate add-application-validation --strict

14. Update Test Environment

• 14.1 Copy new /validate-application command to test directory
• 14.2 Update CLAUDE.md in test directory
• 14.3 Preserve test directory's profile.md and applications/ folder
• 14.4 Test in actual test environment

15. Git Workflow

• 15.1 Verify all changes are on feature branch feature/application-validation
• 15.2 Stage all files (OpenSpec proposal, slash command, documentation updates)
• 15.3 Create descriptive commit message following conventional commits format
• 15.4 Merge feature branch into main
• 15.5 Verify final state