T-KIM9-task-define-batch-skill

Status: closed/superseded · Impact: low · Complexity: medium

Goal

/sdlc:task-define is single-task and interactive. When an audit surfaces many tasks with prose drift (missing template H2 sections), the only batch path today is a hand-rolled loop of one-at-a-time interactive sessions. A task-define-batch skill should take N task slugs (or accept the audit’s drift list), spawn a sub-agent per task in its own worktree + branch, and open one PR per task with a confidence self-assessment and explicit unresolved-question disclosure. The user reviews PRs afterwards instead of approving questions live for each task.

Today

Location	Role today
apps/sdlc/skills/task-define/SKILL.md	Single-task interactive skill. Uses AskUserQuestion to fill gaps one at a time on a single resolved task file. Exits gracefully if the user can’t answer.
apps/sdlc/skills/task-ensure-ready/SKILL.md	Non-interactive validator. Reads contract, fails-or-stamps readiness_verified_at. Records definition_gap on fail. Carve-out for in-progress* so a failed check doesn’t downshift status.
sdlc entities audit op (apps/sdlc/lib/model/ops/audit.ts)	Read-only auditor. Reports [prose/manual] ## Goal: missing template section '## Goal'-style drift per file. Currently the only batch detector — but only that, no batch fixer.
apps/sdlc/skills/entities-migrate/SKILL.md	Batch fixer — but only for auto_fixable=true mechanical drift (schema-version stamping, etc.). Prose-section gaps are flagged auto_fixable=false and skipped.
apps/sdlc/skills/task-review/SKILL.md	Batch triage — updates frontmatter, ranks next 1-2 tasks. Does not fill prose sections.
apps/sdlc/lib/model/entities/task/implementation-ready.md	The contract every task-define-shaped skill targets. Both the existing single-task skill and the proposed batch skill would gate against it.

