Skip to content
sdlc

T-KLIL-task-new-flags-cascading-schema-edits

Status: closed/partially-superseded · Impact: low · Complexity: small

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

Goal

Section titled “Goal”

When a task changes the contained-types pattern of a schema (e.g. relaxing milestone.tasks to also accept epic wikilinks), downstream scaffolding scripts and skill descriptions that reference the schema must be updated in the same change — otherwise they keep rejecting (or under-describing) the new shape. The originating task missed this in its scope and the sub-agent had to make two off-spec edits at implementation time. Closing this gap makes “cascading schema-aware edits” an explicit checklist item during task definition.

Cited by T-J2CW-add-epic-entity-task-depends-on-dependencies.

Today

Section titled “Today”

From the originating post-mortem:

Sub-agent made two off-spec edits that the spec should probably anticipate: (1) new_milestone.py --task flag relaxed to accept epic ids (otherwise the script would reject legitimate inputs once milestone.tasks accepted epics), and (2) setup/SKILL.md description updated to list the actual ships-today entities (backlog/epic/milestone/task) rather than the outdated “today: task” claim. Both reasonable; future tasks that change a schema’s contained-types should explicitly call out script-flag updates as in-scope.

Relevant artifacts:

  • plugin/scripts/new_milestone.py — --task flag (and similar in other new_*.py scripts).
  • plugin/skills/setup/SKILL.md — description that enumerates ships-today entities.
  • plugin/entities/task/template.md and any task-authoring skill — current guidance doesn’t flag this cascade.

Proposed

Section titled “Proposed”

Either:

(a) Extend the task template’s ## Files to touch guidance with an explicit prompt: “When changing a schema’s contained-types pattern, list every new_*.py flag, every skill description enumerating entity types, and any validator referencing the same pattern.”

OR

(b) Add a check to /sdlc:task-define / /sdlc:task-ensure-ready that detects schema-touching tasks (Files to touch mentions any entities/*/schema.json) and asks the author whether the cascading consumers are in scope.

Default preference: (a) — cheaper and lower-friction. (b) is a stretch goal.

Approach

Section titled “Approach”
  1. Pick (a) vs (b). Default (a).
  2. If (a): edit plugin/entities/task/template.md’s ## Files to touch section with a one-liner reminder, and possibly add a short note to plugin/entities/task/writing.md about cascading schema edits.
  3. If (b): build the schema-touch detector into the existing skill flow.

Files to touch

Section titled “Files to touch”
  • plugin/entities/task/template.md — extend the ## Files to touch guidance with the cascading-edits reminder (option a).
  • plugin/entities/task/writing.md — short paragraph on the cascade pattern.
  • (Optional, option b) plugin/skills/task-define/SKILL.md and/or plugin/skills/task-ensure-ready/SKILL.md — schema-touch detector.

Acceptance criteria

Section titled “Acceptance criteria”
  • AC-1: The task template’s guidance for schema-touching changes calls out the cascade (new_*.py flags, skill descriptions, validators) explicitly, so a future author writes them into scope from the start.

Out of scope

Section titled “Out of scope”
  • Retro-fixing existing tasks that already missed the cascade (they were patched at implementation time).
  • Building a generic “schema-aware refactor” tool that mechanically applies the cascade.

Dependencies

Section titled “Dependencies”
  • none

Discovery context

Section titled “Discovery context”

Spawned by /sdlc:task-work post-mortem of T-J2CW-add-epic-entity-task-depends-on-dependencies on 2026-05-19.

← Back to Tasks