mailbox-same-task-lifecycle

name: mailbox-same-task-lifecycle description: Use when a mailbox task says to claim it, execute it, and finish the SAME task with done/fail. Covers claim/peek/inspect, same-task completion, and common Redis/running-state pitfalls. argument-hint: "[task-id] [workdir-or-scope]" disable-model-invocation: false user-invocable: false allowed-tools: - Read - Grep - Bash

Mailbox same-task lifecycle

When to use

• Use when the task payload says some variant of:
  • Claim with node ~/.claude/scripts/mailbox claim <task_id>
  • finish the SAME task with ... done <same_task_id> ... or fail
  • Do not reply with ... send unless you are delegating a brand-new task
• Use for queued mailbox work where the reply must close the existing task.

Non-goals

• Do not use this when you are intentionally creating a brand-new delegated task.
• Do not assume every mailbox task needs send; this skill is specifically for same-task closure.

Inputs / context to gather

1. The mailbox task id.
2. The working directory / project scope the task belongs to.
3. Whether the task is already claimed/running.
4. Whether the work touches local Redis-backed mailbox state.

Procedure

1. Read the task wording carefully.
   • If it says to finish the SAME task, plan around done / fail, not send.
2. Claim the task.
   • node ~/.claude/scripts/mailbox claim $1
3. If claim fails because the task is already running, inspect instead of re-claiming blindly.
   • Use peek and any project/run inspect tooling to understand the scope.
4. Execute only the requested work.
   • For investigation/review slots, keep the work diagnostic.
   • For implementation slots, verify before claiming success.
5. Build the result payload for the same task id.
6. Complete the task with the same id.
   • CCB_CALLER=codex node ~/.claude/scripts/mailbox done $1 '<result_json>'
   • Or use fail if the task truly failed.
7. Record verification evidence and keep the result scoped to the actual task.

Efficiency plan

1. Read the payload once and extract the protocol requirements up front.
2. If the task is already running, pivot to peek/inspection immediately instead of looping on claim.
3. For OPS/home-directory work, prefer focused file inspection and targeted tests over broad repo workflows.
4. Cache the exact verification commands you will cite in the result payload.
5. Stop once the same task id is closed successfully; do not open a new mailbox thread unless you are explicitly delegating.

Pitfalls and fixes

• Symptom: you are about to use mailbox send as a reply.
  • Likely cause: treating a same-task completion like a new delegation.
  • Fix: switch back to done / fail on the original task id.
• Symptom: claim returns an invalid state transition like running -> running.
  • Likely cause: the task is already claimed.
  • Fix: use peek / inspection and continue from the current state.
• Symptom: Redis connection errors such as Could not connect to Redis at 127.0.0.1:6379: Operation not permitted.
  • Likely cause: the current execution context cannot access local Redis.
  • Fix: rerun in a context that can reach local Redis instead of debugging mailbox logic first.
• Symptom: duplicate mailbox result notifications across projects.
  • Likely cause: project routing metadata / watcher behavior is involved.
  • Fix: inspect mailbox_routing and project scope before assuming the task itself is wrong.

Verification checklist

• The task id you complete matches the task id you were asked to claim.
• You used done or fail, not send, unless you truly delegated a new task.
• The result payload includes concrete evidence from the work you actually ran.
• Any requested investigation/review stayed within scope and did not mutate files unnecessarily.
• If the work touched Redis/mailbox watcher behavior, you confirmed the relevant routing/claim behavior rather than assuming.