Updating Work Item

Overview

Update progress on an existing work item: change status, record actual effort, add test results, mark related commits, validate dependencies, and add implementation notes as work progresses.

When to Use

Update a work item when:

• Starting work (change status to in-progress)
• Completing implementation (change status to ready-for-review)
• Recording actual hours spent
• Adding related commit hashes
• Logging test results or CI status
• Adjusting estimates based on new information
• Adding implementation notes or blockers
• Validating dependencies before closing

When NOT to Use

Skip updates for:

• Creating new items (use creating-work-item skill)
• Finalizing and archiving (use finalizing-work-item skill)
• Minor comments (just edit as needed, no skill required)

Frontmatter Fields

Status and Status Reason Fields

status: proposed | ready | in-progress | ready-for-review | closed
status_reason: null | success | obsolete | redundant | superseded | cancelled

Status	status_reason	Meaning	When to Use
proposed	(none)	Work item proposed but not yet ready	Initial creation
ready	(none)	Work item ready to start	Prior to in-progress
in-progress	(none)	Active development	Actively working
ready-for-review	(none)	Impl done, awaiting review/tests	Tests running, PR submitted
closed	success	Finished successfully	All criteria met, merged
closed	obsolete	No longer relevant	Market changed, approach outdated
closed	redundant	Duplicate item	Same work in another item
closed	superseded	Made moot by other item	Different item solves it better
closed	cancelled	Work stopped	Stopped, won't implement

Important: Before transitioning to closed, validate that all items in links.depends_on are already in closed status.

Effort Tracking

estimated: 20 # Set when created (hours as decimal)
actual: 18 # Update as work progresses, finalize when complete
completed_date: null # Set when status = closed (YYYY-MM-DD format)

Guidelines:

• estimated: Set once, don't change unless scope significantly shifts
• actual: Start as null, update when complete
• completed_date: Set only when moving to closed status

Commit Tracking

commits:
  6d8c044: "feat(sdk): initial FilterAdapter interface"
  f00459b: "feat(filters): implement selectattr and map"
  a1b2c3d: "docs: add filter usage examples"

Record commit SHAs (7+ character hashes or 40-character full hashes) mapped to their commit messages. Helps trace implementation back to work items.

To get commit message:

git log <short_hash> -n 1 --pretty=format:"%s"

Test Results

test_results:
  - timestamp: 2024-06-01T12:00:00Z
    note: "https://github.com/squirrel289/temple/actions/runs/12345678"

Record test results with timestamps:

test_results:
  - timestamp: 2024-06-01T12:00:00Z
    note: "All 47 tests pass, coverage 89%"
  - timestamp: 2024-06-02T10:00:00Z
    note: "3 test failures in test_renderer.py (see PR comments)"

Dependencies

links:
  depends_on:
    - "[[wi-054_complete_temple_native.md]]"
    - "[[wi-043_implement_template_syntax_validation.md]]"

Update if new dependencies emerge during implementation. Critical: Before closing a work item, verify all items in links.depends_on are already closed.

Workflow: Updating Work Items

1. Moving to In-Progress

When starting work (changing status from proposed or ready to in-progress):

1. If executing multiple work items in parallel, use parallel-execution skill to ensure workspace isolation: one git worktree per WI with main agent handling all git/PR operations and subagents implementing code only.

2. Automatically create and checkout a local feature branch via feature-branch-management skill:

   # Triggered automatically when status: in-progress
   feature-branch-management create feature/wi-060

   • Branch naming convention: feature/wi-<id> (e.g., feature/wi-060)
   • Branch is created from main and checked out automatically
   • If the branch already exists, it is checked out
   • This ensures all work is isolated and traceable to the work item

3. Validate branch state via guarding-branches aspect before first commit:

   • Confirm you're on the correct feature branch
   • Verify no untracked files or uncommitted changes from previous work
   • Run git clean -n to preview cleanup if needed

