SKILL.md

name	progress-archive
description	Progress file constraints. MUST archive completed phases when file exceeds ~200 lines. MUST preserve original text verbatim — archive is move, not delete. NEVER leave 500+ line progress files uncompressed. NEVER discard history or summarize archive content. MUST read SKILL.md BEFORE editing any progress file.
license	MIT
metadata	author version motiful 2.0

Progress Archive — Progress File Constraint

Standalone rule-skill (no capability counterpart). Constraints + procedure in one.

Archival Rules

• MUST archive completed phases when progress file exceeds ~200 lines — long files waste agent context and bury current state
• MUST preserve original text verbatim in archive files — archive is a historical record, not a summary
• MUST keep all incomplete tasks and their context untouched in the main file — removing context that open tasks depend on breaks continuity
• MUST use relative paths in archive links — absolute paths break when repo moves
• NEVER discard completed content — archive is move, not delete
• NEVER summarize or rewrite content in the archive file — lossy compression destroys decisions and rationale
• NEVER archive a section with incomplete sub-tasks — move the sub-tasks to an active section first
• SHOULD keep recent update log entries in main file — move older ones with the archive

Execution Procedure

def archive_progress(target_file):
    # STEP 1: Detect archive location
    archive_dir = detect_archive_dir(target_file)
    # Probe order: docs/archive/ → _archive/ → backstage/tracks/
    #   → .claude/archive/ → any historical docs dir
    # If none found → create docs/archive/ (or ask user if project has convention)

    # STEP 2: Identify completed sections
    sections = parse_sections(target_file)
    completed = [s for s in sections if s.is_marked_complete]
    # MUST: skip sections with incomplete sub-tasks
    # MUST: skip sections whose context is needed by open tasks (dependency chain)

    # STEP 3: Create archive file
    # Naming: {original-stem}-{phase-or-milestone}-{YYYY-MM-DD}.md
    archive_path = f"{archive_dir}/{stem}-{milestone}-{date}.md"
    write_archive(archive_path, completed)
    # MUST: full original text, verbatim, no summarization

    # STEP 4: Compress main file
    for section in completed:
        replace_with_stub(target_file, section)
        # Stub template: see §Compression Stub Template below

    # STEP 5: Verify
    assert line_count(target_file) < 200 or significantly_reduced
    assert reads_coherently(target_file)
    assert no_dangling_references(target_file)
    assert all_incomplete_tasks_have_full_context(target_file)
    assert archive_file_committed_or_staged(archive_path)

Compression Stub Template

## [Phase/Milestone Name] — Archived

**Completed**: YYYY-MM-DD
**Archive**: `relative/path/to/archive-file.md`

**Summary**:
- Key output 1
- Key output 2

**Decisions carried forward** (affecting open work):
- Decision 1
- Decision 2