378 lines
15 KiB
Markdown
378 lines
15 KiB
Markdown
 
|
# application-archiving Specification
|
||
|
|
|
||
|
|
## Purpose
|
||
|
|
Provide a structured way to archive job applications that are no longer active, maintaining organization and preserving all application work. This capability enables users to move applications from `applications/pending/` to outcome-specific folders (`rejected`, `not-interested`) with metadata updates and safety protections.
|
||
|
|
|
||
|
|
## ADDED Requirements
|
||
|
|
|
||
|
|
### Requirement: Application Archiving Command
|
||
|
|
|
||
|
|
The system SHALL provide a `/archive-application` command that moves applications from pending to archive folders with metadata updates.
|
||
|
|
|
||
|
|
#### Scenario: Archive rejected application from current directory
|
||
|
|
|
||
|
|
- **WHEN** user navigates to `applications/pending/[folder]/` and runs `/archive-application rejected`
|
||
|
|
- **THEN** system detects current application automatically
|
||
|
|
- **AND** moves application folder from `applications/pending/` to `applications/rejected/`
|
||
|
|
- **AND** updates Status field to "Rejected (Archived: [timestamp])"
|
||
|
|
- **AND** preserves all files and folders (application.md, input/, attachments/)
|
||
|
|
- **AND** shows success message with archive location
|
||
|
|
|
||
|
|
#### Scenario: Archive not-interested application by name
|
||
|
|
|
||
|
|
- **WHEN** user runs `/archive-application not-interested 2025-11-02-TechCorp-Developer` from any location
|
||
|
|
- **THEN** system resolves application path in pending folder
|
||
|
|
- **AND** moves application to `applications/not-interested/`
|
||
|
|
- **AND** updates Status field to "Not Interested (Archived: [timestamp])"
|
||
|
|
- **AND** shows success message with original and new locations
|
||
|
|
|
||
|
|
#### Scenario: Display help information
|
||
|
|
|
||
|
|
- **WHEN** user runs `/archive-application --help`
|
||
|
|
- **THEN** system displays command syntax and usage information
|
||
|
|
- **AND** explains parameters (reason, application-name, flags)
|
||
|
|
- **AND** provides examples for common scenarios
|
||
|
|
- **AND** describes what happens during archiving
|
||
|
|
|
||
|
|
#### Scenario: Validate reason parameter
|
||
|
|
|
||
|
|
- **WHEN** user provides invalid reason (not "rejected" or "not-interested")
|
||
|
|
- **THEN** system shows error message listing valid reasons
|
||
|
|
- **AND** displays usage information
|
||
|
|
- **AND** does NOT modify any files
|
||
|
|
|
||
|
|
#### Scenario: Resolve application location
|
||
|
|
|
||
|
|
- **WHEN** user provides application name without full path
|
||
|
|
- **THEN** system searches `applications/pending/` for matching folder
|
||
|
|
- **AND** resolves to full path if found
|
||
|
|
- **AND** shows error if application not found
|
||
|
|
- **AND** lists available applications in pending folder
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Safety Warnings for Generated Documents
|
||
|
|
|
||
|
|
The system SHALL warn users before archiving applications with generated documents to prevent accidental loss of work.
|
||
|
|
|
||
|
|
#### Scenario: Detect and warn about cover letter
|
||
|
|
|
||
|
|
- **WHEN** application folder contains `cover-letter.md`
|
||
|
|
- **THEN** system displays warning message
|
||
|
|
- **AND** lists cover-letter.md as generated document
|
||
|
|
- **AND** stops archiving process
|
||
|
|
- **AND** requires `--force` flag to proceed
|
||
|
|
|
||
|
|
#### Scenario: Detect and warn about application email
|
||
|
|
|
||
|
|
- **WHEN** application folder contains `application-email.md`
|
||
|
|
- **THEN** system displays warning message
|
||
|
|
- **AND** lists application-email.md as generated document
|
||
|
|
- **AND** stops archiving process
|
||
|
|
- **AND** requires `--force` flag to proceed
|
||
|
|
|
||
|
|
#### Scenario: Detect and warn about attachments
|
||
|
|
|
||
|
|
- **WHEN** `attachments/` folder contains files (excluding `.keep`)
|
||
|
|
- **THEN** system displays warning message
|
||
|
|
- **AND** shows count of files in attachments folder
|
||
|
|
- **AND** stops archiving process
|
||
|
|
- **AND** requires `--force` flag to proceed
|
||
|
|
|
||
|
|
#### Scenario: Warning message provides clear options
|
||
|
|
|
||
|
|
- **WHEN** safety warning is displayed
|
||
|
|
- **THEN** message lists all detected documents
|
||
|
|
- **AND** explains that archiving will move everything
|
||
|
|
- **AND** provides three options: continue with --force, cancel to review, or backup first
|
||
|
|
- **AND** shows exact command to use with --force flag
|
||
|
|
|
||
|
|
#### Scenario: Force flag bypasses all warnings
|
||
|
|
|
||
|
|
- **WHEN** user provides `--force` flag
|
||
|
|
- **THEN** system skips all safety checks
|
||
|
|
- **AND** proceeds with archiving without warnings
|
||
|
|
- **AND** shows brief notice that --force was used
|
||
|
|
- **AND** completes archiving successfully
|
||
|
|
|
||
|
|
#### Scenario: No warning for empty attachments folder
|
||
|
|
|
||
|
|
- **WHEN** `attachments/` folder exists but only contains `.keep` file
|
||
|
|
- **THEN** system does NOT treat this as "having attachments"
|
||
|
|
- **AND** does NOT display warning about attachments
|
||
|
|
- **AND** proceeds with archiving (if no other documents found)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Status and Timestamp Tracking
|
||
|
|
|
||
|
|
The system SHALL update application metadata when archiving to maintain audit trail and lifecycle tracking.
|
||
|
|
|
||
|
|
#### Scenario: Update Status field for rejected application
|
||
|
|
|
||
|
|
- **WHEN** application is archived with reason "rejected"
|
||
|
|
- **THEN** system reads `application.md` file
|
||
|
|
- **AND** locates Status field in Metadata section
|
||
|
|
- **AND** replaces Status line with: `- **Status**: Rejected (Archived: YYYY-MM-DD HH:MM)`
|
||
|
|
- **AND** writes updated content back to file
|
||
|
|
- **AND** preserves all other content in application.md
|
||
|
|
|
||
|
|
#### Scenario: Update Status field for not-interested application
|
||
|
|
|
||
|
|
- **WHEN** application is archived with reason "not-interested"
|
||
|
|
- **THEN** system reads `application.md` file
|
||
|
|
- **AND** locates Status field in Metadata section
|
||
|
|
- **AND** replaces Status line with: `- **Status**: Not Interested (Archived: YYYY-MM-DD HH:MM)`
|
||
|
|
- **AND** writes updated content back to file
|
||
|
|
- **AND** preserves all other content in application.md
|
||
|
|
|
||
|
|
#### Scenario: Handle missing Status field
|
||
|
|
|
||
|
|
- **WHEN** application.md does not have Status field in Metadata section
|
||
|
|
- **THEN** system adds Status field to Metadata section
|
||
|
|
- **AND** sets Status to appropriate archived value with timestamp
|
||
|
|
- **AND** preserves existing Metadata section formatting
|
||
|
|
- **AND** proceeds with archiving
|
||
|
|
|
||
|
|
#### Scenario: Timestamp format
|
||
|
|
|
||
|
|
- **WHEN** Status field is updated with timestamp
|
||
|
|
- **THEN** timestamp follows format: YYYY-MM-DD HH:MM
|
||
|
|
- **AND** uses current date and time at moment of archiving
|
||
|
|
- **AND** uses 24-hour time format
|
||
|
|
- **AND** is human-readable and sortable
|
||
|
|
|
||
|
|
#### Scenario: Status update failure handling
|
||
|
|
|
||
|
|
- **WHEN** Status field update fails (file locked, permissions error)
|
||
|
|
- **THEN** system stops archiving process
|
||
|
|
- **AND** shows error message with details
|
||
|
|
- **AND** does NOT move application folder
|
||
|
|
- **AND** leaves application in pending folder unchanged
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Archive Folder Structure
|
||
|
|
|
||
|
|
The system SHALL maintain organized archive folders by reason while preserving application structure.
|
||
|
|
|
||
|
|
#### Scenario: Create rejected archive folder on first use
|
||
|
|
|
||
|
|
- **WHEN** user archives first application with reason "rejected"
|
||
|
|
- **AND** `applications/rejected/` folder does not exist
|
||
|
|
- **THEN** system creates `applications/rejected/` directory
|
||
|
|
- **AND** shows progress message: "Created archive directory: applications/rejected/"
|
||
|
|
- **AND** proceeds with archiving to new folder
|
||
|
|
|
||
|
|
#### Scenario: Create not-interested archive folder on first use
|
||
|
|
|
||
|
|
- **WHEN** user archives first application with reason "not-interested"
|
||
|
|
- **AND** `applications/not-interested/` folder does not exist
|
||
|
|
- **THEN** system creates `applications/not-interested/` directory
|
||
|
|
- **AND** shows progress message: "Created archive directory: applications/not-interested/"
|
||
|
|
- **AND** proceeds with archiving to new folder
|
||
|
|
|
||
|
|
#### Scenario: Preserve folder naming convention
|
||
|
|
|
||
|
|
- **WHEN** application is moved to archive
|
||
|
|
- **THEN** folder name remains unchanged (YYYY-MM-DD-Company-JobTitle format)
|
||
|
|
- **AND** application is placed in `applications/[reason]/[original-folder-name]/`
|
||
|
|
- **AND** date prefix is preserved for chronological sorting
|
||
|
|
|
||
|
|
#### Scenario: Preserve application structure
|
||
|
|
|
||
|
|
- **WHEN** application folder is moved to archive
|
||
|
|
- **THEN** all subfolders are preserved (input/, attachments/)
|
||
|
|
- **AND** all files are preserved (application.md, cover-letter.md, application-email.md)
|
||
|
|
- **AND** folder structure remains identical to pending folder structure
|
||
|
|
- **AND** no files are modified except application.md Status field
|
||
|
|
|
||
|
|
#### Scenario: Verify successful move
|
||
|
|
|
||
|
|
- **WHEN** move operation completes
|
||
|
|
- **THEN** system verifies destination folder exists: `applications/[reason]/[folder]/`
|
||
|
|
- **AND** verifies source folder no longer exists: `applications/pending/[folder]/`
|
||
|
|
- **AND** verifies application.md exists at destination
|
||
|
|
- **AND** only shows success message after verification passes
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Comprehensive Error Handling
|
||
|
|
|
||
|
|
The system SHALL provide clear, actionable error messages for all failure scenarios.
|
||
|
|
|
||
|
|
#### Scenario: Invalid reason parameter error
|
||
|
|
|
||
|
|
- **WHEN** user provides unsupported reason (not "rejected" or "not-interested")
|
||
|
|
- **THEN** system displays error message: "Invalid reason: [provided-reason]"
|
||
|
|
- **AND** lists valid options: rejected, not-interested
|
||
|
|
- **AND** explains what each reason means
|
||
|
|
- **AND** shows usage syntax
|
||
|
|
|
||
|
|
#### Scenario: Application not found error
|
||
|
|
|
||
|
|
- **WHEN** user provides application name that doesn't exist in pending
|
||
|
|
- **THEN** system displays error message: "Application not found: [application-name]"
|
||
|
|
- **AND** lists all available applications in `applications/pending/`
|
||
|
|
- **AND** shows usage syntax with application name parameter
|
||
|
|
|
||
|
|
#### Scenario: Not in application folder error
|
||
|
|
|
||
|
|
- **WHEN** user runs command without application name parameter
|
||
|
|
- **AND** current directory is not within an application folder
|
||
|
|
- **THEN** system displays error message: "Not in an application folder"
|
||
|
|
- **AND** explains two options: navigate to application folder, or provide application name
|
||
|
|
- **AND** lists available applications in pending folder
|
||
|
|
- **AND** shows example commands for both approaches
|
||
|
|
|
||
|
|
#### Scenario: Already archived error
|
||
|
|
|
||
|
|
- **WHEN** user tries to archive application that doesn't exist in pending
|
||
|
|
- **THEN** system displays error message: "Application not found in pending folder"
|
||
|
|
- **AND** suggests checking archive folders (rejected/, not-interested/)
|
||
|
|
- **AND** explains how to move between archives if needed
|
||
|
|
- **AND** does NOT show pending applications list (not relevant)
|
||
|
|
|
||
|
|
#### Scenario: File operation failure error
|
||
|
|
|
||
|
|
- **WHEN** move operation fails (permissions, disk space, concurrent access)
|
||
|
|
- **THEN** system displays error message: "Failed to archive application"
|
||
|
|
- **AND** includes specific error details from file system
|
||
|
|
- **AND** lists possible causes (permissions, disk space, file in use)
|
||
|
|
- **AND** confirms: "The application has NOT been modified"
|
||
|
|
- **AND** suggests checking the issue and trying again
|
||
|
|
|
||
|
|
#### Scenario: Permission denied error
|
||
|
|
|
||
|
|
- **WHEN** user lacks permissions to write to application.md or move folder
|
||
|
|
- **THEN** system displays error about insufficient permissions
|
||
|
|
- **AND** explains which operation failed (status update or folder move)
|
||
|
|
- **AND** suggests checking file/folder permissions
|
||
|
|
- **AND** ensures no partial changes (rollback any modifications)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Auto-Detection of Application Location
|
||
|
|
|
||
|
|
The system SHALL automatically detect the target application when run from within an application folder.
|
||
|
|
|
||
|
|
#### Scenario: Detect application from current directory
|
||
|
|
|
||
|
|
- **WHEN** user is in directory matching pattern `*/applications/pending/[folder-name]/`
|
||
|
|
- **AND** current directory contains `application.md` file
|
||
|
|
- **THEN** system automatically detects application to archive
|
||
|
|
- **AND** extracts folder name for use in move operation
|
||
|
|
- **AND** does NOT require application name parameter
|
||
|
|
|
||
|
|
#### Scenario: Verify application.md exists
|
||
|
|
|
||
|
|
- **WHEN** system detects application from current directory
|
||
|
|
- **THEN** system verifies `application.md` file exists
|
||
|
|
- **AND** shows error if application.md missing
|
||
|
|
- **AND** explains that directory doesn't appear to be valid application folder
|
||
|
|
|
||
|
|
#### Scenario: Handle subdirectories within application
|
||
|
|
|
||
|
|
- **WHEN** user is in subdirectory like `*/applications/pending/[folder]/input/`
|
||
|
|
- **THEN** system detects parent application folder
|
||
|
|
- **AND** resolves to correct application path
|
||
|
|
- **AND** proceeds with archiving parent application
|
||
|
|
|
||
|
|
#### Scenario: Explicit name overrides auto-detection
|
||
|
|
|
||
|
|
- **WHEN** user provides application name parameter
|
||
|
|
- **THEN** system uses provided name instead of auto-detecting
|
||
|
|
- **AND** ignores current directory location
|
||
|
|
- **AND** resolves to specified application in pending folder
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Requirement: Success Messaging and Confirmation
|
||
|
|
|
||
|
|
The system SHALL provide clear confirmation when archiving succeeds with relevant details.
|
||
|
|
|
||
|
|
#### Scenario: Display success message with details
|
||
|
|
|
||
|
|
- **WHEN** archiving completes successfully
|
||
|
|
- **THEN** system displays success message: "Application archived successfully"
|
||
|
|
- **AND** shows application name (Company - Job Title)
|
||
|
|
- **AND** shows original location: `applications/pending/[folder]/`
|
||
|
|
- **AND** shows archived location: `applications/[reason]/[folder]/`
|
||
|
|
- **AND** shows reason: "Rejected by company" or "No longer interested"
|
||
|
|
- **AND** shows updated Status: "Rejected (Archived: [timestamp])"
|
||
|
|
|
||
|
|
#### Scenario: Confirm preservation of all files
|
||
|
|
|
||
|
|
- **WHEN** success message is displayed
|
||
|
|
- **THEN** message confirms: "All documents intact"
|
||
|
|
- **AND** explains application can still be accessed at new location
|
||
|
|
- **AND** provides full path to archived application
|
||
|
|
|
||
|
|
#### Scenario: Success with --force flag
|
||
|
|
|
||
|
|
- **WHEN** archiving completes with --force flag
|
||
|
|
- **THEN** success message includes note: "Safety checks skipped (--force)"
|
||
|
|
- **AND** lists which documents were detected but bypassed
|
||
|
|
- **AND** confirms all documents were moved to archive
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Cross-References
|
||
|
|
|
||
|
|
### Related Capabilities
|
||
|
|
|
||
|
|
- **application-management**: Archiving is the final step in application lifecycle
|
||
|
|
- **application-validation**: Validation ensures applications are complete before potential archiving
|
||
|
|
- **cover-letter-generation**: Generated cover letters trigger safety warnings when archiving
|
||
|
|
- **application-email**: Generated emails trigger safety warnings when archiving
|
||
|
|
|
||
|
|
### Integration Points
|
||
|
|
|
||
|
|
- Status field in `application.md` (managed by application-management)
|
||
|
|
- Application folder structure (defined by application-management)
|
||
|
|
- Generated document detection (cover-letter.md, application-email.md)
|
||
|
|
- Attachments folder (created by application-management)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Technical Notes
|
||
|
|
|
||
|
|
### Status Field Update Implementation
|
||
|
|
|
||
|
|
**Pattern matching:**
|
||
|
|
```regex
|
||
|
|
^(\s*-\s*\*\*Status\*\*:\s*)(.*)$
|
||
|
|
```
|
||
|
|
|
||
|
|
**Replacement format:**
|
||
|
|
```markdown
|
||
|
|
- **Status**: [Rejected|Not Interested] (Archived: YYYY-MM-DD HH:MM)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Safety Check Detection
|
||
|
|
|
||
|
|
**Files to check:**
|
||
|
|
1. `cover-letter.md` in application folder
|
||
|
|
2. `application-email.md` in application folder
|
||
|
|
3. Any files in `attachments/` excluding `.keep`
|
||
|
|
|
||
|
|
**Warning triggered if ANY found**
|
||
|
|
|
||
|
|
### Archive Folder Paths
|
||
|
|
|
||
|
|
- Rejected: `src/applications/rejected/`
|
||
|
|
- Not interested: `src/applications/not-interested/`
|
||
|
|
|
||
|
|
**Folders created on-demand when first needed**
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Validation
|
||
|
|
|
||
|
|
This specification can be validated by:
|
||
|
|
|
||
|
|
1. Running `openspec validate archive-applications --strict`
|
||
|
|
2. Verifying all requirements have at least one scenario
|
||
|
|
3. Checking all scenarios follow WHEN/THEN/AND format
|
||
|
|
4. Confirming no placeholder text remains in requirements
|