fix(aidd-pm): spec-template.md has no home for TBD markers, placement is non-deterministic

Open
#626 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Quiet
Domain
documentation

Research direction

Read plugins/aidd-pm/skills/04-spec/assets/spec-template.md alongside prd-template.md and references/tbd-marker.md, then inspect assets/spec-validator.yml and the cited build, refine, and SKILL.md text. Done means the affected files consistently designate ## Open Questions as the sole home for TBD markers and state the required zero-before-lock behavior.

Written by the indexing model from the issue text.

Description

good first issue

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.

Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
14h 36m
Merged PRs (30d)
110

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from ai-driven-dev/framework

All issues in ai-driven-dev/framework

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.