There is no skill that batches prose-section fill across many drifted tasks. The manual workaround a user just ran (see ## Discovery context) produced 4 PRs across 4 tasks with mixed confidence levels in one parallel pass — empirically the shape works; it just isn’t a skill yet.

Proposed

A new apps/sdlc/skills/task-define-batch/SKILL.md skill that takes a list of task slugs (or --from-audit to pull the current drift list) and, for each task, spawns an autonomous sub-agent that:

1. Creates a worktree at .sdlc/worktrees/<basename> on branch task/<basename>.
2. Reads the task file + related closed tasks + relevant source code to ground its work.
3. Fills the missing template H2 sections in place, preserving existing rich prose below.
4. Self-assesses confidence (high / medium / low) based on whether code paths verified cleanly, whether unresolved design decisions remain, and whether the original task was speculative vs concrete.
5. Updates frontmatter: refreshes last_reviewed, rewrites definition_gap to reflect remaining gaps (or removes it if fully resolved), sets low_confidence: true when appropriate (new field; see Open questions).
6. Commits with project-specific quality gates running first.
7. Opens a PR per task with confidence callout + explicit unresolved-question list + “do NOT promote past planning/proposed” guardrail when low confidence.

The skill is non-interactive at the sub-agent level — there’s no AskUserQuestion in the inner loop because batch-fanning out interactive prompts to one user defeats the parallelism. The interactivity boundary moves to PR review: the user reviews each PR and decides whether to merge / request changes / close.

Approach

1. Spec the skill contract. Decide whether task-define-batch is its own skill or a --batch flag on task-define. Probable answer: separate skill, because the interactivity model is fundamentally different (existing skill is question-driven; batch is autonomous). Sibling skill, not a flag.
2. Decide the input shape. Options:
   • --from-audit — re-run sdlc entities audit, take every DRIFT task with [prose/manual] gaps as input.
   • Positional slugs — task-define-batch slug-1 slug-2 slug-3.
   • File of slugs (one per line) — task-define-batch --from-file paths.txt. Probably support all three; --from-audit is the killer-app shape.
3. Decide concurrency cap. Sub-agents in parallel — but how many? orchestrator.max_implementations from sdlc.yaml is the obvious knob (default 5). Each sub-agent runs in its own worktree so disk pressure is real for large N.
4. Author the per-sub-agent prompt template. Empirical shape from the source run: a. Task file path + basename. b. Worktree + branch convention (.sdlc/worktrees/<basename> + task/<basename>). c. Quality check command (project-specific — read from sdlc.yaml). d. The 9 sections to fill (Goal / Today / Proposed / Approach / Files to touch / Acceptance criteria / Out of scope / Dependencies / Discovery context). e. The implementation-ready contract path. f. Related closed tasks to read for context (inferred from related: frontmatter and any ## Related prose links). g. Confidence rubric (high / medium / low + when each applies). h. Guardrails: no promotion past planning/proposed, no Claude/Anthropic attribution, explicit-path-only staging, relative paths inside worktree.
5. Spawn sub-agents in parallel via the Agent tool, one per task, all in run_in_background: true, then collect notifications as they finish.
6. Aggregate report. Once all sub-agents finish, emit a single summary listing each task with PR URL, confidence, status decision, and remaining-gaps line.
7. Add low_confidence to the task schema. Currently the source run injected it as an ad-hoc frontmatter field. Either formalize it in apps/sdlc/lib/model/entities/task/schema.ts or fold the signal into a refined definition_gap field. Probably formalize — it’s a useful signal for /sdlc:task-review to surface (“these N tasks have low_confidence definitions, review before promoting”).
8. Cross-cutting docs. Update apps/sdlc/skills/README.md index, add per-skill doc at docs/skills/task-define-batch.md via /sdlc:update-skill-doc.

Files to touch

Location	Kind	Change
apps/sdlc/skills/task-define-batch/	new	Skill directory.
apps/sdlc/skills/task-define-batch/SKILL.md	new	Skill body: input parsing, per-task sub-agent dispatch prompt template, aggregation.
apps/sdlc/skills/task-define-batch/tests/	new	Eval harness (per existing skill pattern — e.g. task-define/tests/task_define.test.ts).
apps/sdlc/lib/model/entities/task/schema.ts	modify	Add optional low_confidence: boolean field (if Open question 1 lands on “formalize”).
apps/sdlc/lib/model/entities/task/body-template.eta	modify	If low_confidence is formalized, mention in the header comment.
apps/sdlc/skills/README.md	modify	Add task-define-batch to the skill index.
docs/skills/task-define-batch.md	new	Per-skill doc generated via /sdlc:update-skill-doc.
apps/sdlc/skills/task-define/SKILL.md	modify	Add a one-line “for batch use see /sdlc:task-define-batch” pointer.

Acceptance criteria

• AC-1: /sdlc:task-define-batch --from-audit on a project with N drifted tasks spawns N parallel sub-agents (capped at orchestrator.max_implementations from sdlc.yaml) and produces N PRs, one per task, on branches named task/<basename>.
• AC-2: /sdlc:task-define-batch slug-1 slug-2 slug-3 works against an explicit list of slugs (no audit re-run required).
• AC-3: Each opened PR body contains: a confidence callout (high / medium / low), a summary of which sections were filled, an explicit list of unresolved questions remaining, and a “do NOT promote past planning/proposed” line when confidence is low.
• AC-4: No PR promotes the task past planning/proposed. The skill is a fill-shape operation, not a promote-to-ready operation.
• AC-5: Each PR commit message contains no “Claude” / “Anthropic” / “Co-Authored-By” attribution. Verified by grep over the produced commit messages in the eval harness.
• AC-6: Project quality checks (from sdlc.yaml#quality_checks) ran clean in each sub-agent before commit. Verified by sub-agent stdout marker.
• AC-7: Each sub-agent worktree is at .sdlc/worktrees/<basename> (not a temp dir); the user can find it after the skill exits to inspect mid-flight state if needed.
• AC-8: An aggregated report is emitted on the parent skill’s stdout listing every task with: basename, PR URL, confidence, final status, and one-line remaining-gaps note.
• AC-9: Re-running /sdlc:task-define-batch --from-audit after merging the first pass exits clean (“no drift found”) — the skill is idempotent against an already-clean audit state.
• AC-10 (if Open question 1 lands on “formalize”): tasks completed at low confidence carry low_confidence: true in frontmatter; /sdlc:task-review surfaces these tasks with a “review confidence before promoting” warning.

Out of scope

• Auto-merging the produced PRs. The whole point of the skill is to surface a review surface for the user; auto-merge defeats it. The user merges per PR after reading.
• Filling sections for closed tasks. Closed entities are frozen artefacts of the schema generation they were closed under. task-define-batch should refuse to operate on status: closed/* tasks, mirroring sdlc entities audit --include-closed’s default off.
• Cross-repo dispatch. When a drifted task lives in repo A but its design decisions live upstream in repo B, the batch skill should NOT try to coordinate the cross-repo PR. Sub-agents are scoped to the current repo only. Cross-repo follow-ups stay manual via /sdlc:spawn-task-pr.
• Auto-deleting low_confidence frontmatter after promotion. If a user promotes a low-confidence task to open/ready after review, the field stays until a separate pass clears it. Avoid magic frontmatter mutation outside the explicit verification skill.
• Interactivity inside the sub-agent loop. No AskUserQuestion in the sub-agent prompt. The whole design hinges on the autonomy split: sub-agents are autonomous; the user interacts via PR review. This is intentional and not a future enhancement.

Dependencies

• none (the existing task-define / task-ensure-ready / sdlc entities audit plumbing is enough; this skill composes them rather than replacing them).

Discovery context

• Empirical source: 2026-05-26 manual run against rust-ontogen tasks OF-018, OF-020, OF-021, OF-022 — four tasks flagged by the entity audit as [prose/manual] drift (missing template H2 sections). The user dispatched 4 parallel sub-agents via the Agent tool with hand-rolled prompts following exactly the shape proposed in ## Approach above. Results:
  • PR #86 (OF-018, TS fallback generic-tokenizer bug): medium-high confidence. Sub-agent verified stale paths against current code, narrowed bug surface accurately, and confirmed Direction A applies (OF-015 kept the fallback path per its post-mortem).
  • PR #87 (OF-022, richer external-type renderings): medium-high confidence. Sub-agent caught a real codebase discrepancy (BTreeMap<String, String> vs the sketched HashMap<TypePath, &'static str>) and grounded all 7 Files-to-touch rows.
  • PR #85 (OF-020, hierarchical TS bindings): low confidence. Sub-agent correctly self-assessed that the task is speculative and the Approach starts with a design pass. Added low_confidence: true ad-hoc.
  • PR #88 (OF-021, user-defined generics in TS): low confidence. Sub-agent correctly identified three unresolved design decisions and recommended against promotion. Added low_confidence: true ad-hoc.
  • The user explicitly asked to encapsulate this as a repeatable skill given that the shape worked.
• The empirical-confidence distribution matters: even on speculative tasks the agents produced useful contract-shape PRs that disclose what they don’t know. The disclosure is the value-add over a hand-fill.
• The ad-hoc low_confidence: true frontmatter field is the cleanest signal the source run produced; formalizing it (Open question 1) is the natural follow-up.

Open questions

• Formalize low_confidence: true in the task schema, or keep it ad-hoc? Formalizing enables /sdlc:task-review to filter on it. Keeping it ad-hoc avoids schema churn. Probable answer: formalize, because the signal is reused in at least two places (this skill’s output + review’s input).
• Should sub-agents internally invoke /sdlc:task-define and /sdlc:task-ensure-ready, or duplicate the contract-reading logic? The existing single-task skill is interactive, which doesn’t fit. Probable answer: duplicate the contract-reading shape but skip the interactive arm. Long term, refactor the contract-reading into a shared library both skills consume.
• What’s the concurrency cap default? orchestrator.max_implementations is 5 today. Probably reuse that — same “how many parallel implementations is the project comfortable with” question. But sub-agents here are read-heavy more than write-heavy, so a separate knob (task_define_batch.max_concurrent) might be warranted.
• Should the skill commit each PR atomically, or batch them into one PR with multiple task-file diffs? The source run did one-PR-per-task. Reasoning: each task has different confidence, different unresolved questions, and the user might want to merge OF-018 (high confidence) immediately while leaving OF-020/OF-021 (low confidence) open for design discussion. One-PR-per-task wins on review granularity. Defer the bundled-PR option to a future flag if it earns its keep.

---

← Back to Tasks