## 🛠️ Proposal: Git Work Item Tracking (WorkFlow)

## 🛠️ Proposal: Git Work Item Tracking (WorkFlow)

This proposal outlines a new, optional feature for Git that allows developers to define, track, and complete discrete **Work Items** directly within the repository structure. This system provides a clear, version-controlled overview of project progress across multiple commits, branches, and development stages.

-----

## 1\. Core Concept: The Work Item Log (WIL)

The core idea is to introduce a dedicated, standardized file or metadata structure—the **Work Item Log (WIL)**—that lives within the Git repository (or in a specialized Git object) and is versioned alongside the code.

### Structure and State

Work Items would be simple, single-line descriptions associated with a status flag:

  * **To Do (New):** `-` (or similar symbol/keyword)
  * **Completed (Done):** `+` (or similar symbol/keyword)

**Example Work Item Log (WIL) Snapshot:**

```markdown
# Work Item Log for Feature X
- Implement user authentication module
- Write database schema migration script
- Add unit tests for API endpoints
+ Refactored legacy logging system
+ Configured CI/CD pipeline stage
```

-----

## 2\. Proposed Git Commands (Porcelain)

New commands would be introduced to manage the Work Item Log, ensuring developers interact with the log programmatically rather than manually editing a file (though manual edits should remain possible).

| Command | Description | Example Usage |
| :--- | :--- | :--- |
| `git work item add` | Adds a new work item to the "To Do" list in the current branch's WIL. | `git work item add "Implement feature Z"` |
| `git work item done` | Marks an existing, incomplete work item as "Completed." | `git work item done "Implement feature Z"` |
| `git work item list` | Displays the current state of the WIL for the checked-out commit/branch. | `git work item list --pending` |
| `git work item status` | Shows a summary of work item progress (e.g., 5/12 done). | `git work item status` |
| `git work item diff` | Shows how the WIL has changed between two commits or branches. | `git work item diff master..feature/new-ui` |

-----

## 3\. Key Benefits and Design Principles

### A. Versioning and Branch Specificity

Since the WIL is tracked by Git, it naturally supports per-branch and per-version work plans:

  * **Branch-Specific Plans:** A **feature branch** can track only the items relevant to that feature. When the feature branch is merged into `master`, the completed items (`+`) are integrated into `master`'s WIL, while incomplete items (`-`) remain in the branch history or are manually moved/re-prioritized.
  * **Auditability:** Using `git work item diff`, a developer can easily see what work was **started and finished** within a single commit, a range of commits, or over a developer's working period.

### B. Developer Focus and Workflow

This feature addresses the need for **short-term, high-frequency progress tracking** that current tools (like issue trackers) often fail to capture effectively:

  * **Daily Checklists:** A developer can start their day by reviewing `git work item list` to see their immediate tasks.
  * **Commit Integration:** A new hook could ensure that every commit message includes a summary of any work items marked `+` or `-` in that commit, linking the code change directly to the plan change.

### C. Orthogonality to Issue Trackers

The Work Item Log is **not** a replacement for external issue trackers (Jira, GitHub Issues, etc.).

  * **External Trackers:** Handle long-term planning, prioritization, assignments, and large-scale project management.
  * **WIL:** Handles **atomic, code-level tasks** tied directly to the source code being checked in, offering progress tracking that is local, fast, and version-controlled.

-----

## 4\. Implementation Direction (Technical Considerations)

This could be implemented in a few ways:

1.  **Dedicated Ref Namespace:** A new ref, such as `refs/worklog/<branch-name>`, could point to a specialized Git object storing the serialized Work Item Log data. This makes it non-intrusive to the working tree.
2.  **Specialized File:** Storing the log in a `.gitworklog` file, which is then tracked and committed. This is simpler but requires careful handling of merge conflicts in the log file itself.

The goal is to provide a **standardized, scriptable API** via new commands, making it easier for developers to track their micro-progress without leaving the Git environment.

Bye,
  Skybuck Flying.