4. Update the work item file frontmatter:

   ---
   title: "Implement FilterAdapter"
   id: "wi-060"
   status: in-progress
   priority: high
   estimated: 20
   actual: 2
   completed_date: null
   status_reason: null
   notes:
     - timestamp: 2024-06-01T12:00:00Z
       note: |
         Started implementation of FilterAdapter in packages/core/.
         Initial focus: selectattr and map filters.
   ---

5. Update actual as work progresses:

   actual: 5 # Increment as work progresses, use decimals (e.g., 5.5 for 5h 30m)

2. Recording Actual Hours

As work progresses, update actual:

estimated: 20
actual: 6 # 2 hours initial + 4 more hours

Update periodically (after major milestones, at end of session) so you have a sense of actual time investment.

3. Adding Related Commits

When work is committed, record the commit SHA and message:

commits:
  6d8c044: "feat(sdk): FilterAdapter interface"
  f00459b: "feat(filters): selectattr and map"
  a1b2c3d: "docs: add filter usage examples"

Use short (7-character) or full (40-character) hashes as keys, with commit subject as the value.

Keep hashes in chronological order. Multiple commits are fine—they show the evolution of the work.

4. Transitioning to Ready-for-Review

When implementation is done and ready for review, move to ready-for-review:

1. Validate all changes via validating-changes skill:

   • Run local CI tests: pnpm test:affected:ci
   • If tests fail, add regression tests and fix code, then re-run until all pass
   • Verify no unintended file deletions: git diff origin/main...HEAD --name-status | grep '^D' (should return nothing)
   • Confirm only files related to this WI are modified

2. Validate branch state via guarding-branches aspect:

   • Verify no untracked files: git status --porcelain | grep "^??" (should return nothing)
   • Confirm no uncommitted changes: git status (working tree clean)
   • Verify branch contains only atomic, WI-scoped commits

3. Sync branch with main via feature-branch-management:

   # Triggered automatically when status: ready-for-review
   feature-branch-management sync --base=main

   • Rebases feature branch on latest main to avoid conflicts
   • Ensures clean commit history for PR review
   • If conflicts detected, will prompt with suggested resolution steps

4. Create Pull Request via create-pr skill (automatic):

   # Triggered automatically when status: ready-for-review
   create-pr work_item=wi-060

   • PR title auto-generated: "wi-060: Implement FilterAdapter"
   • PR description auto-generated from work item notes + commit history
   • PR links to work item via "Closes wi-060" reference
   • PR URL recorded in work item metadata

5. Update work item frontmatter:

   status: ready-for-review
   actual: 18 # Finalize effort
   status_reason: null
   links:
     pull_requests:
       - "https://github.com/templjs/templjs/pull/247"
   notes:
     - timestamp: 2024-06-01T12:00:00Z
       note: |
         Implementation complete. All filters implemented with type signatures.
         PR submitted for review: #247
         Awaiting code review and approval.

Do NOT set completed_date or status_reason yet.

5. Recording Test Results

After running tests:

status: ready-for-review
test_results:
  - timestamp: 2024-06-01T12:00:00Z
    note: "https://github.com/templjs/templjs/actions/runs/98765432"
  - timestamp: 2024-06-02T08:00:00Z
    note: |
      CI results:
      - 98 tests pass
      - 2 tests fail in test_filter_edge_cases.py (filter_args validation)
      - Coverage 87% (target 85%)

      Known issues:
      - Filter arg validation too strict for varargs
      - Will fix in follow-up PR

If tests fail, add notes on what needs fixing. Update status back to in-progress if rework needed:

status: in-progress
actual: 19
test_results:
  - timestamp: 2024-06-02T10:00:00Z
    note: "Test failures exposed issue with varargs handling. Reworking in feature/wi-060."
notes:
  - timestamp: 2024-06-02T10:00:00Z
    note: "Tests exposed issue with varargs handling. Working on fix."

6. Moving to Closed

When all tests pass, work is approved, and PR is merged:

1. Verify dependencies closed: Before moving to closed, check that all items in links.depends_on have status: closed

2. Validate branch safety via guarding-branches aspect:

   • Confirm PR is MERGEABLE and no branch protection rules are blocking merge
   • If auto-merge is required by branch policy, enable it; otherwise approve and merge manually
   • After merge, perform post-merge validation: run CI tests and verify no regressions

