From 3a2445080c880544985f50fb0d916534698cc073 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sun, 22 Feb 2026 23:20:56 -0600 Subject: chore: add docs/ to .gitignore and untrack personal files docs/ contains session history, personal workflows, and private protocols that shouldn't be in a public repository. --- docs/workflows/status-check.org | 178 ---------------------------------------- 1 file changed, 178 deletions(-) delete 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 deleted file mode 100644 index efff16d..0000000 --- a/docs/workflows/status-check.org +++ /dev/null @@ -1,178 +0,0 @@ -#+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