Repository navigation
fix(aidd-pm): spec-template.md has no home for TBD markers, placement is non-deterministic #626
Description
Description
04-spec's spec-template.md has no place for unresolved open questions (unlike prd-template.md, which has ## Open Questions). build/refine mark genuine gaps as TBD: <precise question> per references/tbd-marker.md, but with nowhere designated to put them, placement is left to the drafting agent's judgment each run — confirmed non-deterministic by two real runs on the same project: one run put 3 TBDs in ## Hard constraints (where they read as nonsense — a hard constraint can't be undecided, and it contradicts spec-validator.yml's own definition of that section: "concrete and testable, not vague"), a later run on a refined version of the same feature put the same kind of TBDs under ## Context instead.
Expected behaviour
spec-template.md gets a ## Open Questions section (mirroring prd-template.md). Every TBD: — regardless of which section it would eventually fill — lists there, once, deterministically. Target, Hard constraints, Non-goals, and Done-when stay 100% resolved, concrete content only; incomplete because a decision is pending is fine, but nothing vague sits inside them. spec-validator.yml and the citing text in 01-build.md/02-refine.md/SKILL.md's Transversal rules need the matching update (TBD's home becomes ## Open Questions, not "wherever the missing field lives").
Note: unlike PRD's Open Questions (which can legitimately persist post-completion — deferred, non-blocking items), a spec's Open Questions should drive to zero before the spec validates/locks (spec-validator.yml's any_required_unfulfilled: invalid already enforces this for required sections) — worth stating explicitly so the section doesn't silently become a place TBDs go to be forgotten.
Affected file(s)
plugins/aidd-pm/skills/04-spec/assets/spec-template.md, assets/spec-validator.yml, actions/01-build.md, actions/02-refine.md, SKILL.md
Observed behaviour
Same feature, two separate 04-spec runs, two different TBD placements (Hard constraints vs Context) — no section owns it, so the drafting agent improvises each time.
AI tool
Claude Code
OS
macOS
Additional context
Surfaced during #564's router-contract migration (out of scope there — behaviour change, that issue is shape-only). Related to #625 (SDLC never checks spec-validator.yml before treating a spec as a finished contract) but a different root cause: this is the template itself having no home for the marker, not the orchestration layer failing to gate on it.
Activity
refactor(aidd-pm): migrate ticket-info, prd, and spec to router contr…
refactor(aidd-pm): migrate ticket-info, prd, and spec to router contr…
refactor(aidd-pm): migrate ticket-info, prd, and spec to router contr…
fix(aidd-pm): scope the spec marker rule to every other section and l…
docs(aidd-pm): name the gap once in the spec open questions plan
docs(aidd-pm): record the spec open questions journey and review
fix(aidd-pm): cut the spec gap rules to the words that change the draft
fix(aidd-pm): say the refine gap step once
refactor(aidd-pm): cut the spec actions to the words that change the …
fix(aidd-pm): put back the three clauses the cut should have kept
docs(aidd-pm): record what the installed tree does, and what it refuses
fix(aidd-pm): a gap written elsewhere refuses the spec, a gap still o…
refactor(aidd-pm): the spec skill keeps only the words that change a …
refactor(aidd-pm): the backlog declaration shape becomes an asset
fix(aidd-pm): a section says it is optional in its guidance, not in i…
test(cli): the taught backlog example can be an asset, not only a fen…
test(cli): drop the comments the code already says
fix(aidd-pm): give a spec gap one home, and refuse only one written e…
blafourcade commentedon Oct 7, 2026
Delivered by #969, squash-merged into
nextas22c541a7. A squash merge from a non-default base does not auto-close aCloses #626, so this is closed by hand.What landed.
assets/spec-template.mdowns the open questions section and is the only file naming its heading.references/tbd-marker.mddefines what belongs there — a gap is an unresolved decision a required section depends on — and both actions point at it.spec-validator.ymlrepeats that definition on purpose: its evaluator reads the yml alone, and without it one supplied its own notion and refused a spec whose content was complete.One acceptance criterion read differently than written. This issue asked for
TBD:to invalidate a spec until resolved. Measured through the installed tree, a request answering every required field still lists two or three entries, always the CSV column set and when the seven days start. Neither is a decision a required section depends on. So that rule refused complete work, and before this change an extra question cost nothing. What invalidates a spec is now a gap written outside the section — the defect this issue actually measured. Driving to zero stays as intent in the template, and as a requirement for #625, the only thing that will read the validator.SKILL.mdwas listed as affected and is untouched. Its transversal rule names no placement, so there was nothing to retarget.Past the issue, on the author asking for the existing text to be cut too: the skill went from 1379 to 1050 words, the backlog declaration left a step for its own reference with its shape as an asset, and two repository guards followed it — one in
scripts/__tests__/, one incli/tests/, the second caught by CI after no local gate could run it.How it was proved. 40 runs through a tree rebuilt by
aidd translate, each in its own sandbox, counts taken mechanically: placement 8/8 then 4/4, from a PRD 3/3, on a second model 3/3, refine 3/3, the backlog declaration 3/3, each validator case 2/2. Three independent reviewers, four rounds, every round's findings repaired and re-measured.Still true, and stated in the pull request. The Skill tool's own registration is unmeasured: a user-scope install shadows any project sandbox, and isolating the config logs the session out. Drafts over-ask on a thin request, six to eight entries, on both models tried — nothing refuses a spec for it. #626's sibling root cause, #625, is untouched.