Bewerbungszauberer/openspec/changes/archive-applications/proposal.md

Proposal: Archive Applications

Change ID

archive-applications

Summary

Add the ability to archive unsuccessful job applications by moving them from applications/pending/ to organized archive folders (applications/rejected/ or applications/not-interested/). The system will update application metadata and warn users before archiving applications with generated documents.

Problem Statement

Users currently have no structured way to organize completed or unsuccessful applications. All applications remain in the applications/pending/ folder indefinitely, making it difficult to:

1. Distinguish between active and inactive applications
2. Organize applications by outcome (rejected by company vs. user withdrew)
3. Keep the pending folder clean and focused on current opportunities
4. Track the lifecycle of applications from creation to completion

Proposed Solution

Introduce a /archive-application command that:

1. Moves applications from applications/pending/ to outcome-specific folders:

   • applications/rejected/ - Company rejected the application
   • applications/not-interested/ - User decided not to pursue

2. Updates application metadata:

   • Modifies the Status field in application.md with timestamp
   • Preserves all application work (documents, input files, attachments)

3. Protects user work:

   • Detects generated documents (cover letters, emails, attachments)
   • Warns before archiving and requires explicit --force flag
   • Prevents accidental loss of significant work

4. Provides flexible usage:

   • Auto-detects application when run from within application folder
   • Accepts application name parameter when run from any location
   • Supports help flag for usage information

User Requirements

Based on user clarification during proposal phase:

• ✅ Metadata update: Move files AND update Status field with timestamp
• ✅ Command design: Single command with parameter: /archive-application [reason]
• ✅ Safety checks: Warn if documents exist, require --force to proceed
• ✅ Scope: Only rejection paths (rejected and not-interested) for now

Success Criteria

After implementation, users should be able to:

1. Archive applications from within the application folder
2. Archive applications by name from any location
3. Receive warnings before archiving applications with work invested
4. See updated Status field with timestamp after archiving
5. Find archived applications in organized folders by reason
6. Use --force to skip safety checks when confident

Command Interface

Syntax

/archive-application [reason] [application-name] [--force]

Parameters

• reason (required): Either rejected or not-interested

  • rejected - Company rejected the application
  • not-interested - User decided to withdraw or not pursue further

• application-name (optional): Application folder name

  • If omitted: Auto-detect from current working directory
  • If provided: Resolve to full path in pending folder

• --force (flag): Skip safety warnings about generated documents

Examples

# From within application folder
cd applications/pending/2025-11-02-TechCorp-Developer/
/archive-application rejected

# From anywhere with application name
/archive-application rejected 2025-11-02-TechCorp-Developer

# Skip safety checks
/archive-application not-interested --force

# Get help
/archive-application --help

Folder Structure

Before

src/applications/
└── pending/
    ├── 2025-11-02-TechCorp-Developer/
    ├── 2025-11-05-StartupCo-Engineer/
    └── 2025-11-10-BigCorp-Lead/

After

src/applications/
├── pending/
│   └── 2025-11-10-BigCorp-Lead/          # Still active
├── rejected/
│   └── 2025-11-02-TechCorp-Developer/     # Company rejected
└── not-interested/
    └── 2025-11-05-StartupCo-Engineer/     # User withdrew

Applications maintain their original folder name (YYYY-MM-DD-Company-JobTitle/) when moved.

Archiving Process

Step-by-Step Flow

1. Parse & Validate

   • Extract reason parameter (rejected/not-interested)
   • Extract optional application name and flags
   • Validate reason is one of the allowed values

2. Location Detection

   • If no application name: Check if running from within an application folder
   • If application name: Resolve to full path in pending folder
   • Verify application.md exists

3. Safety Check (unless --force)

   • Check for cover-letter.md in application folder
   • Check for application-email.md in application folder
   • Check for files in attachments/ folder (excluding .keep)
   • If ANY found: Show warning and require --force to proceed

4. Update Metadata

   • Read application.md
   • Find Status field in Metadata section: - **Status**: Draft
   • Replace with: - **Status**: Rejected (Archived: 2025-12-18 15:30) OR - **Status**: Not Interested (Archived: 2025-12-18 15:30)
   • Write back to file

5. Create Archive Directory

   • Create applications/rejected/ or applications/not-interested/ if doesn't exist

6. Move Application

   • Execute: mv applications/pending/[folder]/ applications/[reason]/[folder]/
   • Verify move succeeded (destination exists, source removed)

7. Confirm Success

   • Show success message with archive details
   • Include original and new locations
   • Display updated status

