[Bug]: SpecKit implementation differ from spec/data-model/research/PRD

[baozbao]

Bug Description

Hi,this is not really a bug, but rather unexpected.

During one development, I gave Speckit a PRD.
One of the feature is to add couple properties that max length are 200 to existing model.

The generated docs spec/data-model/research they all mentioned A 's length should be 1~200:
for example:
from data-model: | SuspendReason | nvarchar(200) | nullable

But the actual implementation is:
SuspendReasonMaxLength = 500

I went to check the documents, and found out in task.md
The max length was not mentioned.

The reason for max length =500 that the AI give to me is：
When generate the task.md file, the description for the task is vague for the property:

````to use real-time current-handler identity, version-aware state transitions, trimmed suspend reasons, 200-character remark validation, and explicit conflict results`````

The other property's length was mentioned, but not the suspend reasons.

Is this because when I run the /speckit.tasks command without description/specification or something else?
Should the tasks,md to be more specific for each individual task?

Steps to Reproduce

what I did:
specify init --here
/speckit.constitution
/speckit.specify *tell AI to look at the PRD under the doc folder
/speckit.plan

/speckit.tasks

/speckit.implement

Expected Behavior

Expected:
The task should mention both properties have max length 200

Actual Behavior

Mentioned only one property and missed another.

Specify CLI Version

1.0.1

AI Agent

Claude Code

Operating System

Windows 11

Python Version

3.11.9

Error Logs

Additional Context

No response

[github-actions]

Bug assessment — tasks-loses-field-constraints: Likely valid, needs reproduction · severity low

---

Bug Assessment: tasks loses field constraints

• Slug: tasks-loses-field-constraints
• Created: 2026-09-01T12:08:25Z
• Source: issue [Bug]: SpecKit implementation differ from spec/data-model/research/PRD #4383
• Verdict: likely valid, needs reproduction
• Severity: low

Report (summarized)

User (@baozbao) ran the full Spec-Driven Development workflow (specify init → /speckit.constitution → /speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement) on Windows 11 with Specify CLI 1.0.1 and Claude Code as the AI agent.

The PRD specified two properties with max length = 200. Both appeared correctly in the generated data-model.md (e.g., SuspendReason nvarchar(200)) and spec.md. However, the generated tasks.md only mentioned the max-length constraint for one of the two properties; SuspendReason had a vague task description. The AI agent then chose SuspendReasonMaxLength = 500 during /speckit.implement, deviating from the spec.

Symptom

Field-level constraints (e.g., max lengths, validation rules) present in data-model.md and spec.md are not reliably propagated into the generated tasks.md, causing the implementing AI agent to invent its own values. Expected: every task that creates or modifies a constrained field explicitly states the constraint from the data model.

Reproduction

1. Create a spec (/speckit.specify) that includes two or more properties with explicit max-length constraints.
2. Run /speckit.plan — verify both constraints appear in data-model.md.
3. Run /speckit.tasks with no extra arguments.
4. Inspect tasks.md — check whether both properties' max-length constraints are listed in the corresponding task descriptions.
5. Run /speckit.implement and verify which max-length value is used in generated code.

[NEEDS CLARIFICATION: Reporter did not share the PRD or generated tasks.md/data-model.md, so exact repro inputs are unknown.]

Suspected Code Paths

• templates/commands/tasks.md:65-77 — The "Load design documents" step loads data-model.md as optional and says "Extract entities and map to user stories," but does not instruct the AI to carry forward individual field constraints (max lengths, validation rules) into task descriptions.
• templates/commands/tasks.md:170-179 — The "Task Generation Rules" section requires clear file paths and checklist format but has no requirement to include field-level constraint values in the task description text.
• templates/commands/plan.md:141-151 — Phase 1 "Extract entities from feature spec → data-model.md" includes "Validation rules from requirements," correctly capturing constraints — but there is no downstream instruction to preserve these in tasks.md.

No Python source code is involved in the failure; the entire workflow is LLM-prompt-driven.

Root Cause Hypothesis

The /speckit.tasks command template (templates/commands/tasks.md) instructs the AI to extract entities from data-model.md and map them to user stories, but it does not explicitly require that field-level constraints (max lengths, nullable flags, enum values, validation rules) be surfaced verbatim in the generated task descriptions. This leaves the decision to the AI's discretion. When a field description in data-model.md is terse or a constraint applies to several fields simultaneously, the AI may omit it for some fields, causing the implementing agent to fall back to its own defaults.

Confidence: medium — the mechanism is plausible and consistent with the template wording, but cannot be confirmed without the reporter's actual input files.

Proposed Remediation

Preferred: Strengthen the task-generation instructions in templates/commands/tasks.md to explicitly require that when a task involves creating or modifying a field that carries constraints in data-model.md (max length, validation rule, nullable/required, enum values), the task description must quote those constraints verbatim. A single sentence addition to the "Task Organization — From Data Model" section (around line 197) would suffice:

For each entity field with validation rules (max length, enum values, required/nullable, format), the task description MUST include the constraint value exactly as stated in data-model.md (e.g., "SuspendReason nvarchar(200), nullable").

This keeps the fix non-breaking (only the prompt changes) and raises the floor on constraint fidelity without restructuring the template.

Alternatives:

• Add a post-generation validation step to /speckit.tasks that cross-references data-model.md constraints against the generated task text and flags mismatches — more thorough but adds latency and complexity to every run.
• Add a converge or analyze step between /speckit.tasks and /speckit.implement that explicitly checks constraint propagation — already partially supported by the speckit.analyze handoff, but would need explicit constraint-checking instructions there.

Files likely to change:

• templates/commands/tasks.md (Task Organization → From Data Model section, ~line 197)
• presets/lean/commands/speckit.tasks.md (lean preset variant — check whether it also needs the same addition)

Tests to add or update:

• A template-rendering or integration test that verifies a tasks.md generated from a fixture data-model.md containing max-length constraints includes those constraint values in the task text for every affected field.
• Update or create a test in the existing test suite covering the /speckit.tasks prompt behavior with constrained fields (if such a fixture-based test exists).

Risks & Considerations

• The fix is prompt-only; no Python code changes, no API breakage, no migration needed.
• Changing the template may make task descriptions longer/more verbose — acceptable trade-off for correctness.
• The lean preset (presets/lean/commands/speckit.tasks.md) is a separate file and must be updated in parallel if it diverges from the core template.
• Different AI agents may still paraphrase rather than quote constraints exactly; the instruction helps but does not guarantee perfect fidelity across all LLMs.

Open Questions

• [NEEDS CLARIFICATION: Can the reporter share the PRD, the generated data-model.md, and the generated tasks.md? This would confirm whether the missed constraint was present in data-model.md but omitted from tasks.md, or if it was also missing from data-model.md.]
• [NEEDS CLARIFICATION: Was /speckit.tasks invoked with any arguments ($ARGUMENTS non-empty)? Extra context could affect what the AI emphasizes.]

Generated by 🐛 Assess Bug from Labeled Issue for issue #4383 · 86.1 AIC · ⌖ 11.2 AIC · ⊞ 34.2K · ◷