feat: add application validation command

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>
2025-11-02 21:00:05 +01:00
parent f1ba0dd98d
commit 2b13cc4e69
6 changed files with 949 additions and 5 deletions
@@ -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
@@ -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)
@@ -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
@@ -347,8 +347,11 @@ After successful population:
 3. **Refine match strategy**:
   Adjust which experiences and projects to emphasize.
-4. **Generate documents** (coming soon):
+4. **Validate application**:
-   Once satisfied, generate tailored CV and cover letter.
+   Run /validate-application to ensure completeness before document generation.
 5. **Generate documents** (coming soon):
   Once validation passes, generate tailored CV and cover letter.
 ---
@@ -0,0 +1,385 @@
 Validate that `application.md` is completely filled out and ready for document generation.
 # Instructions
 You are validating a job application to ensure it's ready for generating tailored CV, cover letter, and email.
 ## Step 1: Location Detection
 ### Determine Which Application to Validate
 **If NO parameter provided:**
 1. Check current working directory
 2. Verify if you're inside an application folder by checking:
   - Path pattern: ends with `applications/pending/[folder-name]/`
   - File existence: `application.md` exists in current directory
 3. If yes → validate this application
 4. If no → show error with available applications (see Error Handling section)
 **If parameter PROVIDED:**
 1. Parameter can be:
   - Folder name: `2025-11-02-TechCorp-Developer`
   - Relative path: `applications/pending/2025-11-02-TechCorp-Developer`
   - Absolute path: `/full/path/to/application/folder`
 2. Resolve to application folder: `applications/pending/[folder-name]/`
 3. Check if `application.md` exists in that location
 4. If yes → validate that application
 5. If no → show error with available applications
 ### Error Handling: Wrong Location / Not Found
 **If running from wrong location without parameter:**
 ```
 ❌ Not in an application folder
 Please either:
 1. Navigate to an application folder:
   cd applications/pending/[application-folder]/
   /validate-application
 2. Or provide the application folder name:
   /validate-application [application-folder-name]
 Available applications:
 [List output of: ls applications/pending/]
 Example:
 /validate-application 2025-11-02-TechCorp-Developer
 ```
 **If application doesn't exist with parameter:**
 ```
 ❌ Application not found: [provided-name]
 Available applications:
 [List output of: ls applications/pending/]
 Usage:
 /validate-application [folder-name]
 ```
 **If application.md missing in found folder:**
 ```
 ❌ No application.md found in [path]
 This doesn't appear to be a valid application folder.
 Did you create this application with /new-application?
 ```
 ## Step 2: Read application.md
 Read the entire `application.md` file in the detected/specified application folder.
 **If file is corrupted or unreadable:**
 ```
 ❌ Could not read application.md
 The file exists but cannot be read. It may be corrupted or have permission issues.
 Please check the file: [full-path-to-application.md]
 ```
 ## Step 3: Parse Sections
 Extract content for each section by markdown headings. Recognize sections case-insensitively:
 **Required Sections** (validation checks these):
 - "Organization Information" / "organization information"
 - "Job Information" / "job information"
 - "Job Description Summary" / "job description summary"
 **Optional Sections** (don't cause validation failure):
 - Match Strategy
 - Key Messages
 - Tone of Voice
 - Research Notes
 - Document Checklist
 - Application Strategy Notes
 - Timeline
 - Metadata
 ## Step 4: Detect Placeholders
 Check for these placeholder patterns that indicate incomplete data:
 ### Placeholder Patterns
 **Square brackets:**
 - `[To be filled]`
 - `[Organization name]`
 - `[Job Title]`
 - `[Company Name]`
 - `[...]`
 - `[Any text in brackets]`
 **Generic template text:**
 - "Add information here"
 - "To be filled"
 - Text that matches the template unchanged
 ### Context-Aware Detection
 **DO flag as placeholders:**
 - `[To be filled]`
 - `[Company Name]`
 - `[Job Title]` as the only content
 - `[Organization name here]`
 **DON'T flag as placeholders:**
 - `[PhD]` after a name in context
 - `[Acquired by Google]` in a company description
 - `[Remote]` as a job location descriptor
 - Other brackets used meaningfully in normal text
 If placeholder text is longer than 100 characters, truncate it in the error message: `"[First 100 chars...]"`
 ## Step 5: Validate Required Sections
 ### Organization Information
 **Must have:**
 - Organization Name field with real content (not placeholder)
 **Check:**
 - Look for "Organization Name:", "Company:", or similar field labels
 - Extract the value after the label
 - Check if value contains placeholders
 - Check if value is empty or only whitespace
 **If incomplete:**
 - Flag: `Organization Name: Contains placeholder "[exact-text]"`
 - Or: `Organization Name: Missing or empty`
 ### Job Information
 **Must have:**
 - Job Title field with real content (not placeholder)
 **Check:**
 - Look for "Job Title:", "Position:", or similar field labels
 - Extract the value after the label
 - Check if value contains placeholders
 - Check if value is empty or only whitespace
 **If incomplete:**
 - Flag: `Job Title: Contains placeholder "[exact-text]"`
 - Or: `Job Title: Missing or empty`
 ### Job Description Summary
 **Must have:**
 - At least SOME content in one or more subsections:
  - Responsibilities / Key Responsibilities
  - Required Skills / Qualifications
  - Preferred Skills
  - Requirements
  - Keywords
 **Check:**
 - Verify section exists
 - Check if section has any real content (not just placeholders)
 - Check if at least one subsection has meaningful text
 **If incomplete:**
 - Flag: `Job Description Summary: No content found`
 - Or: `Responsibilities: Contains placeholder "[exact-text]"`
 - Or: `Required Skills: Missing or empty`
 ### Missing Sections
 If an entire required section is missing from the document:
 - Flag: `Missing required section: [Section Name]`
 ## Step 6: Check Population Status
 ### Input Folder Check
 **Check if `input/` folder exists and has files:**
 1. Check for `input/` subfolder in the application directory
 2. List files in `input/` folder
 3. Count supported files (exclude .gitkeep, .DS_Store, etc.)
 **Categorize status:**
 - **Empty**: `input/` doesn't exist or has no files (0 files)
 - **Populated**: `input/` has 1+ files
 - **Not applicable**: Required sections are filled (manual population is fine)
 ### Population Warning Logic
 **Warn about population IF:**
 - Input folder is empty (0 files) AND
 - Multiple required sections still have placeholders
 **Suggest /populate-application IF:**
 - Input folder has files (1+ files) AND
 - Multiple required sections still have placeholders
 **DON'T warn IF:**
 - Required sections are filled with real content (manual population is fine, even if input/ is empty)
 ## Step 7: Generate Validation Report
 ### Success Format (Validation PASSES)
 **If all required sections are complete:**
 ```
 ✅ Application Validation: PASSED
 Your application is complete and ready for document generation!
 Summary:
 - Organization: [Extracted Company Name]
 - Position: [Extracted Job Title]
 - Job requirements: [N] identified
 - Input documents: [N] files in input/ folder
 [If Match Strategy section has content:]
 - Match strategy: Complete
 [If Key Messages section has content:]
 - Key messages: Defined
 You can now proceed with generating tailored CV, cover letter, and application email.
 ```
 **Extract actual values** from application.md for the summary (organization name, position, count requirements/skills mentioned).
 ### Failure Format (Validation FAILS)
 **If any required section is incomplete:**
 ```
 ❌ Application Validation: FAILED
 Your application has incomplete sections that need attention before document generation.
 Issues found:
 [Group errors by section - only show sections with errors]
 ## Organization Information
 - [ ] Organization Name: Contains placeholder "[To be filled]"
 ## Job Information
 - [ ] Job Title: Missing or empty
 ## Job Description Summary
 - [ ] Responsibilities: Contains placeholder "[List key responsibilities]"
 - [ ] Required Skills: No content found
 [If population warning applies:]
 ## Population Status
 ⚠️  Input folder appears empty. Consider:
 1. Adding job posting and related documents to input/
 2. Running /populate-application to extract information
 [Or if input has files but sections empty:]
 ## Population Status
 ⚠️  Input folder has [N] documents but application seems unpopulated.
 Consider running:
   /populate-application
 This will analyze your input documents and populate the sections above.
 [End with guidance:]
 Please update application.md to fill in these sections, then run /validate-application again.
 [Alternative if only placeholders:]
 Or manually edit application.md to add the missing information, then run /validate-application again.
 ```
 ### Error Details Format
 **For each issue, use checkbox format:**
 ```
 - [ ] Field Name: Issue description
 ```
 **Quote exact placeholder text:**
 ```
 - [ ] Organization Name: Contains placeholder "[To be filled]"
 ```
 **Group by section:**
 ```
 ## Organization Information
 - [ ] Organization Name: Issue
 - [ ] Location: Issue
 ## Job Description Summary
 - [ ] Responsibilities: Issue
 ```
 ## Step 8: Provide Clear Next Steps
 ### After Success
 ```
 You can now proceed with generating tailored CV, cover letter, and application email.
 ```
 ### After Failure
 ```
 Please update application.md to fill in these sections, then run /validate-application again.
 ```
 Or if they should run population:
 ```
 Add documents to input/ folder and run /populate-application to analyze and populate application.md.
 Then run /validate-application again to confirm completeness.
 ```
 ## Important Notes
 ### Tone
 - Be encouraging - validation is a positive quality check
 - Be specific about what's missing
 - Provide actionable guidance
 - Don't be judgmental about incomplete applications
 ### Flexibility
 - Optional sections can remain incomplete
 - Manual population is perfectly fine (don't require /populate-application if sections are filled)
 - Input folder can be empty if user manually populated
 - Focus on required information only
 ### Accuracy
 - Quote exact placeholder text when reporting issues
 - Extract real values from application.md for success summary
 - Count actual items (requirements, skills, documents)
 - Be precise about what's missing vs what's present
 ### Integration
 - This is a quality gate before document generation
 - Match the pattern of `/validate-profile` for consistency
 - User can explicitly skip validation if they want (with warning)
 - Default behavior: validate before generating any documents
 ## Edge Cases
 ### Legitimate Brackets
 - `[PhD]` or `[MBA]` in credentials → not a placeholder
 - `[Remote]` as location descriptor → not a placeholder
 - `[Acquired]` in company history → not a placeholder
 - Check surrounding context to distinguish
 ### Partial Completion
 - If Organization Name is filled but Job Title has placeholder → only flag Job Title
 - If some job description subsections are filled → validation can pass
 - Don't require ALL subsections, just SOME content
 ### Very Long Placeholders
 - Truncate to 100 characters: `"[First 100 characters...]"`
 - Still quote them to show what was found
 ### Multiple Issues in Same Field
 - List each issue separately
 - Be clear about what specifically is wrong
 ### Application Already Has Some Content
 - Focus error messages only on what's still missing
 - Acknowledge what's already complete in summary (if desired)
 - Be constructive about gaps
@@ -187,14 +187,21 @@ When helping with job applications, follow this comprehensive workflow:
 - Adjust which experiences and projects to emphasize
 - Fine-tune key messages and tone
-### 5. Content Generation (FUTURE)
+### 5. Validate Application (NEW - Quality Gate)
 - Run `/validate-application` to ensure application.md is complete
 - Check that required sections are filled (Organization, Job Title, Job Description)
 - Verify no placeholder text remains (like `[To be filled]`)
 - Get warnings if input/ folder is empty or application seems unpopulated
 - **Must pass before document generation**
 ### 6. Content Generation (FUTURE)
 - Generate CV/cover letter/email based on `application.md` strategy
 - Emphasize relevant experience from `profile.md`
 - Incorporate keywords from the job description naturally
 - Maintain factual accuracy - use only verified information from `profile.md`
 - **Note**: Document generation will be implemented in a future update
-### 6. Quality Assurance
+### 7. Quality Assurance
 - Verify all company names, dates, and facts are correct
 - Ensure consistency between all documents (CV ↔ cover letter ↔ email)
 - Check that tone matches the target company culture
@@ -255,6 +262,7 @@ Adjust recommendations based on the target market if the user specifies a differ
 - `/validate-profile` - Validate that `profile.md` is complete and ready for application generation
 - `/new-application "Company - Job Title"` - Create a new application workspace with organized folder structure
 - `/populate-application` - Analyze input documents and populate application.md with job info, research, and strategy
 - `/validate-application [optional-app-name]` - Validate that application.md is complete before document generation
 ## Example Usage
@@ -268,7 +276,9 @@ Adjust recommendations based on the target market if the user specifies a differ
 3. After application is created, guide user: "Add the job posting and any other documents to `applications/pending/[folder]/input/`"
 4. When user has added documents: "Navigate to the application folder and run `/populate-application`"
 5. After population completes: "Review `application.md` to see the analysis and strategy"
-6. Future: Generate tailored CV, cover letter, and email based on `application.md`
+6. Validation step: "Run `/validate-application` to ensure the application is complete"
 7. If validation passes: Ready for document generation
 8. Future: Generate tailored CV, cover letter, and email based on `application.md`
 ### Example 2: Quick Document Request (Legacy Flow)
@@ -283,6 +293,17 @@ Adjust recommendations based on the target market if the user specifies a differ
 6. Generate tailored cover letter using only information from `profile.md`
 7. Suggest: "For better organization, consider using `/new-application` next time to manage the full application process"
 ### Example 3: Validating an Application
 **User**: "Check if my TechCorp application is ready"
 **Claude Code should**:
 1. If user is in application folder: Run `/validate-application` (auto-detects current location)
 2. If user is elsewhere: Run `/validate-application 2025-11-02-TechCorp-Software-Engineer`
 3. If validation passes (✅): "Your application is complete! Organization: TechCorp, Position: Software Engineer. Ready for document generation."
 4. If validation fails (❌): Show specific issues like "Organization Name: Contains placeholder '[To be filled]'" and suggest "Please update application.md or run `/populate-application` if you have documents in input/"
 5. Provide clear next steps based on validation result
 ## Updating the Profile
 If you notice missing or outdated information during application preparation: