Files

T

gurixandClaude Sonnet 4.5 c91999d78c chore: archive fix-coverletter-template-path change

Archived completed OpenSpec change after successful deployment.
The template path fix has been applied to specs and is now in production.

Change archived as: 2026-01-12-fix-coverletter-template-path

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

2026-01-12 21:51:51 +01:00

15 KiB

Raw Blame History

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

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:

^(\s*-\s*\*\*Status\*\*:\s*)(.*)$

Replacement format:

- **Status**: [Rejected|Not Interested] (Archived: YYYY-MM-DD HH:MM)

Safety Check Detection

Files to check:

cover-letter.md in application folder
application-email.md in application folder
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:

Running openspec validate archive-applications --strict
Verifying all requirements have at least one scenario
Checking all scenarios follow WHEN/THEN/AND format
Confirming no placeholder text remains in requirements

15 KiB Raw Blame History