Skip to content

[Feature]: /speckit.tasks — cite data-model constraints instead of copying them verbatim #5429

Backlog

Description

@LightSystem

Problem Statement

#4430 (fixing #4383) added this rule to "From Data Model" in templates/commands/tasks.md:

For each field with constraints in data-model.md (max length, nullable/required, enum values, validation rules), quote the constraint verbatim in the task description so it is not left to implementation-time discretion

The problem #4383 reported is real: the task paraphrased a field ("trimmed suspend reasons") without its limit, and the implementing agent invented one. The remedy, though, gives every constraint a second copy, and two things make that costly:

  1. Copies drift. data-model.md, research.md and the contracts keep changing after /speckit.tasks, through /speckit.plan re-runs, hand edits and fixes found mid-implementation. Re-running /speckit.tasks then is not a fix, since it regenerates the file and its completion state. The tasks keep the old text, and the implementing agent holds two versions, of which the task's can win. That is [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383's failure again, now caused by a stale copy instead of an omission.
  2. /speckit.analyze is not told to look. Its Goal limits it to "the three core artifacts (spec.md, plan.md, tasks.md)", and its "Load Artifacts" step loads only those and the constitution (from plan.md, only its "Data Model references"). A task contradicting data-model.md is therefore not compared against it.

In our project, agents also applied the rule beyond its scope. Combined with "each task must be specific enough that an LLM can complete it without additional context" (present since the initial template), generated tasks restated whole data-model rows, formulas from research.md, contract field descriptions and UI strings.

Example:

data-model.md:  | Profile.displayName | string, 1–80 chars, trimmed | FR-004 |
tasks.md:       T012 Add displayName to Profile ("string, 1–80 chars, trimmed")

A fix found during implementation changes the limit to 120 in data-model.md. T012 still says 80, and /speckit.analyze reports nothing.

Proposed Solution