Safety Warning Example

⚠️  Warning: Generated documents detected

This application contains work that may be lost:
- cover-letter.md (exists)
- application-email.md (exists)
- attachments/ folder (3 files)

Archiving will move everything to the archive folder, but these documents
suggest you may have put significant work into this application.

Options:
1. Continue archiving anyway: /archive-application rejected --force
2. Cancel and review the documents first
3. Export/backup documents before archiving

Are you sure you want to archive this application?

System behavior: STOP and require --force flag to proceed.

Technical Implementation

Status Field Update

Current format (in template):

- **Status**: Draft

After archiving (rejected):

- **Status**: Rejected (Archived: 2025-12-18 15:30)

After archiving (not-interested):

- **Status**: Not Interested (Archived: 2025-12-18 15:30)

Implementation approach:

1. Read entire application.md file
2. Find line matching pattern: ^(\s*-\s*\*\*Status\*\*:\s*)(.*)$
3. Replace entire line with new status and timestamp
4. Write back to file

Timestamp format: YYYY-MM-DD HH:MM (ISO-style date, 24-hour time)

Safety Check Logic

Detection criteria:

# Check for generated documents
test -f cover-letter.md          # Cover letter exists
test -f application-email.md     # Email exists
ls attachments/ | grep -v '\.keep' | wc -l > 0   # Has attachments besides .keep

Warning trigger:

• ANY of: cover-letter.md exists, application-email.md exists, attachments count > 0

Bypass:

• Provide --force flag to skip all safety checks

Auto-Detection Pattern

When no application name provided:

1. Get current working directory
2. Check if path matches: */applications/pending/[folder-name]/
3. Verify application.md exists in current directory
4. Extract folder name for use in move operation

When application name provided:

1. Resolve to full path: applications/pending/[provided-name]/
2. Verify folder exists
3. Verify application.md exists

Error Handling

Error Scenarios

1. Invalid reason

   ❌ Invalid reason: [provided-reason]
   
   Reason must be one of:
   - rejected: Company rejected the application
   - not-interested: User withdrew or not pursuing
   
   Usage: /archive-application [reason] [application-name]
   

2. Application not found

   ❌ Application not found: [application-name]
   
   Available applications in pending:
   [List folders in applications/pending/]
   
   Usage: /archive-application [reason] [application-name]
   

3. Not in application folder

   ❌ Not in an application folder
   
   Please either:
   1. Navigate to an application folder:
      cd applications/pending/[application-folder]/
      /archive-application [reason]
   
   2. Or provide the application folder name:
      /archive-application [reason] [application-folder-name]
   
   Available applications:
   [List folders in applications/pending/]
   

4. Already archived

   ❌ Application not found in pending folder
   
   The application "[folder-name]" doesn't exist in applications/pending/.
   
   Did you already archive it? Check:
   - applications/rejected/
   - applications/not-interested/
   
   To move between archives, use mv command directly.
   

5. File operation failure

   ❌ Failed to archive application
   
   Error: [specific error message]
   
   Possible causes:
   - Insufficient permissions
   - File system full
   - Application folder is open in another program
   
   Please check the issue and try again.
   The application has NOT been modified.
   

6. Status update failure

   ⚠️  Application moved but status update failed
   
   The application was moved to:
   applications/[reason]/[folder-name]/
   
   However, the Status field in application.md could not be updated.
   Please manually update: - **Status**: [Rejected/Not Interested] (Archived: [date])
   
   Error: [specific error details]
   

Edge Cases

Handled Edge Cases

1. Partially generated application

   • User created cover letter but not email
   • Handling: Warn - any generated document is significant work

2. Empty attachments folder

   • attachments/ exists but only contains .keep file
   • Handling: Don't count as "having attachments" - no warning

3. Re-archiving

   • User tries to archive application already in rejected folder
   • Handling: Error message suggesting application already archived

4. Missing Status field

   • Old application.md doesn't have Status field in Metadata section
   • Handling: Add Status field to Metadata section, then proceed

5. Permission errors

   • Can't write to application.md or can't move folder
   • Handling: Rollback any changes, show clear error, leave in pending

6. Concurrent operations

   • User has application open in editor while archiving
   • Handling: File system will handle, may fail - show appropriate error

Integration Points

With Existing Workflow

The archiving feature integrates at the end of the application lifecycle:

Current workflow:
1. Create: /new-application "Company - Job Title"
2. Populate: /populate-application
3. Validate: /validate-application
4. Generate: /write-cover-letter
5. Generate: /write-application-email
6. Send: (User sends application via email client)

