T-JXBQ-task-work-warns-on-long-sub-agent-prompt

Status: closed/wontdo · Impact: medium · Complexity: small

Auto-generated from a /sdlc:task-work post-mortem. Review and promote to open/ready before picking up.

Goal

The implementing sub-agent dispatched from /sdlc:task-work Step 6 died mid-execution with API Error: The socket connection was closed unexpectedly after ~5 minutes when handed a long (~70+ line) implementation prompt. No commits had landed; a fresh dispatch with an abbreviated prompt completed cleanly. The pattern suggests sub-agent prompts above some length threshold materially raise the risk of mid-flight socket close — paying the cost of a wasted multi-minute window per occurrence. Surfaced by T-FRTD-drop-lease-filesystem-cache. The fix is cheap: add a documented length budget + a parent-side guard that warns (and ideally splits or compacts the brief) before dispatch.

Today

Location	Role today
`plugin/skills/task-work/SKILL.md` Step 6	Tells the parent to brief the sub-agent “like a colleague who just walked in” — no length guidance, no warning about long-prompt failure modes.
`plugin/skills/task-work/SKILL.md` lines 463–528 (Step 6 body)	Documents the dispatch pattern, the heartbeat-before-dispatch ordering, and the fallback when `Agent` isn’t available — but says nothing about prompt length or the socket-close failure mode observed in 2026-05-27-drop-lease-filesystem-cache.

Proposed

Step 6 of task-work SKILL.md grows a short “Prompt-length budget” note that:

States the observed failure mode in one line: long prompts (~70+ lines) have correlated with mid-execution API Error: socket connection was closed unexpectedly after several minutes, costing the entire dispatch window.
Recommends a target brief size (a guess: ~30–40 lines, trim to essentials — assumptions, files to touch, AC list, deliverable). The exact threshold is uncertain; the doc should call this out and invite calibration as more data lands.
Suggests mitigation: break the work into a sequential wave of sub-agents (the existing wave pattern documented in Step 6), or factor static context into a referenced doc the sub-agent reads rather than inlining it.
Optionally: a parent-side heuristic check that warns when the composed prompt exceeds the threshold, so the muscle-memory pattern is “see warning, prune prompt, retry” rather than “lose 5 minutes to a socket close, retry”.

Approach

Edit plugin/skills/task-work/SKILL.md Step 6 to add the prompt-length-budget note with the failure mode + recommended target + mitigation.
(Optional, uncertain) Add a lightweight check in whatever helper composes the dispatch prompt — log a warning when the composed string exceeds N lines. If no such helper exists today (prompt is constructed inline in the skill prose), skip this step.
Reference the post-mortem origin (T-FRTD-drop-lease-filesystem-cache) in the SKILL.md note so future contributors can find the evidence.

Files to touch

Location	Kind	Change
`plugin/skills/task-work/SKILL.md`	modify	Add a “Prompt-length budget” note to Step 6 describing the socket-close failure mode and the recommended target brief size.

Acceptance criteria

AC-1: plugin/skills/task-work/SKILL.md Step 6 contains a named “Prompt-length budget” (or equivalent) subsection that references the socket-close failure mode and the ~30–40-line target.
AC-2: A grep for socket connection or prompt length in plugin/skills/task-work/SKILL.md returns at least one match.
AC-3: The new prose cites [T-FRTD-drop-lease-filesystem-cache](/planning/tasks/drop-lease-filesystem-cache/) as the discovery context.

Out of scope

Hardening the dispatch path itself (retry on socket close, partial state recovery, etc.) — separate, larger task.
Compacting any specific existing sub-agent prompt — that’s a per-skill follow-up, not in this task’s scope.

Dependencies

none

Discovery context

Spawned by /sdlc:task-work post-mortem of T-FRTD-drop-lease-filesystem-cache on 2026-05-27.

Dedup search (spawn-from-post-mortem)

Bullet: The first sub-agent dispatch died mid-execution with API Error: The socket connection was closed unexpectedly after ~5 minutes. No commits had landed. A fresh dispatch with an abbreviated prompt completed cleanly. The original prompt was long (70+ lines); worth a follow-up — sub-agent prompts above some length threshold may risk this, and the skill’s sub-agent dispatch guidance could note it. Keywords searched: mid-execution, unexpectedly, abbreviated, connection, sub-agent, completed, follow-up, threshold Excluded: 2026-05-27-drop-lease-filesystem-cache Top candidates (score / status / headline):

32 / planning/draft / 2026-05-23-subagent-invariant-preflight-lint — Run skill-prose invariant linter inline during sub-agent edits to catch forbidden-phrase violations pre-flight
25 / closed/done / 2026-05-20-task-work-sub-agent-verdict-contract-clarity — Tighten task-work sub-agent verdict contract so ensure-ready’s READY marker isn’t mistaken for task-work’s final verdict
17 / planning/proposed / 2026-05-26-task-define-batch-skill — Add a task-define-batch skill that fills implementation-ready gaps in many tasks via parallel sub-agents
16 / planning/proposed / 2026-05-24-task-work-sub-agent-verdict-contract-escape-recurrence — task-work: sub-agents still emit ensure-ready READY: as final verdict despite verdict-contract hardening
15 / closed/done / 2026-05-21-spawn-from-post-mortem-stronger-dedup — Strengthen spawn-from-post-mortem dedup and record the search trail Decision: SPAWNED Rationale: Override of script-recommended LINKED-EXISTING to 2026-05-23-subagent-invariant-preflight-lint. That task is about skill-prose invariant linting (forbidden-phrase violations in sub-agent edits) — not about sub-agent dispatch failure modes or prompt-length budgets. The score-32 overlap is incidental shared sub-agent vocabulary. No existing task tracks the long-prompt / socket-close failure mode; spawning a new one is the right shape.

← Back to Tasks