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

```bash
/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

```bash
# 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):**
```markdown
- **Status**: Draft
```

**After archiving (rejected):**
```markdown
- **Status**: Rejected (Archived: 2025-12-18 15:30)
```

**After archiving (not-interested):**
```markdown
- **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:**
```bash
# 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)