Keep #4383's guarantee, that no constraint is left to implementation-time discretion, but meet it by reference:

  • tasks.md "From Data Model": each task that creates or changes a constrained field cites it explicitly as data-model.md Entity.field. A prose paraphrase does not count. The task quotes a constraint only where it narrows or adds to it.
  • "Without additional context" means nothing needed beyond the feature's design documents, which /speckit.implement's "Load and analyze the implementation context" step already reads. That read alone did not prevent [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383, because implement read data-model.md at v1.0.1 too. What changes is that each task carries an explicit pointer instead of a paraphrase, and analyze enforces it.
  • /speckit.analyze also loads data-model.md and flags (a) a constrained field that no task cites in that form, which catches [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383's case directly, and (b) a task that states a constraint differently from data-model.md.
  • tests/test_tasks_template_constraints.py asserts the citation rule instead of the verbatim one.

Alternatives Considered

  • Keep the verbatim rule and have analyze compare the copies. This catches drift, but every design change still needs a second edit in tasks.md.
  • A project-level override (CLAUDE.md, AGENTS.md). This works per project, but the default still pushes every new project toward duplication, and the override has to name the template's rule to outrank it.
  • A preset overriding the command. This freezes a full copy of an upstream template.

Component

Agent integrations (command files, workflows)

AI Agent (if applicable)

All agents

Use Cases

  • Long /speckit.implement runs, where a task's own text is what the agent acts on.
  • Features whose data-model.md has many constrained fields, where per-field copies make tasks.md long and noisy.
  • Repositories with a single-source-of-truth convention for documentation.

Acceptance Criteria

Additional Context

Related: #4383 and #4430 (the fix this revisits), and #4164 (structured IDs and context packs, where implement loads a task plus the records it cites; this proposal is a small step in that direction).

AI Disclosure

Drafted with Claude Code (Claude Opus 5.5, high reasoning effort, human-supervised). The agent traced the rule's history through spec-kit's commits and PRs and wrote the draft. I reviewed and edited it before posting.

Activity

  1. added
    triage-can-waitVerdict: valid and in-scope but deprioritized; held behind the evidence gate
    feature-assessRun the Spec Kit idea-assessment pipeline on this feature request
    and removed on Nov 13, 2026
  2. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — cite-model-constraints · Stage 1/5: Intake

    Idea Intake: Cite data-model constraints by reference

    Idea (as captured)

    Issue #5429 proposes changing /speckit.tasks so tasks cite constrained fields as data-model.md Entity.field instead of copying constraints verbatim into task prose. The request argues that verbatim copies drift as data-model.md evolves, and that /speckit.analyze currently checks only spec.md, plan.md, and tasks.md, so stale or contradictory copied constraints can go undetected. It proposes updating task-generation rules, analyzer checks, and tests so constraints remain explicit without duplicating the source of truth.

    Triggering event and origin: labeled feature request in github/spec-kit issue #5429 by @LightSystem.

    Restated

    The request is to preserve explicit constraint guidance for implementation while replacing duplicated task-level constraint text with stable references to canonical data-model.md fields. It also asks for analyzer checks that detect missing references and mismatches, so constraint drift is caught before implementation.

    Origin & Context

    First-Glance Unknowns

    • [NEEDS CLARIFICATION: Should the citation format be strictly backticked data-model.md Entity.field, or are equivalent explicit forms acceptable?]
    • [NEEDS CLARIFICATION: Should /speckit.analyze enforce this rule only for constrained fields, or for all data-model fields referenced by tasks?]
    • [NEEDS CLARIFICATION: How should analyzer severity be assigned for missing citations vs. mismatched copied constraints?]
    • [NEEDS CLARIFICATION: Should existing generated tasks.md files be migrated, or should the change apply only to newly generated tasks?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5429 · copilot · gpt53codex · 51.3 AIC · ⌖ 0.689 AIC · ⊞ 27.7K · ◷

  3. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — cite-model-constraints · Stage 2/5: Research

    Idea Research: Constraint citation over duplication

    • Slug: cite-model-constraints
    • Created: 2026-11-16T20:51:56Z
    • Evidence confidence (overall): medium

    Users & Demand

    Prior Art

    Market & Context

    • In documentation-heavy workflows, duplicated authoritative constraints tend to drift after iterative edits; the issue describes this exact maintenance cost in Spec Kit artifacts regenerated or edited after /speckit.tasks — [source: issue [Feature]: /speckit.tasks — cite data-model constraints instead of copying them verbatim #5429 | cited] (confidence: medium)
    • Alternative practice in similar systems is "single source of truth + explicit pointers" to reduce contradiction risk, but direct comparative benchmarks were not collected in-repo — [source: ASSUMPTION] (confidence: low)

    Data & Constraints

    • Analyzer scope currently states "three core artifacts (spec.md, plan.md, tasks.md)" (templates/commands/analyze.md, line 54), which supports the claim that data-model-only drift may be missed unless analyze behavior is expanded — [source: repository file | cited] (confidence: high)
    • Backward compatibility constraint: existing tests codify verbatim-copy behavior; changing policy will require test updates and potentially migration guidance for teams relying on current phrasing — [source: tests/test_tasks_template_constraints.py | cited] (confidence: high)
    • No runtime telemetry in this repository quantifies failure frequency, implementation delays, or defect rates caused by stale copied constraints — [source: ASSUMPTION] (confidence: low)

    Evidence Against the Idea

    Gaps & Open Questions

    • [NEEDS CLARIFICATION: Exact citation grammar and linting tolerance (strict backtick form vs. equivalent plain-text reference).]
    • [NEEDS CLARIFICATION: Whether /speckit.analyze should hard-fail on paraphrase, or warn with severity levels.]
    • [NEEDS CLARIFICATION: Migration expectation for existing feature branches with generated tasks.md using verbatim copies.]
    • [NEEDS CLARIFICATION: Acceptance threshold for "constraint differs" detection (exact text match vs. semantic equivalence).]

    Sources

    • [Feature]: /speckit.tasks — cite data-model constraints instead of copying them verbatim #5429 (host: github.com, policy: allowlisted)
    • repository file templates/commands/tasks.md (line 200; local source)
    • repository file tests/test_tasks_template_constraints.py (line 24; local source)
    • repository file templates/commands/analyze.md (line 54; local source)
    • repository file templates/commands/implement.md (lines 90–96; local source)
    • repository file CHANGELOG.md (line 637; local source)

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5429 · copilot · gpt53codex · 51.3 AIC · ⌖ 0.689 AIC · ⊞ 27.7K · ◷

  4. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — cite-model-constraints · Stage 3/5: Problem

    Problem Definition: Constraint drift between model and task artifacts

    • Slug: cite-model-constraints
    • Created: 2026-11-16T20:51:56Z
    • Inputs used: intake.md | research.md

    Problem Statement

    Spec Kit task generation can force constrained data-model fields to be duplicated verbatim in task descriptions, which creates a second mutable source of truth that can drift when design artifacts evolve. When that drift is not systematically checked, implementers may act on stale or contradictory task text and reintroduce constraint errors the process is meant to prevent.

    Affected Users & Stakeholders

    • Users: Spec Kit users running /speckit.tasks and /speckit.implement — they risk implementing wrong limits/validation when task text and data-model.md diverge.
    • Users: AI implementing agents in SDD workflows — they may prioritize task-local text over canonical design records when both are present.
    • Stakeholders: Spec Kit maintainers — they own template correctness, regression prevention, and analyzer coverage quality.
    • Stakeholders: Teams adopting Spec Kit in repositories with strict documentation single-source-of-truth norms — they absorb review and maintenance cost from duplicated constraints.

    Goals

    • Preserve explicit, unambiguous constraint guidance for implementation-time execution.
    • Reduce or eliminate drift risk introduced by duplicating canonical constraint text into tasks.md.
    • Ensure pre-implementation analysis can detect missing or contradictory constraint references.
    • Keep generated tasks actionable without forcing undocumented inference by implementing agents.

    Non-Goals

    • Redesigning the full SDD command architecture.
    • Defining API, data-model, or implementation-level design for analyzer internals.
    • Retroactively editing every historical tasks.md artifact in existing repositories.
    • Solving all task verbosity concerns unrelated to constrained-field handling.

    Success Metrics

    • New task-generation output includes explicit constrained-field linkage to canonical records for all constrained fields (baseline: current rule enforces verbatim copies instead).
    • Analyzer detects at least two failure classes: missing constrained-field linkage and constraint mismatch against canonical data model (baseline: unknown/likely uncovered in current three-artifact scope).
    • Regression scenario matching [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383/fix(tasks): require field constraints from data-model.md in generated tasks #4430 lineage is covered by deterministic tests for both positive and negative cases (baseline: one regression test focused on verbatim-copy instruction text).
    • Maintainer review burden from stale duplicated constraints decreases [NEEDS CLARIFICATION: measure method and threshold].

    Cost of Inaction

    Keeping the current duplication-heavy rule leaves process correctness dependent on manually keeping copied constraint prose synchronized across artifacts as designs change. This preserves a known path to stale task instructions, increases review overhead, and can negate the original anti-invention safeguard by replacing omission risk with contradiction risk.

    Open Questions

    • [NEEDS CLARIFICATION: What exact syntax and parser tolerance should define a valid constrained-field citation in tasks.md?]
    • [NEEDS CLARIFICATION: Should analyzer findings for missing citations be blocking errors, warnings, or configurable?]
    • [NEEDS CLARIFICATION: What migration guidance (if any) should be provided for active branches already using verbatim copies?]
    • [NEEDS CLARIFICATION: How should semantic-equivalent but text-different constraints be compared in analysis?]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5429 · copilot · gpt53codex · 51.3 AIC · ⌖ 0.689 AIC · ⊞ 27.7K · ◷

  5. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — cite-model-constraints · Stage 4/5: Concept

    Concept: Canonical constraint references in task generation

    • Slug: cite-model-constraints
    • Created: 2026-11-16T20:51:56Z
    • Recommended option: Option B — Citation-first with analyzer enforcement

    Options

    Option A — Keep verbatim copies, add drift checks only

    • Sketch: Continue generating task text with copied field constraints, but extend analysis to compare copied constraints against canonical data-model.md values and flag mismatches.
    • Appetite: medium
    • Trade-offs: Preserves current task readability and existing workflow behavior; still maintains two mutable representations of the same constraint and requires robust equivalence logic.
    • Rabbit holes: Parsing freeform copied prose reliably; false positives from formatting differences; ongoing maintenance of comparison heuristics.

    Option B — Citation-first with analyzer enforcement

    • Sketch: Require each constrained field to be cited in tasks via explicit data-model.md Entity.field references, with only local deltas restated when intentionally narrowing behavior; analyzer checks for missing citations and contradictory restatements.
    • Appetite: medium
    • Trade-offs: Reduces duplication and drift risk while preserving explicit traceability; requires convention clarity and analyzer/task-template updates to avoid ambiguity.
    • Rabbit holes: Defining strict-but-usable citation grammar; deciding severity and migration expectations; handling semantic-equality edge cases.

    Option C — Do nothing

    • Sketch: Keep current verbatim-copy rule and existing analyzer scope unchanged.
    • Appetite: small
    • Trade-offs: Zero implementation effort now; retains known stale-copy risk and manual synchronization burden called out by requesters.
    • Rabbit holes: Future regressions may require higher-cost fixes under delivery pressure.

    Recommendation

    Recommend Option B. It directly targets the identified failure mode (drift between canonical model constraints and copied task prose) while preserving explicit implementation guidance through stable pointers. Compared with Option A, it avoids making duplicated text the long-term primary mechanism and aligns better with single-source-of-truth documentation practice.

    Out of Scope (for the recommended option)

    • Full redesign of /speckit.analyze beyond checks needed for constrained-field coverage and mismatch detection.
    • Broader task-template verbosity optimization outside constrained-field handling.
    • Backfilling or auto-migrating all historical task artifacts in external repositories.
    • Detailed implementation design (parsers, matching algorithms, or code structure).

    Assumptions to Validate

    • Implementers can reliably act on citation pointers because /speckit.implement already loads data-model.md.
    • Citation syntax can be defined tightly enough for deterministic analysis and testing.
    • Teams prefer canonical-reference workflows over duplicated prose when both remain explicit.
    • Regression coverage can encode both positive (all constrained fields cited) and negative (paraphrase-only/mismatch) cases without fragile fixtures.

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5429 · copilot · gpt53codex · 51.3 AIC · ⌖ 0.689 AIC · ⊞ 27.7K · ◷

  6. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    Feature assessment — cite-model-constraints · Stage 5/5: Decision — verdict go

    Decision: Cite constraints by reference with analyzer checks

    • Slug: cite-model-constraints
    • Decided: 2026-11-16T20:51:56Z
    • Verdict: go
    • Artifacts reviewed: intake.md | research.md | problem.md | concept.md

    Scorecard

    Criterion Rating Justification
    Problem validity strong The issue identifies a concrete failure mode: duplicated constraint text drifts and can mislead implementation despite prior safeguards.
    Evidence strength adequate Evidence is grounded in current templates/tests/changelog and a detailed reproduction narrative, but lacks broad usage telemetry.
    Value vs. inaction strong Reducing contradiction risk in core SDD artifacts and improving pre-implementation detection has clear process value over status quo maintenance burden.
    Feasibility / appetite adequate A medium-appetite concept exists (template rule + analyzer/test updates) without requiring architectural redesign.
    Strategic fit adequate The change aligns with Spec Kit’s consistency and deterministic-workflow goals, while preserving explicit implementation guidance.
    Risk posture adequate Key risks (citation ambiguity, false positives, migration confusion) are identified and can be managed with explicit grammar and regression tests.

    Verdict & Rationale

    Go. The problem is real and repeatedly adjacent to known regressions, evidence is sufficient to justify specification, and there is a credible concept that preserves the original anti-invention objective while reducing drift risk. The remaining unknowns are implementation-detail clarifications appropriate for /speckit-specify, not blockers to entering specification.

    If needs-clarification

    • Blocking questions: none
    • Revisit stage: n/a

    If go — Handoff to /speckit-specify

    • Problem: Duplicated constrained-field prose in tasks.md can drift from canonical data-model.md, creating contradictory implementation guidance.
    • Chosen approach: Citation-first constrained-field references (data-model.md Entity.field) plus analyzer checks for missing references and contradictory stated constraints.
    • In scope / out of scope: In scope: task-template rule updates, analyze coverage extension for constrained fields, regression tests for positive/negative scenarios. Out of scope: broader analyzer redesign, unrelated task verbosity refactors, mass migration of historical artifacts.
    • Success metrics: Every constrained field is explicitly cited by generated tasks; analyzer flags missing citations and mismatches; regression fixtures cover [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383/fix(tasks): require field constraints from data-model.md in generated tasks #4430 lineage scenarios.
    • Carried-forward open questions:
      • [NEEDS CLARIFICATION: Canonical citation grammar and acceptable variants.]
      • [NEEDS CLARIFICATION: Severity policy for missing citation vs. mismatch findings.]
      • [NEEDS CLARIFICATION: Exact mismatch detection semantics (literal vs. normalized equivalence).]

    Generated by 💡 Assess a Feature Request by Installing and Running Spec Kit for #5429 · copilot · gpt53codex · 51.3 AIC · ⌖ 0.689 AIC · ⊞ 27.7K · ◷

  7. added
    feature-goFeature assessment verdict: go — ready to hand off to /speckit.specify
    on Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature-assessRun the Spec Kit idea-assessment pipeline on this feature requestfeature-goFeature assessment verdict: go — ready to hand off to /speckit.specifytriage-can-waitVerdict: valid and in-scope but deprioritized; held behind the evidence gate

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions