fix(aidd-pm): spec-template.md has no home for TBD markers, placement is non-deterministic
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
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ai-driven-dev/framework
-
refactor(aidd-orchestrator): the check zone says when to stop, and reviews its axes in one round Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
ai-driven-dev/framework#887 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
ai-driven-dev/framework#873 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
ai-driven-dev/framework#872 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
ai-driven-dev/framework#625 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
ai-driven-dev/framework#467 · 1 comment ·
All issues in ai-driven-dev/framework
Similar issues
-
comp/desktop P3 type/bug
Difficulty 1/5 Under an hour Newbie friendliness 92/100
NousResearch/hermes-agent#118866 ·
-
Browser Waiting for: Product Owner
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
getsentry/sentry-javascript#24577 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
agilepathway/label-checker#640 ·
-
Plugin stuck at "loading" on DSH 0.1.6-alpha.2 — turnTail list slot registration missing options.id Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
chrisparsons83/flexspotff#153 ·