3. Update work item frontmatter:

   status: closed
   status_reason: success
   actual: 22
   completed_date: 2026-02-12
   test_results:
     - timestamp: 2024-06-01T12:00:00Z
       note: "https://github.com/templjs/templjs/actions/runs/98765432"
   links:
     pull_requests:
       - "https://github.com/templjs/templjs/pull/247"
   commits:
     a1b2c3d: "chore: merge PR #247 (FilterAdapter implementation)"
   notes:
     - timestamp: 2024-06-02T15:00:00Z
       note: |
         All acceptance criteria met:
         - FilterAdapter interface implemented and documented
         - Core filters (selectattr, map, join, default) working
         - 95% test coverage
         - Code reviewed and approved
         - Merged to main

Set status_reason to one of:

• success: Normal completion with acceptance criteria met
• obsolete: Item no longer needed (note why in notes)
• redundant: Duplicate of another item (reference it via links)
• superseded: Made moot by another item (reference it via links)
• cancelled: Work stopped before completion (note why in notes)

Leave file in /backlog/. The finalizing-work-item skill handles archiving to /backlog/archive/.

7. Adjusting Estimates

If scope changes significantly during work:

estimated: 28 # Increased from 20 due to validation requirements
actual: 14
notes:
  - timestamp: 2024-06-01T12:00:00Z
    note: |
      Scope expanded: discovered need for JSON Schema validation in filter 
      arguments. Adjusted estimate by +8 hours.

Or revert the work item to proposed if scope change is fundamental:

status: proposed
estimated: 28
actual: 14
notes:
  - timestamp: 2024-06-01T12:00:00Z
    note: "Scope significantly expanded. Reverting to proposed for re-estimation."

8. Updating Dependencies

If new dependencies discovered during work:

links:
  depends_on:
    - "[[wi-054_complete_temple_native.md]]"
    - "[[wi-044_implement_semantic_validation.md]]" # Added: type checking needed

Update the work item file to reflect these. Document in notes why the dependency was added.

Examples

Example 1: Feature Work Progress

Initial creation (status: proposed):

---
title: "Implement FilterAdapter"
id: "wi-060"
status: proposed
priority: high
estimated: 20
actual: null
completed_date: null
status_reason: null
links:
  depends_on:
    - "[[wi-054_complete_temple_native.md]]"
---

After moving to in-progress (2 hours):

status: in-progress
actual: 2
notes:
  - timestamp: 2024-06-01T12:00:00Z
    note: |
      Started with interface design and type signatures.
      SelectAttr filter drafted.

After ready-for-review (18 hours):

status: ready-for-review
status_reason: null
actual: 18
commits:
  6d8c044: "feat(sdk): FilterAdapter interface"
  f00459b: "feat(filters): selectattr, map, join, default"
links:
  pull_requests:
    - "https://github.com/templjs/templjs/pull/247"
test_results:
  - timestamp: 2024-06-01T18:00:00Z
    note: "https://github.com/templjs/templjs/actions/runs/12345678"
notes:
  - timestamp: 2024-06-01T18:00:00Z
    note: |
      Implementation complete. All tests pass. 95% coverage.
      PR #247 submitted for review.

After merge to closed (22 hours):

status: closed
status_reason: success
actual: 22
completed_date: 2026-02-12
test_results:
  - timestamp: 2024-06-01T18:00:00Z
    note: "https://github.com/templjs/templjs/actions/runs/12345678"
links:
  pull_requests:
    - "https://github.com/templjs/templjs/pull/247"
commits:
  6d8c044: "feat(sdk): FilterAdapter interface"
  f00459b: "feat(filters): selectattr, map, join, default"
  a1b2c3d: "merge: PR #247 FilterAdapter implementation"
notes:
  - timestamp: 2024-06-02T12:00:00Z
    note: |
      Merged to main. All acceptance criteria met.
      Ready for finalization.

Example 2: Bug Fix with Rework

Starting work:

---
title: "Fix elif parsing edge case"
id: "wi-059"
status: in-progress
estimated: 4
actual: 1
---

Test failure (rework needed):

status: in-progress
actual: 3
test_results:
  - timestamp: 2024-06-01T10:00:00Z
    note: "Local: 1 test fails in test_parser.py::test_consecutive_elif"
notes:
  - timestamp: 2024-06-01T10:00:00Z
    note: |
      Found deeper issue: elif blocks interfere when nested.
      Need to refactor block termination logic.
      Revising approach—effort may exceed estimate.

Resolution (ready-for-review):

status: ready-for-review
actual: 7
estimated: 4
commits:
  abc1234: "fix(parser): elif block termination logic"
test_results:
  - timestamp: 2024-06-01T14:00:00Z
    note: "https://github.com/templjs/templjs/actions/runs/87654321"
notes:
  - timestamp: 2024-06-01T14:00:00Z
    note: |
      Fixed by refactoring block_ends() logic. Took longer due to edge cases.
      All tests now pass including new consecutive_elif tests.
      PR submitted for review.

Example 3: Spike/Research Update

---
title: "Evaluate expression engines"
id: "wi-061"
status: in-progress
estimated: 16
actual: 8
notes:
  - timestamp: 2024-06-01T08:00:00Z
    note: |
      Evaluation candidates:
      1. JMESPath - mature, good for JSON, limited type support
      2. Custom recursive descent - flexible, small footprint
      3. meval - lightweight Python evaluator

      Progress:
      - JMESPath prototype working (2h)
      - Custom parser WIP (6h) - complexity clear now, drafting comparison doc

      Leaning toward option 2 (custom) due to control of type system.
---

Common Patterns

Weekly Status Update

Review active work items weekly:

status: in-progress
actual: 12 # Update from 10
notes:
  - timestamp: 2024-06-08T17:00:00Z
    note: |
      Week of Feb 10: 2 hours progress (mid-week catchup).
      Current blockers: Decision on filter signature format—waiting for architecture review.
      Expected completion: Feb 17

Handling Blockers

notes:
  - timestamp: 2024-06-01T14:00:00Z
    note: |
      BLOCKED: Waiting for ADR-006 decision on expression language.
      Cannot finalize filter syntax without it.
      Unblocked when: ADR merged and decision published
      Impact: Pushed completion target to 2026-02-20

Scope Creep Recognition

notes:
  - timestamp: 2024-06-01T14:00:00Z
    note: |
      Original estimate: 12 hours (selectattr, map, join)
      Current scope: +default filter + type validation = ~18 hours likely
      Recommendation: Create follow-up item for advanced filters, limit this to core 3.

Tips & Conventions

Atomic Updates

Each update should correspond to a logical work milestone:

• End of session: time tracking
• After tests run: test results
• After commit: commit hash
• Status change: full progress summary

Don't update work items excessively—focus on meaningful changes.

Notes Field

Use notes for:

• Progress summary
• Blockers or issues
• Scope changes
• Decision points
• Follow-up items

Avoid: detailed implementation notes (keep in commit messages instead)

Time Tracking Accuracy

Record hours regularly:

• At end of each session
• After significant milestone
• Final tally when completed

Use decimals for partial hours (e.g., 5.5 for 5 hours 30 minutes).

Commit Message Integration

Reference work items in commit messages (align with commitlint rules if used):

feat(filters): implement selectattr and map

Implements core filtering operations for FilterAdapter.
Supports filtering sequences by attribute value and projection.

Closes [[wi-060_implement_filter_adapter]]

Then update the work item with the commit hash.

Related Skills

• creating-work-item: For creating new work items from scratch
• feature-branch-management: Invoked automatically on status transitions (create branch on in-progress, sync on ready-for-review)
• create-pr: Invoked automatically when status → ready-for-review (create PR from feature branch)
• handle-pr-feedback: For addressing PR review feedback and managing rework
• resolve-pr-comments: For addressing specific code review comments
• finalizing-work-item: For archiving completed work items after merge
• git-commit: For recording commits that can be linked in commits