Repository navigation
Description
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:
- Copies drift.
data-model.md,research.mdand the contracts keep changing after/speckit.tasks, through/speckit.planre-runs, hand edits and fixes found mid-implementation. Re-running/speckit.tasksthen 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. /speckit.analyzeis 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 (fromplan.md, only its "Data Model references"). A task contradictingdata-model.mdis 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 asdata-model.mdEntity.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 readdata-model.mdat v1.0.1 too. What changes is that each task carries an explicit pointer instead of a paraphrase, and analyze enforces it. /speckit.analyzealso loadsdata-model.mdand 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 fromdata-model.md.tests/test_tasks_template_constraints.pyasserts 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.implementruns, where a task's own text is what the agent acts on. - Features whose
data-model.mdhas many constrained fields, where per-field copies maketasks.mdlong and noisy. - Repositories with a single-source-of-truth convention for documentation.
Acceptance Criteria
- Given a
data-model.mdwith constrained fields, every constrained field is cited by at least one task asdata-model.mdEntity.field, and no task restates a constraint it does not change. -
/speckit.analyzereports a constrained field that no task cites, including one only paraphrased in prose. -
/speckit.analyzereports a task whose stated constraint differs fromdata-model.md. - Regression fixture: [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383's scenario (two fields, each
max length 200) yields tasks citing both fields, and analyze flags atasks.mdthat only paraphrases one, as [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383's did.
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
github-actions commentedon Nov 16, 2026
Feature assessment — cite-model-constraints · Stage 1/5: Intake
Idea Intake: Cite data-model constraints by reference
/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429Idea (as captured)
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.mdfields. It also asks for analyzer checks that detect missing references and mismatches, so constraint drift is caught before implementation.Origin & Context
First-Glance Unknowns
data-model.mdEntity.field, or are equivalent explicit forms acceptable?]/speckit.analyzeenforce this rule only for constrained fields, or for all data-model fields referenced by tasks?]tasks.mdfiles be migrated, or should the change apply only to newly generated tasks?]github-actions commentedon Nov 16, 2026
Feature assessment — cite-model-constraints · Stage 2/5: Research
Idea Research: Constraint citation over duplication
Users & Demand
/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 — [source: https://github.com/[Feature]:/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 | cited] (confidence: medium)/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 body; CHANGELOG.md line 637 | cited] (confidence: medium)Prior Art
data-model.mdinto task text (templates/commands/tasks.md, line 200), mirrored in the tasks skill and enforced by a regression test (tests/test_tasks_template_constraints.py, line 24) — [source: repository files | cited] (confidence: high)CHANGELOG.md, line 637), so any new approach must preserve the original anti-invention intent from [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383 — [source: CHANGELOG.md; issue [Feature]:/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 narrative | cited] (confidence: high)/speckit.implementalready loadsdata-model.mdcontext (templates/commands/implement.md, lines 90–96), so referencing a canonical field path is compatible with existing implementation-context loading — [source: repository file | cited] (confidence: high)Market & Context
/speckit.tasks— [source: issue [Feature]:/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 | cited] (confidence: medium)Data & Constraints
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)Evidence Against the Idea
/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 relationship notes | cited] (confidence: medium)Gaps & Open Questions
/speckit.analyzeshould hard-fail on paraphrase, or warn with severity levels.]tasks.mdusing verbatim copies.]Sources
/speckit.tasks— cite data-model constraints instead of copying them verbatim #5429 (host: github.com, policy: allowlisted)templates/commands/tasks.md(line 200; local source)tests/test_tasks_template_constraints.py(line 24; local source)templates/commands/analyze.md(line 54; local source)templates/commands/implement.md(lines 90–96; local source)CHANGELOG.md(line 637; local source)github-actions commentedon Nov 16, 2026
Feature assessment — cite-model-constraints · Stage 3/5: Problem
Problem Definition: Constraint drift between model and task artifacts
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
/speckit.tasksand/speckit.implement— they risk implementing wrong limits/validation when task text anddata-model.mddiverge.Goals
tasks.md.Non-Goals
tasks.mdartifact in existing repositories.Success Metrics
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
tasks.md?]github-actions commentedon Nov 16, 2026
Feature assessment — cite-model-constraints · Stage 4/5: Concept
Concept: Canonical constraint references in task generation
Options
Option A — Keep verbatim copies, add drift checks only
data-model.mdvalues and flag mismatches.Option B — Citation-first with analyzer enforcement
data-model.mdEntity.fieldreferences, with only local deltas restated when intentionally narrowing behavior; analyzer checks for missing citations and contradictory restatements.Option C — Do nothing
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)
/speckit.analyzebeyond checks needed for constrained-field coverage and mismatch detection.Assumptions to Validate
/speckit.implementalready loadsdata-model.md.github-actions commentedon Nov 16, 2026
Feature assessment — cite-model-constraints · Stage 5/5: Decision — verdict go
Decision: Cite constraints by reference with analyzer checks
Scorecard
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
If go — Handoff to
/speckit-specifytasks.mdcan drift from canonicaldata-model.md, creating contradictory implementation guidance.data-model.mdEntity.field) plus analyzer checks for missing references and contradictory stated constraints.