From 2b13cc4e69ebe1413b11e4594f04e9dc2ddf4131 Mon Sep 17 00:00:00 2001 From: Markus Graf Date: Sun, 2 Nov 2025 21:00:05 +0100 Subject: [PATCH] feat: add application validation command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../add-application-validation/proposal.md | 120 ++++++ .../specs/application-validation/spec.md | 223 ++++++++++ .../add-application-validation/tasks.md | 192 +++++++++ src/.claude/commands/populate-application.md | 7 +- src/.claude/commands/validate-application.md | 385 ++++++++++++++++++ src/CLAUDE.md | 27 +- 6 files changed, 949 insertions(+), 5 deletions(-) create mode 100644 openspec/changes/add-application-validation/proposal.md create mode 100644 openspec/changes/add-application-validation/specs/application-validation/spec.md create mode 100644 openspec/changes/add-application-validation/tasks.md create mode 100644 src/.claude/commands/validate-application.md diff --git a/openspec/changes/add-application-validation/proposal.md b/openspec/changes/add-application-validation/proposal.md new file mode 100644 index 0000000..ead0701 --- /dev/null +++ b/openspec/changes/add-application-validation/proposal.md @@ -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 diff --git a/openspec/changes/add-application-validation/specs/application-validation/spec.md b/openspec/changes/add-application-validation/specs/application-validation/spec.md new file mode 100644 index 0000000..a1ee17b --- /dev/null +++ b/openspec/changes/add-application-validation/specs/application-validation/spec.md @@ -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) diff --git a/openspec/changes/add-application-validation/tasks.md b/openspec/changes/add-application-validation/tasks.md new file mode 100644 index 0000000..d29abc4 --- /dev/null +++ b/openspec/changes/add-application-validation/tasks.md @@ -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 diff --git a/src/.claude/commands/populate-application.md b/src/.claude/commands/populate-application.md index f634d56..89505ce 100644 --- a/src/.claude/commands/populate-application.md +++ b/src/.claude/commands/populate-application.md @@ -347,8 +347,11 @@ After successful population: 3. **Refine match strategy**: Adjust which experiences and projects to emphasize. -4. **Generate documents** (coming soon): - Once satisfied, generate tailored CV and cover letter. +4. **Validate application**: + Run /validate-application to ensure completeness before document generation. + +5. **Generate documents** (coming soon): + Once validation passes, generate tailored CV and cover letter. --- diff --git a/src/.claude/commands/validate-application.md b/src/.claude/commands/validate-application.md new file mode 100644 index 0000000..e4eb245 --- /dev/null +++ b/src/.claude/commands/validate-application.md @@ -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 diff --git a/src/CLAUDE.md b/src/CLAUDE.md index 885f252..085bd2e 100644 --- a/src/CLAUDE.md +++ b/src/CLAUDE.md @@ -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: