#+TITLE: Status Check Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-02-02

* Overview

This workflow defines how Claude monitors and reports on long-running jobs (10+ minutes). It provides regular status updates, ETA estimates, and clear completion/failure signals with notifications.

Uses the =notify= command for completion/failure notifications.

* Problem We're Solving

Long-running jobs create uncertainty:

1. *Silent failures* - Jobs fail without notification, wasting time
2. *Missed completions* - Job finishes but user doesn't notice for hours
3. *No visibility* - User doesn't know if it's safe to context-switch
4. *Unknown ETAs* - No sense of when to check back

*Impact:* Delayed follow-up, wasted time, uncertainty about when to return attention to the task.

* Exit Criteria

The workflow is successful when:

1. Claude proactively monitors long-running tasks (10+ minutes)
2. Status updates arrive every 5 minutes with progress and ETA
3. Completion/failure is clearly announced with notification
4. Failures trigger investigation or confirmation before action

* When to Use This Workflow

Use automatically when:
- Network transfers (rsync, scp, file sync)
- Test suites expected to run long
- Build processes
- Any job estimated at 10+ minutes

Use when Craig requests:
- "Keep me posted on this"
- "Provide status checks on this job"  
- "Let me know when it's done"
- "Monitor this for me"

* Approach: How We Work Together

** Step 1: Initial Status

When a long-running job starts, report:

#+begin_example
HH:MM - description - ETA
19:10 - Starting file transfer of ~/videos to wolf - ETA ~30 minutes
#+end_example

Format: One line, under 120 characters.

** Step 2: Progress Updates (Every 5 Minutes)

Report progress with updated ETA:

#+begin_example
HH:MM - job description - update - ETA
19:15 - File transfer to wolf - now transferring files starting with "h" - ETA ~25 minutes
#+end_example

If ETA changes significantly, explain why:

#+begin_example
19:20 - File transfer to wolf - network speed dramatically reduced - ETA ~40 minutes
19:25 - File transfer to wolf - network speed recovered - ETA ~10 minutes
#+end_example

** Step 3: Completion

On success:

#+begin_example
HH:MM - job description SUCCESS! - elapsed time
19:35 - File transfer to wolf SUCCESS! - elapsed: ~25 minutes
#+end_example

Then:
1. Play success sound and show persistent notification
2. Report any relevant details (files transferred, tests passed, etc.)

#+begin_src bash
notify success "Job Complete" "File transfer to wolf finished" --persist
#+end_src

** Step 4: Failure

On failure:

#+begin_example
HH:MM - job description FAILURE! - elapsed time
Reason: Network connectivity dropped. Should I investigate, restart, or something else?
#+end_example

Then:
1. Play failure sound and show persistent notification
2. Investigate the reason OR ask for confirmation before diagnosing
3. Unless fix is trivial and obvious, ask before fixing or rerunning

#+begin_src bash
notify fail "Job Failed" "File transfer to wolf - network error" --persist
#+end_src

* Status Format Reference

| Situation | Format                                                   |
|-----------+----------------------------------------------------------|
| Initial   | =HH:MM - description - ETA=                                |
| Progress  | =HH:MM - job description - update - ETA=                   |
| Success   | =HH:MM - job description SUCCESS! - elapsed time=          |
| Failure   | =HH:MM - job description FAILURE! - elapsed time= + reason |

All status lines should be under 120 characters.

* Principles to Follow

** Reliability
Updates every 5 minutes, no exceptions. Status checks are never considered an interruption.

** Transparency
Honest progress reporting. If ETA changes, explain why. Don't silently adjust estimates.

** ETA Honesty
- Always try to estimate, even if uncertain
- If truly unknown, say "ETA unknown"
- When ETA changes significantly, explain the reason
- A wrong estimate with explanation is better than no estimate

** Fail Loudly
Never let failures go unnoticed. Always announce failures with sound and persistent notification.

** Ask Before Acting
On failure, investigate or ask - don't automatically retry or fix unless the solution is trivial and obvious.

* Implementation

** Monitoring with Sleep (Blocking)

To ensure 5-minute status updates happen reliably, use blocking sleep loops.
Do NOT use =at= for reminders - it only notifies the user, not Claude.

#+begin_src bash
# Check status, sleep 5 min, repeat until job completes
sleep 300 && date "+%H:%M" && tail -15 /path/to/output.log
#+end_src

This blocks the conversation but guarantees regular updates. The user has
explicitly approved this approach - status checks are never an interruption.

** Background Jobs

For jobs run in background via Bash tool:
1. Start job with =run_in_background: true=
2. Note the output file path
3. Use blocking sleep loop to check output every 5 minutes
4. Continue until job completes or fails

* Notification Reference

#+begin_src bash
# Success
notify success "Job Complete" "description" --persist

# Failure
notify fail "Job Failed" "description" --persist
#+end_src

* Living Document

Update as patterns emerge:
- Which jobs benefit most from monitoring
- ETA estimation techniques that work well
- Common failure modes and responses