Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

docs: add guidelines to prevent panics in fallible code (#1110)

Maximilian Roos632df3f042b4
diff --git a/.claude/skills/pr-review/SKILL.md b/.claude/skills/pr-review/SKILL.md
index b43a7237b..961802c44 100644
--- a/.claude/skills/pr-review/SKILL.md
+++ b/.claude/skills/pr-review/SKILL.md
@@ -96,6 +96,9 @@ tactical checklist.
- Are there edge cases that aren't handled?
- Could the changes break existing functionality?
- Are error messages helpful and consistent with the project style?
+- Does new code use `.expect()` or `.unwrap()` in functions returning `Result`?
+ These should use `?` or `bail!` instead — panics in fallible code bypass error
+ handling.
**Testing:**
diff --git a/CLAUDE.md b/CLAUDE.md
index 5c5639642..1cb44bd7a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -331,6 +331,7 @@ if worktree.is_dirty() {
- **Use `bail!`** for business logic errors (dirty worktree, missing branch, invalid state)
- **Use `.context()`** for wrapping I/O and external command failures
+- **Never `.expect()` or `.unwrap()` in functions returning `Result`** — use `?`, `bail!`, or return an error. Panics in fallible code bypass error handling.
- **Don't `logger.error` before raising** — include context in the error message itself
- **Let errors propagate** — don't catch and re-raise without adding information
diff --git a/src/commands/list/collect/execution.rs b/src/commands/list/collect/execution.rs
index 668416dc8..7f0bf50cf 100644
--- a/src/commands/list/collect/execution.rs
+++ b/src/commands/list/collect/execution.rs
@@ -145,6 +145,10 @@ impl ExpectedResults {
/// worktree. Expected results are registered internally as each work item is added.
/// The caller is responsible for executing the work items.
///
+/// Task preconditions (stale branch, unborn branch, missing llm_command) are
+/// enforced here — not in callers. This function is called from both `collect()`
+/// and `populate_item()`, so guards must live here to cover all entry points.
+///
/// The `repo` parameter is cloned into each TaskContext, sharing its cache via Arc.
pub fn work_items_for_worktree(
repo: &Repository,
@@ -243,8 +247,7 @@ pub fn work_items_for_worktree(
if !has_commits && COMMIT_TASKS.contains(&kind) {
continue;
}
- // Skip SummaryGenerate when no LLM command is configured.
- // (Also skipped via skip_tasks in collect(), but populate_item() bypasses that path.)
+ // Skip SummaryGenerate when no LLM command is configured
if kind == TaskKind::SummaryGenerate && options.llm_command.is_none() {
continue;
}
@@ -270,6 +273,8 @@ pub fn work_items_for_worktree(
/// Returns a list of work items representing all tasks that should run for this
/// branch. Branches have fewer tasks than worktrees (no working tree operations).
///
+/// Task preconditions are enforced here, same as [`work_items_for_worktree`].
+///
/// The `repo` parameter is cloned into each TaskContext, sharing its cache via Arc.
/// The `is_remote` flag indicates whether this is a remote-tracking branch (e.g., "origin/feature")
/// vs a local branch. This is known definitively at collection time and avoids guessing later.
@@ -332,8 +337,7 @@ pub fn work_items_for_branch(
if is_stale && EXPENSIVE_TASKS.contains(&kind) {
continue;
}
- // Skip SummaryGenerate when no LLM command is configured.
- // (Also skipped via skip_tasks in collect(), but populate_item() bypasses that path.)
+ // Skip SummaryGenerate when no LLM command is configured
if kind == TaskKind::SummaryGenerate && options.llm_command.is_none() {
continue;
}