NEW:
7. Archive: /archive-application [reason]  ← NEW STEP

With Application States

Application lifecycle states:

• Draft - Created, not yet populated (in pending/)
• In Progress - Being worked on, documents generated (in pending/)
• Submitted - Sent to company, awaiting response (in pending/)
• Rejected - Company rejected (in rejected/)
• Not Interested - User withdrew (in not-interested/)

Status field tracking:

• application.md Metadata section maintains current state
• Archive operation updates state with timestamp
• State history is preserved in Timeline section

With Documentation

Updates needed to src/CLAUDE.md:

1. Add new section: "Archiving Applications" (~40 lines)

   • Explain archiving workflow
   • Show command syntax and examples
   • Describe safety checks
   • Document archive folder structure

2. Update "Available Commands" list

   • Add /archive-application with parameters and flags

3. Update workflow examples

   • Include archiving as final step in lifecycle

Dependencies

File Dependencies

Required existing files:

• applications/pending/ - Source folder for active applications
• application.md - Must exist in each application folder
• src/CLAUDE.md - Framework instructions to update

Created files:

• applications/rejected/ - Created on-demand when first needed
• applications/not-interested/ - Created on-demand when first needed

Command Dependencies

No hard dependencies on other commands, but archiving is typically the last step after:

• /new-application - Creates the application
• /populate-application - Populates strategy
• /write-cover-letter - Generates cover letter
• /write-application-email - Generates email

Users can archive at any stage (even immediately after creation if they change their mind).

Testing Considerations

Test Scenarios

1. Basic archiving from within application folder

   • No generated documents
   • Should succeed without warnings

2. Archiving with application name parameter

   • From any location
   • Should resolve path and succeed

3. Safety check with cover letter

   • Generated cover-letter.md exists
   • Should warn and require --force

4. Safety check with attachments

   • Files exist in attachments/ folder
   • Should warn and require --force

5. Force flag bypasses warnings

   • Use --force with generated documents
   • Should proceed without warnings

6. Invalid reason parameter

   • Provide unsupported reason (e.g., "accepted")
   • Should error with valid options

7. Application not found

   • Provide non-existent application name
   • Should error with available applications list

8. Wrong directory without parameter

   • Run from root without application name
   • Should error with usage guidance

9. Create rejected folder for first time

   • First time archiving with "rejected" reason
   • Should create applications/rejected/ folder

10. Multiple applications to same folder

    • Archive multiple applications as rejected
    • Should handle without conflicts

11. Status field update verification

    • Check application.md after archiving
    • Should have updated Status with timestamp

12. Missing Status field

    • Archive old application without Status field
    • Should add field before archiving

Backwards Compatibility

Compatibility Analysis

No breaking changes:

• Existing applications in pending/ folder are unaffected
• Archive folders are created on-demand
• Status field already exists in current template (line 12)
• No changes to existing command behavior
• No changes to folder structure for pending applications

Forwards compatible:

• Old applications can be archived (Status field added if missing)
• New applications will work with archiving from day one
• Archive folders follow same naming convention as pending

Migration: None required - feature works with existing applications as-is

Alternatives Considered

Alternative 1: Separate Commands for Each Reason

Approach: Create /reject-application and /withdraw-application commands

Pros:

• More intuitive command names
• Clearer user intent
• Better discoverability (separate help for each)

Cons:

• Code duplication (same logic in two commands)
• More commands to maintain
• Harder to add new archive reasons later

Decision: Rejected in favor of single parameterized command based on user preference

Alternative 2: Just Move Files (No Metadata Update)

Approach: Simple file move without updating application.md

Pros:

• Simpler implementation
• Faster execution
• Less chance of file corruption

Cons:

• Lose tracking of when and why archived
• Status field becomes outdated
• No audit trail of archival

Decision: Rejected - metadata update provides valuable tracking

Alternative 3: Always Allow Archiving (No Safety Checks)

Approach: Skip all warnings, just move files

Pros:

• Faster for experienced users
• No interruptions
• Simpler implementation

Cons:

• Risk of accidentally archiving significant work
• No protection against mistakes
• Harder to recover from accidents

Decision: Rejected - safety checks prevent data loss and frustration

Alternative 4: Add accepted Folder Immediately

Approach: Include applications/accepted/ from the start

Pros:

• Complete lifecycle coverage
• Users can track successful applications
• More comprehensive solution

Cons:

• Scope creep beyond user request
• Different use case (accepted apps are managed differently)
• Can add later if needed

Decision: Rejected - focus on user's current need (rejection paths)

