Failure Triage Implementation Plan¶
History. Done on 2026-04-05 (#113): triage_failed_torrent() in transmission-done.sh.
For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
Goal: When transmission-done cannot process a torrent, categorize the failure, move files to a triage directory, and remove the torrent from Transmission — keeping pending-move clean and giving the operator clear hints for manual resolution.
Architecture: Add a triage_failed_torrent() function
to transmission-done.sh that classifies failures from
FileBot output, moves the torrent to a category-specific
subdirectory under Media/Torrents/triage/, and returns 0
so the trigger watcher treats it as "handled" (cleaning up
the trigger and removing from Transmission). The
classification uses patterns already identified in
log_filebot_error().
Tech Stack: Pure Bash 5.x, BATS tests, existing FileBot output parsing
Triage Categories¶
Based on observed FileBot output patterns:
| Category | Directory |
|---|---|
| Already in Plex | triage/already-in-plex/ |
| No match | triage/no-match/ |
| Other failure | triage/failed/ |
Detection patterns:
- already-in-plex:
[AUTO] Skipped.*already existsor[IMPORT] Destination file already exists - no-match:
Processed 0 fileswithout "already exists"; orunable to identify/no match/no results - failed: Anything else (network, license, perms)
Key Design Decisions¶
- Triage happens in
process_media()afterprocess_media_with_fallback()fails — this is whereLAST_FILEBOT_OUTPUTis available for classification. - Triage returns 0 (success) so the trigger watcher cleans up the trigger file and removes the torrent from Transmission. Files preserved in triage for review.
TRIAGE_BASEderived fromTR_TORRENT_DIR(the download parent, e.g.,.../Torrents/pending-move), replacingpending-movewithtriage/<category>.- Move uses
mv(NFS-safe, no opendir needed). - Manual mode skips triage — interactive users can see the error and decide. Triage is automated-only.
- Preview failures also get triaged — when
preview_filebot_changes()fails, that's "no match".
Task 1: Add classify_failure() function¶
Files:
- Modify:
app-setup/templates/transmission-done.sh— add afterlog_filebot_error()(~line 520) - Test:
tests/transmission-filebot/unit/test_error_logging.bats— add classification tests
Step 1: Write the failing tests
Add to tests/transmission-filebot/unit/test_error_logging.bats:
# --- Failure classification tests ---
@test "classify_failure: detects already-in-plex from Skipped pattern" {
local output='[AUTO] Skipped [/path/to/file.mkv] because [/dest/file.mkv] already exists
Processed 0 files'
run classify_failure "${output}"
assert_success
assert_output "already-in-plex"
}
@test "classify_failure: detects already-in-plex from IMPORT pattern" {
local output='[IMPORT] Destination file already exists: /dest/file.mkv (/src/file.mkv)
Processed 0 files'
run classify_failure "${output}"
assert_success
assert_output "already-in-plex"
}
@test "classify_failure: detects no-match from zero processed" {
local output='Rename episodes using [TheMovieDB]
Lookup via [SomeShow]
Processed 0 files'
run classify_failure "${output}"
assert_success
assert_output "no-match"
}
@test "classify_failure: detects no-match from identification failure" {
local output='unable to identify media files'
run classify_failure "${output}"
assert_success
assert_output "no-match"
}
@test "classify_failure: returns failed for empty output" {
run classify_failure ""
assert_success
assert_output "failed"
}
@test "classify_failure: returns failed for network errors" {
local output='connection timeout reaching TheTVDB'
run classify_failure "${output}"
assert_success
assert_output "failed"
}
Step 2: Run tests to verify they fail
Run: bats tests/transmission-filebot/unit/test_error_logging.bats
Expected: 6 new tests FAIL with "classify_failure: command not found"
Step 3: Implement classify_failure()
Add to transmission-done.sh after log_filebot_error() (~line 520):
# Classify a FileBot failure into a triage category.
# Reads the combined FileBot output from all fallback strategies.
# Returns one of: "already-in-plex", "no-match", "failed"
classify_failure() {
local filebot_output="$1"
# Already in Plex: FileBot found a match but the destination file exists
if echo "${filebot_output}" | grep -qiE "already exists|Skipped.*already exists"; then
echo "already-in-plex"
return 0
fi
# No match: FileBot couldn't identify the media at all
if echo "${filebot_output}" | grep -qiE "unable to identify|no match|no results|failed to fetch"; then
echo "no-match"
return 0
fi
# No match: FileBot found candidates but processed 0 files (ambiguous match)
if echo "${filebot_output}" | grep -q "Processed 0 files"; then
echo "no-match"
return 0
fi
# Everything else: network errors, license issues, permissions, etc.
echo "failed"
return 0
}
Step 4: Run tests to verify they pass
Run: bats tests/transmission-filebot/unit/test_error_logging.bats
Expected: All tests PASS (existing 16 + 6 new = 22)
Step 5: Commit
git add app-setup/templates/transmission-done.sh tests/transmission-filebot/unit/test_error_logging.bats
git commit -m "feat(transmission-filebot): add classify_failure() for triage categories"
Task 2: Add triage_failed_torrent() function¶
Files:
- Modify:
app-setup/templates/transmission-done.sh— add afterclassify_failure() - Test:
tests/transmission-filebot/unit/test_error_logging.bats— add triage tests
Step 1: Write the failing tests
Add to tests/transmission-filebot/unit/test_error_logging.bats:
# --- Triage function tests ---
@test "triage_failed_torrent: moves directory to correct triage category" {
local triage_base="${BATS_TEST_TMPDIR}/triage"
local source="${BATS_TEST_TMPDIR}/pending-move/TestTorrent"
mkdir -p "${source}"
touch "${source}/video.mkv"
run triage_failed_torrent "${source}" "no-match" "${triage_base}"
assert_success
assert_dir_exists "${triage_base}/no-match/TestTorrent"
assert_file_exists "${triage_base}/no-match/TestTorrent/video.mkv"
assert_file_not_exists "${source}/video.mkv"
}
@test "triage_failed_torrent: moves single file to triage category" {
local triage_base="${BATS_TEST_TMPDIR}/triage"
local source="${BATS_TEST_TMPDIR}/pending-move/Movie.2024.mkv"
mkdir -p "${BATS_TEST_TMPDIR}/pending-move"
touch "${source}"
run triage_failed_torrent "${source}" "already-in-plex" "${triage_base}"
assert_success
assert_file_exists "${triage_base}/already-in-plex/Movie.2024.mkv"
assert_file_not_exists "${source}"
}
@test "triage_failed_torrent: creates triage directory if missing" {
local triage_base="${BATS_TEST_TMPDIR}/triage"
local source="${BATS_TEST_TMPDIR}/pending-move/Test"
mkdir -p "${source}"
touch "${source}/file.mkv"
# triage_base doesn't exist yet
assert_file_not_exists "${triage_base}"
run triage_failed_torrent "${source}" "failed" "${triage_base}"
assert_success
assert_dir_exists "${triage_base}/failed/Test"
}
@test "triage_failed_torrent: handles name collision by appending timestamp" {
local triage_base="${BATS_TEST_TMPDIR}/triage"
local source="${BATS_TEST_TMPDIR}/pending-move/TestTorrent"
mkdir -p "${source}" "${triage_base}/no-match/TestTorrent"
touch "${source}/video.mkv"
run triage_failed_torrent "${source}" "no-match" "${triage_base}"
assert_success
# Original source should be gone
assert_file_not_exists "${source}/video.mkv"
}
@test "triage_failed_torrent: logs the triage action" {
local triage_base="${BATS_TEST_TMPDIR}/triage"
local source="${BATS_TEST_TMPDIR}/pending-move/TestTorrent"
mkdir -p "${source}"
touch "${source}/video.mkv"
triage_failed_torrent "${source}" "no-match" "${triage_base}"
assert_file_exists "${LOG_FILE}"
run grep "Triaged to" "${LOG_FILE}"
assert_success
}
Step 2: Run tests to verify they fail
Run: bats tests/transmission-filebot/unit/test_error_logging.bats
Expected: 5 new tests FAIL
Step 3: Implement triage_failed_torrent()
Add to transmission-done.sh after classify_failure():
# Move a failed torrent to a triage directory based on failure category.
# Args: $1=torrent_path, $2=category (from classify_failure), $3=triage_base_dir
# The triage directory structure is:
# triage/already-in-plex/ — FileBot matched but destination exists
# triage/no-match/ — FileBot couldn't identify the media
# triage/failed/ — other errors (network, license, permissions)
triage_failed_torrent() {
local torrent_path="$1"
local category="$2"
local triage_base="$3"
local torrent_name
torrent_name=$(basename "${torrent_path}")
local dest_dir="${triage_base}/${category}"
mkdir -p "${dest_dir}" 2>/dev/null || true
# Handle name collision: append timestamp if destination already exists
local dest="${dest_dir}/${torrent_name}"
if [[ -e "${dest}" ]]; then
dest="${dest_dir}/${torrent_name}.$(date +%Y%m%d-%H%M%S)"
fi
if mv "${torrent_path}" "${dest}" 2>/dev/null; then
log "Triaged to ${category}: ${torrent_name} → ${dest}"
return 0
else
log "Warning: Failed to move ${torrent_name} to triage/${category}"
return 1
fi
}
Step 4: Run tests to verify they pass
Run: bats tests/transmission-filebot/unit/test_error_logging.bats
Expected: All tests PASS
Step 5: Commit
git add app-setup/templates/transmission-done.sh tests/transmission-filebot/unit/test_error_logging.bats
git commit -m "feat(transmission-filebot): add triage_failed_torrent() to move failures to categorized dirs"
Task 3: Wire triage into process_media() and main()¶
Files:
- Modify:
app-setup/templates/transmission-done.sh:1205-1265(process_media) and1426-1489(main)
Step 1: Modify process_media() to return triage info
The key insight: process_media() currently returns 1 on failure. Instead, when in automated mode, it should triage the failure and return 0 (handled). The caller (main()) needs to know whether media was successfully processed vs triaged, so it can log appropriately.
Replace the failure path in process_media() (~line 1238-1241):
# Step 5: Process with comprehensive fallback strategy
LAST_FILEBOT_OUTPUT=""
if ! process_media_with_fallback "${source_dir}"; then
log "Error: All FileBot strategies failed"
log_filebot_error 1 "${LAST_FILEBOT_OUTPUT}" "${source_dir}" "fallback-chain"
# In automated mode, triage the failure instead of leaving it in pending-move
if [[ "${INVOCATION_MODE}" == "automated" ]]; then
local category
category=$(classify_failure "${LAST_FILEBOT_OUTPUT}")
local triage_base="${TR_TORRENT_DIR%/*}/triage"
if triage_failed_torrent "${source_dir}" "${category}" "${triage_base}"; then
# Return 0: the torrent is "handled" (triaged), trigger watcher should
# clean up the trigger and remove from Transmission
return 0
fi
fi
return 1
fi
Also add triage for the preview failure path (~line 1222-1226). When the preview fails, FileBot can't even identify the media — that's "no-match":
# Step 3: Preview changes with dry-run
if ! preview_filebot_changes "${source_dir}"; then
log "Error: Preview failed - cannot determine what changes would be made"
if [[ "${INVOCATION_MODE}" == "automated" ]]; then
local category
category=$(classify_failure "${LAST_FILEBOT_OUTPUT:-}")
local triage_base="${TR_TORRENT_DIR%/*}/triage"
if triage_failed_torrent "${source_dir}" "${category}" "${triage_base}"; then
return 0
fi
fi
return 1
fi
Step 2: Update main() logging
The main() function currently logs "Processing completed successfully" when process_media() returns 0. But now return 0 can mean either "processed" or "triaged". Use a flag to distinguish.
Add a global flag before process_media is called:
TRIAGE_PERFORMED=false
if ! process_media "${torrent_path}"; then
log "Error: Media processing failed"
main_exit_code=1
elif [[ "${TRIAGE_PERFORMED}" == "true" ]]; then
log "Torrent triaged (not processed) — see triage directory"
else
log "Processing completed successfully"
fi
And set TRIAGE_PERFORMED=true inside triage_failed_torrent() when the move succeeds.
Step 3: Run full test suite
Run: bats tests/transmission-filebot/**/*.bats
Expected: All 114+ tests PASS (existing tests use TEST_MODE and INVOCATION_MODE=manual, so they won't trigger triage)
Step 4: Commit
git add app-setup/templates/transmission-done.sh
git commit -m "feat(transmission-filebot): wire triage into process_media for automated failures"
Task 4: Add integration tests for triage flow¶
Files:
- Create:
tests/transmission-filebot/integration/test_triage_workflow.bats
Step 1: Write integration tests
#!/usr/bin/env bats
load '../test_helper'
setup() {
common_setup
export INVOCATION_MODE="automated"
export TR_TORRENT_DIR="${BATS_TEST_TMPDIR}/pending-move"
mkdir -p "${TR_TORRENT_DIR}"
}
@test "triage workflow: already-in-plex torrent is moved and returns success" {
# Create a torrent that FileBot will skip (already exists)
local torrent_dir="${TR_TORRENT_DIR}/TestShow.S01E01"
mkdir -p "${torrent_dir}"
touch "${torrent_dir}/video.mkv"
# Mock LAST_FILEBOT_OUTPUT with "already exists" pattern
export FILEBOT_TEST_OUTPUT='[AUTO] Skipped [/src/video.mkv] because [/dst/video.mkv] already exists
Processed 0 files'
export FILEBOT_TEST_EXIT=1
# The triage base would be at pending-move/../triage
local triage_base="${BATS_TEST_TMPDIR}/triage"
local category
category=$(classify_failure "${FILEBOT_TEST_OUTPUT}")
assert_equal "${category}" "already-in-plex"
run triage_failed_torrent "${torrent_dir}" "${category}" "${triage_base}"
assert_success
assert_dir_exists "${triage_base}/already-in-plex/TestShow.S01E01"
}
@test "triage workflow: no-match torrent is moved to no-match" {
local torrent_dir="${TR_TORRENT_DIR}/UnknownMedia"
mkdir -p "${torrent_dir}"
touch "${torrent_dir}/video.mkv"
local output='Rename episodes using [TheMovieDB]
Processed 0 files'
local category
category=$(classify_failure "${output}")
assert_equal "${category}" "no-match"
local triage_base="${BATS_TEST_TMPDIR}/triage"
run triage_failed_torrent "${torrent_dir}" "${category}" "${triage_base}"
assert_success
assert_dir_exists "${triage_base}/no-match/UnknownMedia"
}
@test "triage workflow: classify_failure with mixed already-exists and match returns already-in-plex" {
local output='[AUTO] Skipped [/src/ep1.mkv] because [/dst/ep1.mkv] already exists
[MOVE] from [/src/ep2.mkv] to [/dst/ep2.mkv]
Processed 1 file'
# This case has both a skip and a move — it succeeded partially.
# classify_failure checks for "already exists" first, so this returns already-in-plex.
# But in practice this wouldn't reach triage because process_media_with_fallback
# would return 0 (1 file was processed).
run classify_failure "${output}"
assert_output "already-in-plex"
}
Step 2: Run integration tests
Run: bats tests/transmission-filebot/integration/test_triage_workflow.bats
Expected: PASS
Step 3: Run full suite
Run: bats tests/transmission-filebot/**/*.bats
Expected: All tests PASS
Step 4: Commit
git add tests/transmission-filebot/integration/test_triage_workflow.bats
git commit -m "test(transmission-filebot): add integration tests for triage workflow"
Task 5: Final review, shellcheck, and deploy¶
Step 1: Run shellcheck
Expected: Clean
Step 2: Run full test suite
Expected: All tests PASS
Step 3: Deploy updated trigger watcher (if any changes)
The trigger watcher doesn't need changes — it already removes from Transmission and cleans up triggers when the done script returns 0, which is exactly what triage does.
Step 4: Commit and push
git add -A
git commit -m "feat(transmission-filebot): failure triage with categorized directories
When automated processing fails, classify the failure (already-in-plex,
no-match, or other) and move the torrent to a triage subdirectory under
Media/Torrents/triage/. Return success so the trigger watcher removes the
torrent from Transmission and cleans up the trigger file. Manual mode is
unaffected — failures still return non-zero for the operator to handle."