From 6787fb160c80118b80df37c01cb69dcfbebfff17 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 7 Feb 2026 21:41:19 -0600 Subject: docs: sync templates, rename workflows and notes.org Sync from templates. Rename NOTES.org to notes.org, session-wrap-up to wrap-it-up, retrospective-workflow to retrospective, session-start to startup. Update all references. --- docs/workflows/status-check.org | 178 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 docs/workflows/status-check.org (limited to 'docs/workflows/status-check.org') diff --git a/docs/workflows/status-check.org b/docs/workflows/status-check.org new file mode 100644 index 0000000..efff16d --- /dev/null +++ b/docs/workflows/status-check.org @@ -0,0 +1,178 @@ +#+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 -- cgit v1.2.3