T-ZJXU-task-ensure-ready-verifies-cited-schema-fields
Status: closed/superseded · Impact: low · Complexity: small
Auto-generated from a /sdlc:task-work post-mortem. Review and
promote to open/ready before picking up.
Task specs sometimes cite “sibling schemas that carry the same
field” or similar broad claims about the codebase that turn out
to be inaccurate by the time the task is picked up. The implementer
catches this during the relevance check (Step 2 of /sdlc:task-work)
and scopes the work down, but the catch is manual. A small
schema-cross-reference check in /sdlc:task-ensure-ready (or
/sdlc:task-review) would surface these specifically-falsifiable
claims earlier, before a worktree is even spun up. Originating
incident: T-NIPN-migrate-reorders-frontmatter-keys.
“The task spec mentioned mirroring the schema change in ‘sibling schemas (epic, milestone, backlog) that carry the same field,’ but none of those schemas actually declare
readiness_verified_at:— only task does. The relevance check noticed and the implementation scoped down.”
/sdlc:task-ensure-ready already checks that cited file paths
exist and that cited symbols exist with the shape described. It
does NOT cross-check schema-field claims of the form “sibling
schemas X/Y/Z that carry field F” against the actual property
lists in those schemas. A claim that’s false-by-construction
sits in the task body until the implementer’s relevance check
catches it.
Proposed
Section titled “Proposed”/sdlc:task-ensure-ready (or a sibling helper script) extracts
sentences of the form “(epic|milestone|backlog|task) schemas
(that|which) carry (the field|<field>)” and, for each such
sentence, opens the named schema and confirms the field is in
the properties: list. If a claimed schema doesn’t actually
carry the field, surface that as a definition_gap so the spec
gets corrected before the task is picked up.
Approach
Section titled “Approach”- Pick the scope: ensure-ready (cheaper, runs per-task) vs. task-review (runs in batch, slower). Default: ensure-ready, since it’s the gate task-work already calls.
- Add a regex-based extractor for schema-field cross-reference claims. Keep it conservative — false negatives are better than false positives that block valid tasks.
- For each extracted claim, open the schema JSON and check the
propertieskeys. - On mismatch, append to the
definition_gaptext instead of passing.
Files to touch
Section titled “Files to touch”| Location | Kind | Change |
|---|---|---|
plugin/skills/task-ensure-ready/SKILL.md | new | document the new |
plugin/skills/task-ensure-ready/ | new | likely a new helper script |
plugin/skills/task-ensure-ready/tests/run_evals.py | modify | fixtures |
Acceptance criteria
Section titled “Acceptance criteria”- AC-1: A task body containing “sibling schemas (epic,
milestone, backlog) that carry the same field” where the cited
field isn’t actually in those schemas causes ensure-ready to
return NEEDS-DEFINITION with a
definition_gapnaming the false claim. - AC-2: A task body whose schema-field claims are all truthful passes ensure-ready unchanged.
- AC-3: An eval case covers both AC-1 and AC-2.
Out of scope
Section titled “Out of scope”- Free-form natural-language claims that don’t match the regex shape. This pass is targeted at one specific recurring foot-gun, not a general-purpose claim-verifier.
Dependencies
Section titled “Dependencies”- none
Discovery context
Section titled “Discovery context”Spawned by /sdlc:task-work post-mortem of T-NIPN-migrate-reorders-frontmatter-keys on 2026-05-21.