T-24ZN-task-authoring-validates-touchpoint-kinds
Status: closed/superseded · Impact: medium · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
/sdlc:task-new and /sdlc:task-define can author and merge a task
whose ## Files to touch table carries kinds the implementation-ready
gate rejects (new (git mv), modify/delete) and whose ## Today
table cites paths that do not exist yet — and nobody learns until
/sdlc:task-work picks the task up and the readiness gate fails
mid-flight. Running the same parse_touchpoints.py resolution + kind
validation the gate uses, but at authoring/define time, closes the
gap: the author fixes the touchpoints once, immediately, instead of a
future task-work run hitting a hard stop on a merged task. Surfaced by
T-1KPE-add-backlog-capture.
| Location | Role today |
|---|---|
plugin/skills/task-ensure-ready/parse_touchpoints.py | Parses ## Files to touch / ## Today tables and resolves each row against the codebase by kind. Invoked by the readiness gate at /sdlc:task-work pickup time — NOT at authoring/define time. |
plugin/skills/task-ensure-ready/SKILL.md | The readiness gate. First and only place touchpoint kinds + Today-path existence are checked today — after the task is written, committed, and merged. |
plugin/skills/task-new/SKILL.md | Interactive intake. Edits the body sections (including Files-to-touch / Today) but does not resolve or kind-validate the touchpoints it just wrote. |
plugin/skills/task-define/SKILL.md | Fills thin sections toward implementation-ready, but likewise never runs the touchpoint resolution the gate will later apply. |
From T-1KPE-add-backlog-capture’s post-mortem: “The merged task passed authoring/merge but FAILED the v3 implementation-readiness gate at pickup (invalid Files-to-touch kinds
new (git mv)/modify/delete, and a## Todayrow citing the not-yet-existentplugin/cli/) — task-new/task-define should run the sameparse_touchpoints.pyresolution + kind validation at authoring time so these are caught before merge, not mid-task-work.”
Proposed
Section titled “Proposed”/sdlc:task-new and /sdlc:task-define run the existing
parse_touchpoints.py resolution + kind validation against the task
body they just edited, before committing, and surface any invalid kind
or unresolvable modify/delete row (or a ## Today row citing a
not-yet-existent path) as an authoring-time advisory the author
resolves in place. The check reuses parse_touchpoints.py unchanged —
this task wires the gate’s own resolver into the authoring path so the
two surfaces agree, rather than re-implementing validation. It must not
be a hard disqualifier where the task legitimately describes
not-yet-created paths (a new row resolving against a parent that does
not exist yet is fine); the advisory targets the specific failures the
gate rejects: bad kind tokens, and modify/delete rows that cannot
resolve.
Approach
Section titled “Approach”- Confirm
parse_touchpoints.pyis callable as a library / CLI from a skill step against an in-progress (uncommitted) task file, and that its kind-validation + resolution surface matches what the readiness gate invokes. (Open: whether to expose a thin--authoring-advisorymode that downgrades the not-yet-existent-path case so authors aren’t blocked on legitimately-new paths.) - Add a step to
/sdlc:task-new(after it edits Files-to-touch / Today) and/sdlc:task-define(after its body edits) that runs the resolver against the working copy and reports invalid kinds / unresolvablemodify+deleterows, prompting the author to fix before commit. - Add a fixture covering a task with a bad kind token (
new (git mv)) and a## Todayrow citing a non-existent path; assert the authoring check flags both. Wire into the skills’ eval suites if they have one.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/skills/task-new/SKILL.md | modify | Add a touchpoint-resolution advisory step after the body-edit step. |
plugin/skills/task-define/SKILL.md | modify | Same advisory step after define’s body edits. |
plugin/skills/task-ensure-ready/parse_touchpoints.py | modify | Possible thin advisory/CLI affordance if the authoring surface needs a softer not-yet-existent-path mode (decide in Approach step 1). |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: Authoring a task via
/sdlc:task-new(or running/sdlc:task-defineon one) whose## Files to touchcarries an invalid kind token (e.g.new (git mv),modify/delete) surfaces the bad kind to the author before the task is committed, naming the offending row. - AC-2: A
## Today(or## Files to touchmodify/delete) row citing a path that does not resolve in the codebase is flagged at authoring time, not first at/sdlc:task-workpickup. - AC-3: A legitimately-new
newrow whose target does not yet exist does NOT trip the authoring advisory (no false positive on the intended-creation case). - AC-4: The authoring check reuses
parse_touchpoints.py— kind rules are not duplicated between the gate and the authoring surface.
Out of scope
Section titled “Out of scope”- Auto-fixing the touchpoints. The advisory reports; the author edits.
- Changing the kind grammar or the gate’s resolution rules — this task only moves the existing check earlier in the lifecycle.
- A pre-merge CI gate on planning PRs — tracked separately at T-M2OV-pre-merge-frontmatter-validation-gate (frontmatter) and T-G39V-validate-task-body-shape-at-commit-time (AC/table shape); this task is the authoring-skill-side advisory complement.
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-1KPE-add-backlog-capture on 2026-05-27.
Dedup search (spawn-from-post-mortem)
Section titled “Dedup search (spawn-from-post-mortem)”Bullet: The merged task passed authoring/merge but FAILED the v3 implementation-readiness gate at pickup (invalid Files-to-touch kinds ‘new (git mv)’ / ‘modify/delete’, and a ## Today row citing the not-yet-existent plugin/cli/) — task-new/task-define should run the same parse_touchpoints.py resolution + kind validation at authoring time so these are caught before merge, not mid-task-work. Keywords searched: implementation-readiness, parse_touchpoints, not-yet-existent, files-to-touch, mid-task-work, task-define, resolution, validation Excluded: 2026-05-27-add-backlog-capture Top candidates (score / status / headline):
- 27 / 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
- 19 / planning/draft / 2026-05-23-entities-migrate-reshapes-bulleted-sections — entities-migrate reshapes bulleted Today/Files-to-touch into v3 tables
- 18 / closed/done / 2026-05-22-restructure-task-touchpoints-as-a-table-with-symbol-dir-glob — Restructure task touchpoints as a table with symbol/dir/glob citation grammar
- 14 / closed/done / 2026-05-19-consolidate-task-status-enum — Consolidate task status enum and migrate existing instances
- 12 / closed/done / 2026-05-20-task-spec-flags-schema-rejecting-placeholders — /sdlc:task-define surfaces schema-rejecting placeholders at authoring time Decision: SPAWNED Rationale: Override script’s LINKED-EXISTING (2026-05-26-task-define-batch-skill) → SPAWNED. The top candidate is a false positive from keyword overlap on “task-define”/“implementation-ready”: the batch skill fills implementation-ready gaps across many tasks via parallel sub-agents — it does not run parse_touchpoints.py kind validation at authoring time, which is this bullet’s specific gap. The next candidates are about migrating/reshaping Today/Files-to-touch tables (entities-migrate) or frontmatter-placeholder advisories (task-spec-flags-schema-rejecting-placeholders, explicitly “not a readiness-gate check”); none run the gate’s touchpoint resolver at task-new/task-define time. This is a distinct, uncovered automation.