org-agent-contrib/org-skill-org-gtd-archive-roam-daily.org

SKILL: Org-GTD Archive Roam Daily (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Successful extraction of [YYYY-MM-DD] from
    • Automated creation of non-existent daily files during archive
    • Subtree relocation verification
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces (Lisp Signatures)

Overview

The Org-GTD Archive Roam Daily skill enables chronological archiving of completed GTD tasks. Instead of a flat archive file, tasks are moved to their respective `org-roam-dailies` files based on their `:CREATED:` property, preserving contextual and temporal integrity.

Phase A: Demand (PRD)

1. Purpose

Define the requirements for chronologically-aware task archiving.

2. User Needs

• Temporal Alignment: Archive tasks to the daily file matching their creation date.
• Context Preservation: Maintain all properties and sub-elements during the move.
• Robust Extraction: Correctly parse `:CREATED:` property timestamps.
• Fail-safe Logic: Default to current date if `:CREATED:` is missing (with a warning).

3. Success Criteria

TODO Successful extraction of [YYYY-MM-DD] from   CREATED

TODO Automated creation of non-existent daily files during archive

TODO Subtree relocation verification

Phase B: Blueprint (PROTOCOL)

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

The system will utilize Emacs Lisp to extract the `:CREATED:` property from a GTD task, derive a date, locate (or create) the corresponding `org-roam-daily` file, and move the task subtree to that file. Error handling will include a fallback mechanism to the current date, accompanied by a user notification. The design emphasizes modularity and testability.

2. Semantic Interfaces (Lisp Signatures)

• `(org-gtd-archive-roam-daily &optional subtree)`

  • Purpose: Main entry point. Archives a GTD task to its corresponding `org-roam-daily` file based on the `:CREATED:` property.

  • Arguments:

    • `subtree` (optional): The subtree to archive. Defaults to the current subtree.
  • Return Value: `t` on success, `nil` on failure.
  • Side Effects: Modifies Org files.

• `(org-gtd-archive-roam-daily-extract-created-date subtree)`

  • Purpose: Extracts the date from the `:CREATED:` property of a subtree.

  • Arguments:

    • `subtree`: The subtree to extract the date from.
  • Return Value: A string in `YYYY-MM-DD` format, or `nil` if the property is missing or invalid.

• `(org-gtd-archive-roam-daily-get-daily-file-path date)`

  • Purpose: Determines the file path for a given date, according to `org-roam-dailies` conventions.

  • Arguments:

    • `date`: A string in `YYYY-MM-DD` format.
  • Return Value: A string representing the file path.

• `(org-gtd-archive-roam-daily-ensure-daily-file-exists file-path)`

  • Purpose: Creates an `org-roam-daily` file if it does not already exist.

  • Arguments:

    • `file-path`: The path to the `org-roam-daily` file.
  • Return Value: `t` if the file exists (either originally or after creation), `nil` if creation failed.
  • Side Effects: Creates a new file.

• `(org-gtd-archive-roam-daily-move-subtree subtree file-path)`

  • Purpose: Moves a subtree to a specified file.

  • Arguments:

    • `subtree`: The subtree to move.
    • `file-path`: The destination file path.
  • Return Value: `t` on success, `nil` on failure.
  • Side Effects: Modifies Org files.

• `(org-gtd-archive-roam-daily-warn message)`

  • Purpose: Displays a warning message to the user.

  • Arguments:

    • `message`: The warning message to display.
  • Return Value: `nil`
  • Side Effects: Displays a message.