Future Enhancements

Not included in this proposal but could be added in future changes:

1. Accepted archive - applications/accepted/ folder for successful applications
2. Unarchive command - /unarchive-application to move back to pending
3. List archived - /list-archived command to browse archives by reason
4. Archive statistics - Show counts of applications by outcome
5. Archive search - Find applications in archives by company or date
6. Bulk operations - Archive multiple applications at once
7. Archive notes - Add custom notes when archiving (why rejected, lessons learned)
8. Expiration/cleanup - Auto-delete archived applications older than X months
9. Export archive - Export archived applications to external format (CSV, JSON)
10. Timeline tracking - Add "Archived" entry to Timeline section in application.md

Risks and Mitigations

Risk 1: Accidental Data Loss

Risk: Users accidentally archive applications with significant work

Likelihood: Medium (users may not realize they have generated documents)

Impact: High (loss of cover letters, emails, strategy work)

Mitigation:

• Implement safety checks that detect generated documents
• Require explicit --force flag to bypass warnings
• Show detailed warning listing all documents that would be archived
• Preserve all files during move (nothing is deleted)

Risk 2: File System Errors

Risk: Move operation fails due to permissions, disk space, or concurrent access

Likelihood: Low (most systems handle file operations reliably)

Impact: Medium (application left in inconsistent state)

Mitigation:

• Check permissions before attempting move
• Verify destination doesn't already exist
• Rollback metadata changes if move fails
• Show clear error messages with troubleshooting steps
• Never delete source until move is verified

Risk 3: Status Update Failures

Risk: Status field update fails but files are moved

Likelihood: Low (text file updates usually succeed)

Impact: Low (application is archived, just metadata is stale)

Mitigation:

• Update status BEFORE moving files (easier to recover)
• If update fails, stop and don't move
• If move succeeds but status fails, warn user but don't rollback
• Provide manual update instructions in error message

Risk 4: User Confusion About Archive Locations

Risk: Users can't find archived applications after moving them

Likelihood: Medium (users may forget where they archived)

Impact: Low (applications are still accessible, just in different folder)

Mitigation:

• Show clear success message with new location
• Use intuitive folder names (rejected, not-interested)
• Document archive structure in CLAUDE.md
• Consider future enhancement: /list-archived command

Risk 5: Archive Folder Clutter

Risk: Archive folders become cluttered with many old applications

Likelihood: High (over time, many applications will be archived)

Impact: Low (just organizational issue, doesn't affect functionality)

Mitigation:

• Maintain date prefix in folder names for chronological sorting
• Document folder structure in CLAUDE.md
• Consider future enhancement: expiration/cleanup policy
• Consider future enhancement: archive search functionality

Implementation Approach

Phase 1: Core Command (Priority 1)

1. Create command file: src/.claude/commands/archive-application.md

   • ~500-700 lines procedural instructions
   • Follow pattern from write-cover-letter.md
   • Include all validation, safety checks, error handling

2. Update framework docs: src/CLAUDE.md

   • Add "Archiving Applications" section
   • Update "Available Commands" list
   • Include workflow integration examples

Phase 2: Specifications (Priority 1)

3. Create OpenSpec spec: openspec/specs/application-archiving/spec.md

   • Formal requirements with scenarios
   • Document all behaviors and edge cases

4. Update existing spec: openspec/specs/application-management/spec.md

   • Add lifecycle management requirement
   • Document application states

Phase 3: Testing & Validation (Priority 2)

5. Manual testing of all scenarios
6. Verification of error handling
7. Documentation review for clarity

Phase 4: Optional Enhancements (Priority 3)

8. Consider adding Timeline section updates
9. Consider archive listing functionality
10. Consider unarchive command

Approval Checklist

Before implementation begins, verify:

• User has confirmed archiving approach (move + metadata update)
• Command syntax is clear and intuitive
• Safety check behavior is acceptable
• Archive folder structure makes sense
• Error handling covers common scenarios
• Integration with existing workflow is smooth
• OpenSpec proposal follows project conventions
• No breaking changes to existing functionality

Success Metrics

After implementation, measure success by:

1. Functionality: Users can successfully archive applications
2. Safety: No reports of accidental data loss
3. Usability: Users understand command syntax without extensive documentation
4. Integration: Command fits naturally into existing workflow
5. Maintenance: Command follows established patterns, easy to maintain

---

Status: Proposal draft ready for review Change ID: archive-applications Estimated Effort: Medium (1-2 hours implementation) Risk Level: Low (non-breaking, additive feature)