feat: Update SDD-1 to reduce questions that can be answered from context#46
Open
twellspring wants to merge 8 commits intomainfrom
Open
feat: Update SDD-1 to reduce questions that can be answered from context#46twellspring wants to merge 8 commits intomainfrom
twellspring wants to merge 8 commits intomainfrom
Conversation
Contributor
|
👋 Thank you for opening this pull request! We require PR titles to follow the Conventional Commits specification. Error details: Valid format: Valid types: Examples:
Please update your PR title and the check will run automatically. |
Contributor
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. 📝 WalkthroughWalkthroughOverhauls and adds SDD spec-generation prompts into a context-first, structured workflow: enforces repository-wide context assessment, introduces Phase A (identify information gaps) and Phase B (Questions File creation with template and STOP/WAIT rules), and provides strict spec templates, directory conventions, and iterative review guidance. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
prompts/SDD-1-generate-spec.md (2)
189-194: Two minor clarity gaps in the Progressive Disclosure and skip instruction1. Undocumented threshold range (lines 189–193): The guidance defines 0–5 questions for "mature" codebases (3+ specs) and 8–12 for "new" ones, but the 6–7 question range and codebases with 1–2 completed specs have no explicit guidance. An AI agent encountering a mid-maturity codebase has no anchor point.
2. Imprecise context reference (line 194): "Use the context gathered in Phase A" is narrowly scoped — Phase A is a question-resolution step, and its context is a subset of what was gathered in Step 2. An AI agent reading this literally when skipping to spec generation might not draw on the richer Step 2 codebase analysis. Line 154 correctly says "using context gathered in Step 2" for Phase A itself; line 194 should match that precision.
✏️ Suggested clarifications
-**Progressive Disclosure:** Focus on essential questions only. The number of questions will vary based on available context: -- **Mature codebases** (3+ completed specs, clear patterns): Aim for 0-5 questions, or skip questions entirely if all requirements are clear -- **New codebases** (limited context): May require 8-12 questions to establish requirements -- **Always prioritize**: Questions about business logic, user preferences, and novel functionality over technical implementation details +**Progressive Disclosure:** Focus on essential questions only. The number of questions will vary based on available context: +- **Mature codebases** (3+ completed specs, clear patterns): Aim for 0-5 questions, or skip questions entirely if all requirements are clear +- **Developing codebases** (1-2 completed specs, some patterns): Aim for 5-8 questions, focusing on areas not yet established +- **New codebases** (no completed specs, limited context): May require 8-12 questions to establish requirements +- **Always prioritize**: Questions about business logic, user preferences, and novel functionality over technical implementation details -**If no questions are needed:** Skip directly to Step 5 (Spec Generation). Use the context gathered in Phase A to inform the spec. +**If no questions are needed:** Skip directly to Step 5 (Spec Generation). Use the context gathered in Step 2 and Phase A to inform the spec.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` around lines 189 - 194, Update the "Progressive Disclosure" guidance to cover mid-maturity and low-maturity edge cases and fix the context reference: explicitly add guidance for codebases with 1–2 completed specs (e.g., recommend 6–8 questions) and for the 6–7 question gap (normalize to a 6–8 or 6–7 bucket depending on signal), and change the phrase "Use the context gathered in Phase A" to "Use the context gathered in Step 2" so the skip-to-Step-5 instruction consistently references the fuller analysis; modify the text in the Progressive Disclosure block and the Step 5 skip sentence (keywords: "Progressive Disclosure", "Phase A", "Step 5 (Spec Generation)", "Step 2") accordingly.
152-161: Consider specifying the expected user-facing output of Phase AThe
(Internal)label implies Phase A is an internal processing step, but there's no guidance on what — if anything — should be reported to the user. Without this, an AI agent may either produce a lengthy verbose dump of all candidate questions and their context-based resolutions (flooding the response before any questions file), or silently skip it entirely with no transparency. A brief instruction clarifying the expected output level would make behavior more predictable.✏️ Suggested clarification
-### Phase A: Context-Based Resolution (Internal) +### Phase A: Context-Based Resolution (Internal — Do Not Surface to User) -Before creating a questions file, generate and attempt to answer common clarifying questions using context gathered in Step 2: +Before creating a questions file, silently generate and attempt to answer common clarifying questions using context gathered in Step 2. Do not output Phase A reasoning or intermediate results to the user — proceed directly to Phase B or Step 5.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` around lines 152 - 161, The Phase A description ("Phase A: Context-Based Resolution (Internal)") lacks guidance on what, if anything, should be surfaced to the user after generating/answering clarifying questions from Step 2 and before creating the questions file; update the Phase A text to state a clear expected user-facing output (e.g., produce no verbose dump but instead generate a brief internal summary: a 1–2 sentence assessment plus the top 3 candidate questions with short answers OR only emit a single "ambiguous: true" flag if unresolved), and mention that these items should be embedded into the questions file metadata; reference the section name "Phase A: Context-Based Resolution (Internal)", the earlier "Step 2" context gathering, and the resulting "questions file" so the agent implementation knows where to put the concise summary or flag.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@prompts/SDD-1-generate-spec.md`:
- Around line 189-194: Update the "Progressive Disclosure" guidance to cover
mid-maturity and low-maturity edge cases and fix the context reference:
explicitly add guidance for codebases with 1–2 completed specs (e.g., recommend
6–8 questions) and for the 6–7 question gap (normalize to a 6–8 or 6–7 bucket
depending on signal), and change the phrase "Use the context gathered in Phase
A" to "Use the context gathered in Step 2" so the skip-to-Step-5 instruction
consistently references the fuller analysis; modify the text in the Progressive
Disclosure block and the Step 5 skip sentence (keywords: "Progressive
Disclosure", "Phase A", "Step 5 (Spec Generation)", "Step 2") accordingly.
- Around line 152-161: The Phase A description ("Phase A: Context-Based
Resolution (Internal)") lacks guidance on what, if anything, should be surfaced
to the user after generating/answering clarifying questions from Step 2 and
before creating the questions file; update the Phase A text to state a clear
expected user-facing output (e.g., produce no verbose dump but instead generate
a brief internal summary: a 1–2 sentence assessment plus the top 3 candidate
questions with short answers OR only emit a single "ambiguous: true" flag if
unresolved), and mention that these items should be embedded into the questions
file metadata; reference the section name "Phase A: Context-Based Resolution
(Internal)", the earlier "Step 2" context gathering, and the resulting
"questions file" so the agent implementation knows where to put the concise
summary or flag.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
prompts/SDD-1-generate-spec.md (2)
64-70:⚠️ Potential issue | 🟡 MinorStep 4 overview label is stale — still reads "Clarifying Questions".
The Spec Generation Overview at Line 68 still names Step 4 "Clarifying Questions", but the step's actual heading (Line 154) was renamed to "Identify Information Gaps" in this PR. A reader (or the AI agent) navigating from the overview to the step will encounter a mismatch.
📝 Proposed fix
-4. **Clarifying Questions** - Gather detailed requirements through structured inquiry +4. **Identify Information Gaps** - Assess context gaps and gather requirements through structured inquiry🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` around lines 64 - 70, Update the Step 4 label in the Spec Generation overview so it matches the renamed heading: change the overview text "Step 4 — Clarifying Questions" to "Step 4 — Identify Information Gaps" (or vice-versa if you prefer the original) so the overview line and the actual heading "Identify Information Gaps" are consistent; edit the markdown block in prompts/SDD-1-generate-spec.md that lists the numbered steps (the line currently showing "Clarifying Questions") to use the exact phrase "Identify Information Gaps".
241-241:⚠️ Potential issue | 🟡 Minor"Return to step 3" is ambiguous — conflicts with top-level Step 3.
Line 241 instructs the agent to "repeat the process (return to step 3)" after creating a follow-up questions file. Within the Questions File Process sub-list, sub-step 3 is "STOP AND WAIT", which is the intended target. However, at the top-level workflow, Step 3 is "Initial Scope Assessment" — an entirely different instruction. An AI agent parsing this literally could loop back to re-evaluate scope rather than halting to wait for user answers.
📝 Proposed fix — disambiguate the reference
-5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). +5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat this process from sub-step 2 (Point User to File → STOP AND WAIT → Read Answers).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` at line 241, The phrase "return to step 3" is ambiguous; update the wording to explicitly reference the Questions File Process sub-step by changing it to something like "return to Questions File Process sub-step 3 (STOP AND WAIT)" so the agent knows to halt and wait for answers rather than looping back to the top-level Step 3 Initial Scope Assessment; locate this text in prompts/SDD-1-generate-spec.md where the follow-up questions file creation is described and replace the ambiguous reference accordingly.
🧹 Nitpick comments (2)
prompts/SDD-1-generate-spec.md (2)
236-236: Questions file path is unspecified — only the filename is given.Line 236 instructs saving to
[NN]-questions-[N]-[feature-name].mdwith no directory path. Step 1 establishes./docs/specs/[NN]-spec-[feature-name]/as the canonical location for all spec-related files ("questions, spec, tasks, proofs"), and Step 5's output uses a fully-qualified path. Leaving the directory implicit here creates ambiguity about where the questions file lands.📝 Proposed fix — add explicit path
-1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). +1. **Create Questions File**: Save questions to `./docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` at line 236, Update Step 1 so the questions filename includes the canonical directory by specifying the full path (e.g., ./docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md) to match Step 5 and the earlier statement that all spec-related files live in ./docs/specs/[NN]-spec-[feature-name]/; change the text that currently only lists `[NN]-questions-[N]-[feature-name].md` to the fully-qualified path so the questions file placement is unambiguous.
178-188: Minor style nits flagged by static analysis.LanguageTool flags two instances of
"without precedent"(Lines 178, 187) as wordy. Consider a shorter phrasing such as "Novel functionality new to the codebase" or simply "new functionality with no existing patterns."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-generate-spec.md` around lines 178 - 188, Replace the wordy phrase "without precedent" in the two occurrences of the string "Novel functionality without precedent in the codebase" with a shorter, clearer phrase such as "new to the codebase" or "new functionality with no existing patterns"; update both the heading and the bullet point so they read e.g. "Novel functionality new to the codebase" or "New functionality with no existing patterns" to satisfy the LanguageTool suggestion.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@prompts/SDD-1-generate-spec.md`:
- Around line 64-70: Update the Step 4 label in the Spec Generation overview so
it matches the renamed heading: change the overview text "Step 4 — Clarifying
Questions" to "Step 4 — Identify Information Gaps" (or vice-versa if you prefer
the original) so the overview line and the actual heading "Identify Information
Gaps" are consistent; edit the markdown block in prompts/SDD-1-generate-spec.md
that lists the numbered steps (the line currently showing "Clarifying
Questions") to use the exact phrase "Identify Information Gaps".
- Line 241: The phrase "return to step 3" is ambiguous; update the wording to
explicitly reference the Questions File Process sub-step by changing it to
something like "return to Questions File Process sub-step 3 (STOP AND WAIT)" so
the agent knows to halt and wait for answers rather than looping back to the
top-level Step 3 Initial Scope Assessment; locate this text in
prompts/SDD-1-generate-spec.md where the follow-up questions file creation is
described and replace the ambiguous reference accordingly.
---
Nitpick comments:
In `@prompts/SDD-1-generate-spec.md`:
- Line 236: Update Step 1 so the questions filename includes the canonical
directory by specifying the full path (e.g.,
./docs/specs/[NN]-spec-[feature-name]/[NN]-questions-[N]-[feature-name].md) to
match Step 5 and the earlier statement that all spec-related files live in
./docs/specs/[NN]-spec-[feature-name]/; change the text that currently only
lists `[NN]-questions-[N]-[feature-name].md` to the fully-qualified path so the
questions file placement is unambiguous.
- Around line 178-188: Replace the wordy phrase "without precedent" in the two
occurrences of the string "Novel functionality without precedent in the
codebase" with a shorter, clearer phrase such as "new to the codebase" or "new
functionality with no existing patterns"; update both the heading and the bullet
point so they read e.g. "Novel functionality new to the codebase" or "New
functionality with no existing patterns" to satisfy the LanguageTool suggestion.
Seven copies of the original SDD-1 spec, one per iteration. Each will be updated to its iteration version in the working tree for IDE diff comparison. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
cdfb979 to
ac6d138
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🧹 Nitpick comments (6)
prompts/SDD-1-iteration4.md (1)
179-179: Optional: Simplify "without precedent in the codebase".LanguageTool flags this as wordy. Consider "new to the codebase" or "not yet in the codebase."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration4.md` at line 179, Replace the phrase "without precedent in the codebase" in the prompts/SDD-1-iteration4.md content with a simpler alternative such as "new to the codebase" or "not yet in the codebase"; locate the exact string "without precedent in the codebase" and swap it for one of the suggested shorter options to address the LanguageTool wordiness flag.prompts/SDD-1-iteration6.md (1)
186-186: Optional: Simplify "without precedent in the codebase".LanguageTool flags this as wordy. Consider "not yet in the codebase" or "new to the codebase."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration6.md` at line 186, Replace the phrase "without precedent in the codebase" in the prompt text with a shorter alternative such as "not yet in the codebase" or "new to the codebase"; locate the string in prompts/SDD-1-iteration6.md (the prompt line currently reading 'Novel functionality without precedent in the codebase') and update it to the chosen concise wording to reduce wordiness.prompts/SDD-1-iteration7.md (2)
178-187: Optional: Simplify "without precedent in the codebase" (appears twice).LanguageTool flags this as wordy. "Not yet in the codebase" or "new to the codebase" are shorter alternatives.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration7.md` around lines 178 - 187, The phrase "without precedent in the codebase" is wordy and repeated in the "Phase B: Create Questions File (If Needed)" section; replace both occurrences of that exact string with a shorter alternative such as "not yet in the codebase" or "new to the codebase" so the language is concise and consistent throughout the Phase B guidance (search for the literal "without precedent in the codebase" to locate the lines to update).
163-169: Optional: Vary the sentence openers in the Phase A checklist.Six of seven bullet points begin with "What." Consider mixing in alternate phrasings for a few items (e.g., "How should…", "Which proof artifacts…") to improve readability.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration7.md` around lines 163 - 169, The Phase A checklist in prompts/SDD-1-iteration7.md currently has six of seven bullets starting with "What"; update the checklist bullets (the lines like "What UI/UX patterns should be followed?", "What technical approach should be used?", etc.) to vary sentence openers for readability—replace a few "What" starters with alternatives such as "How should data be validated?", "Which proof artifacts will demonstrate it works?", "How should error handling be implemented?", or "When should edge cases be handled?" so the list mixes "What", "How", "Which", and "When" phrasing while preserving each item's intent.prompts/SDD-1-iteration5.md (1)
179-179: Optional: Simplify "without precedent in the codebase".LanguageTool flags this as wordy. Consider "not yet in the codebase" or "new to the codebase."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration5.md` at line 179, Replace the wordy phrase "Novel functionality without precedent in the codebase" with a simpler alternative such as "Novel functionality not yet in the codebase" or "New to the codebase" wherever that exact phrase appears (e.g., in the prompts text header "Novel functionality without precedent in the codebase"); update the sentence to use one of these shorter options to satisfy LanguageTool's brevity suggestion.prompts/SDD-1-iteration1.md (1)
1-11: Consider whether iteration files belong in theprompts/directory long-term.All 7 iteration files share
name: SDD-1-generate-specin their YAML frontmatter. If a prompt runner resolves prompts by name, having 7 files with the samenamefield in the same directory may cause conflicts or unexpected behavior — only one would be active. These appear to be development/comparison artifacts rather than production prompts. Consider moving them to adocs/orscratch/location, or excluding them from theprompts/directory that the runner scans.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration1.md` around lines 1 - 11, Multiple iteration prompt files share the same YAML frontmatter name "SDD-1-generate-spec", which can conflict with a prompt runner that resolves prompts by name; either rename the frontmatter "name" in the extra iteration files to unique identifiers (e.g., append -iter1, -iter2) or move these iteration files out of the prompts/ directory into a non-scanned location such as docs/ or scratch/, and ensure any runner configuration that scans the prompts/ directory is updated to exclude these moved files; target the YAML frontmatter "name: SDD-1-generate-spec" in each iteration file (or the set of seven files) to apply the change.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@prompts/SDD-1-iteration1.md`:
- Around line 209-213: Replace the standalone bold paragraph "**Question
Philosophy: Prefer zero questions when context is sufficient**" (and its
duplicates in iteration2/iteration3) with a proper markdown heading (e.g., "###
Question Philosophy: Prefer zero questions when context is sufficient") so it
uses heading syntax instead of emphasis; update the exact lines containing that
bold text in prompts/SDD-1-iteration1.md (and the corresponding occurrences in
iteration2 and iteration3) to the chosen heading level to satisfy MD036.
In `@prompts/SDD-1-iteration2.md`:
- Around line 210-214: The bold standalone line "**Question Philosophy: Prefer
zero questions when context is sufficient**" violates MD036; replace it with a
proper markdown heading or a normal sentence instead of using bold as a
heading—e.g., convert it to a heading like "### Question Philosophy: Prefer zero
questions when context is sufficient" or rephrase it into a regular paragraph
sentence; update the block near the "If Questions Are Needed" section so the
intent remains the same but the bold line is no longer acting as a heading.
In `@prompts/SDD-1-iteration3.md`:
- Around line 209-213: The CI failure is due to using bold text as a section
heading: replace the standalone bold paragraph "**Question Philosophy: Prefer
zero questions when context is sufficient**" with a proper Markdown heading
(e.g., "#### Question Philosophy: Prefer zero questions when context is
sufficient" or another appropriate heading level consistent with "### If
Questions Are Needed") so it conforms to MD036/no-emphasis-as-heading; update
the markup where that exact bold string appears and ensure surrounding spacing
follows heading conventions.
- Around line 249-362: The document currently contradicts itself by stating
"**ALWAYS create a questions file:**" then later titling the process "###
Questions File Process (If Questions Are Needed)"; update the heading and any
conditional language so they match the mandate—e.g., change "### Questions File
Process (If Questions Are Needed)" to "### Questions File Process (Always)" and
adjust the numbered steps under that heading to clearly state that a questions
file must always be created (with "Questions for User" set to "None" when no
user questions exist) and remove any wording that implies the file is optional;
ensure references to the filename pattern "[NN]-questions-[N]-[feature-name].md"
and the STOP AND WAIT requirement remain intact and consistent.
In `@prompts/SDD-1-iteration4.md`:
- Around line 254-268: Step 5 in the "Questions File Process" is inconsistent
and the proceed-gate is missing a condition; update the Step 5 line to match
formatting used by Steps 1–4 and 6 by making its key text bold (e.g., "**Step
5**: Look for comments under \"Questions Answered from Context\" and address
them."), and extend the "Only proceed to Step 5 after:" gate to include a second
part requiring that all corrections and issues flagged under "Questions Answered
from Context" have been reviewed and addressed before moving on (explicitly
mention "all corrections flagged in 'Questions Answered from Context' are
resolved").
In `@prompts/SDD-1-iteration5.md`:
- Around line 228-241: The numbered "Questions File Process" is missing an
explicit "Follow-Up Rounds" step so the iterative follow-up flow may be skipped;
add a new numbered step (e.g., "5. Follow-Up Rounds") right after step 4 that
instructs the agent to create subsequent questions files when user answers
reveal new clarifications, stop after each created questions file and wait for
answers, and only proceed after reviewing answers; update references in the
CRITICAL note and any later steps that assume a step 5 so they point to this new
"Follow-Up Rounds" step and ensure the phrase "STOP AND WAIT" remains mandatory
after creating any questions file (see the "Create Questions File" block and the
"CRITICAL" sentence).
In `@prompts/SDD-1-iteration6.md`:
- Around line 235-248: Add an explicit numbered step for "Follow-Up Rounds"
immediately after the current Step 4 in the numbered procedure (the list
starting "1. **Create Questions File**" through "4. **Read Answers**") so it
matches the prose under "Iterative Process"; the new Step 5 should state that if
answers generate new questions, create a new questions file and STOP to wait for
answers, and clarify that only after reviewing answers and having enough detail
should the workflow proceed—update any following step numbers or references and
ensure the "CRITICAL" sentence remains linked to this new Step 5.
---
Nitpick comments:
In `@prompts/SDD-1-iteration1.md`:
- Around line 1-11: Multiple iteration prompt files share the same YAML
frontmatter name "SDD-1-generate-spec", which can conflict with a prompt runner
that resolves prompts by name; either rename the frontmatter "name" in the extra
iteration files to unique identifiers (e.g., append -iter1, -iter2) or move
these iteration files out of the prompts/ directory into a non-scanned location
such as docs/ or scratch/, and ensure any runner configuration that scans the
prompts/ directory is updated to exclude these moved files; target the YAML
frontmatter "name: SDD-1-generate-spec" in each iteration file (or the set of
seven files) to apply the change.
In `@prompts/SDD-1-iteration4.md`:
- Line 179: Replace the phrase "without precedent in the codebase" in the
prompts/SDD-1-iteration4.md content with a simpler alternative such as "new to
the codebase" or "not yet in the codebase"; locate the exact string "without
precedent in the codebase" and swap it for one of the suggested shorter options
to address the LanguageTool wordiness flag.
In `@prompts/SDD-1-iteration5.md`:
- Line 179: Replace the wordy phrase "Novel functionality without precedent in
the codebase" with a simpler alternative such as "Novel functionality not yet in
the codebase" or "New to the codebase" wherever that exact phrase appears (e.g.,
in the prompts text header "Novel functionality without precedent in the
codebase"); update the sentence to use one of these shorter options to satisfy
LanguageTool's brevity suggestion.
In `@prompts/SDD-1-iteration6.md`:
- Line 186: Replace the phrase "without precedent in the codebase" in the prompt
text with a shorter alternative such as "not yet in the codebase" or "new to the
codebase"; locate the string in prompts/SDD-1-iteration6.md (the prompt line
currently reading 'Novel functionality without precedent in the codebase') and
update it to the chosen concise wording to reduce wordiness.
In `@prompts/SDD-1-iteration7.md`:
- Around line 178-187: The phrase "without precedent in the codebase" is wordy
and repeated in the "Phase B: Create Questions File (If Needed)" section;
replace both occurrences of that exact string with a shorter alternative such as
"not yet in the codebase" or "new to the codebase" so the language is concise
and consistent throughout the Phase B guidance (search for the literal "without
precedent in the codebase" to locate the lines to update).
- Around line 163-169: The Phase A checklist in prompts/SDD-1-iteration7.md
currently has six of seven bullets starting with "What"; update the checklist
bullets (the lines like "What UI/UX patterns should be followed?", "What
technical approach should be used?", etc.) to vary sentence openers for
readability—replace a few "What" starters with alternatives such as "How should
data be validated?", "Which proof artifacts will demonstrate it works?", "How
should error handling be implemented?", or "When should edge cases be handled?"
so the list mixes "What", "How", "Which", and "When" phrasing while preserving
each item's intent.
prompts/SDD-1-iteration1.md
Outdated
Comment on lines
+209
to
+213
| ### If Questions Are Needed | ||
|
|
||
| **Question Philosophy: Prefer zero questions when context is sufficient** | ||
|
|
||
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
Contributor
There was a problem hiding this comment.
CI failure: MD036 – bold text used instead of a heading.
**Question Philosophy: Prefer zero questions when context is sufficient** is a standalone bold paragraph used as a section heading, failing the MD036/no-emphasis-as-heading markdownlint rule and blocking CI. This same pattern appears in iteration2 (line 212) and iteration3 (line 211).
🔧 Proposed fix
-**Question Philosophy: Prefer zero questions when context is sufficient**
+### Question Philosophy: Prefer zero questions when context is sufficient📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### If Questions Are Needed | |
| **Question Philosophy: Prefer zero questions when context is sufficient** | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." | |
| ### If Questions Are Needed | |
| ### Question Philosophy: Prefer zero questions when context is sufficient | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration1.md` around lines 209 - 213, Replace the standalone
bold paragraph "**Question Philosophy: Prefer zero questions when context is
sufficient**" (and its duplicates in iteration2/iteration3) with a proper
markdown heading (e.g., "### Question Philosophy: Prefer zero questions when
context is sufficient") so it uses heading syntax instead of emphasis; update
the exact lines containing that bold text in prompts/SDD-1-iteration1.md (and
the corresponding occurrences in iteration2 and iteration3) to the chosen
heading level to satisfy MD036.
prompts/SDD-1-iteration2.md
Outdated
Comment on lines
+210
to
+214
| ### If Questions Are Needed | ||
|
|
||
| **Question Philosophy: Prefer zero questions when context is sufficient** | ||
|
|
||
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
Contributor
There was a problem hiding this comment.
CI failure: MD036 – bold text used instead of a heading.
**Question Philosophy: Prefer zero questions when context is sufficient** is a standalone bold paragraph acting as a section heading, which triggers the MD036/no-emphasis-as-heading markdownlint rule and fails CI.
🔧 Proposed fix
-**Question Philosophy: Prefer zero questions when context is sufficient**
+### Question Philosophy: Prefer zero questions when context is sufficient📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### If Questions Are Needed | |
| **Question Philosophy: Prefer zero questions when context is sufficient** | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." | |
| ### If Questions Are Needed | |
| ### Question Philosophy: Prefer zero questions when context is sufficient | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration2.md` around lines 210 - 214, The bold standalone line
"**Question Philosophy: Prefer zero questions when context is sufficient**"
violates MD036; replace it with a proper markdown heading or a normal sentence
instead of using bold as a heading—e.g., convert it to a heading like "###
Question Philosophy: Prefer zero questions when context is sufficient" or
rephrase it into a regular paragraph sentence; update the block near the "If
Questions Are Needed" section so the intent remains the same but the bold line
is no longer acting as a heading.
prompts/SDD-1-iteration3.md
Outdated
Comment on lines
+209
to
+213
| ### If Questions Are Needed | ||
|
|
||
| **Question Philosophy: Prefer zero questions when context is sufficient** | ||
|
|
||
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
Contributor
There was a problem hiding this comment.
CI failure: MD036 – bold text used instead of a heading.
Same issue as iteration1/iteration2: **Question Philosophy: Prefer zero questions when context is sufficient** is a standalone bold paragraph used as a section heading, failing the MD036/no-emphasis-as-heading markdownlint rule.
🔧 Proposed fix
-**Question Philosophy: Prefer zero questions when context is sufficient**
+### Question Philosophy: Prefer zero questions when context is sufficient📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### If Questions Are Needed | |
| **Question Philosophy: Prefer zero questions when context is sufficient** | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." | |
| ### If Questions Are Needed | |
| ### Question Philosophy: Prefer zero questions when context is sufficient | |
| Ask clarifying questions ONLY for decisions that cannot be inferred from existing patterns or documentation. Each question should address genuine ambiguity that blocks spec creation. Focus on understanding the "what" and "why" rather than the "how." |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 209 - 213, The CI failure is due to
using bold text as a section heading: replace the standalone bold paragraph
"**Question Philosophy: Prefer zero questions when context is sufficient**" with
a proper Markdown heading (e.g., "#### Question Philosophy: Prefer zero
questions when context is sufficient" or another appropriate heading level
consistent with "### If Questions Are Needed") so it conforms to
MD036/no-emphasis-as-heading; update the markup where that exact bold string
appears and ensure surrounding spacing follows heading conventions.
prompts/SDD-1-iteration3.md
Outdated
Comment on lines
+249
to
+362
| **ALWAYS create a questions file:** `[NN]-questions-1-[feature-name].md` | ||
|
|
||
| The file has two sections: | ||
| 1. **Questions for User** - Questions that need user input (if any) | ||
| 2. **Questions Answered by Context** - Questions you resolved from codebase, documentation, previous specs, or other sources | ||
|
|
||
| ```markdown | ||
| # [NN] Questions - [Feature Name] | ||
|
|
||
| ## Questions for User | ||
|
|
||
| [If none: "None - all questions resolved from existing context"] | ||
|
|
||
| [If there are questions for the user, use checkbox format:] | ||
|
|
||
| ### 1. [Question Category/Topic] | ||
|
|
||
| [What specific aspect of the feature needs clarification?] | ||
|
|
||
| - [ ] (A) [Option description explaining what this choice means] | ||
| - [ ] (B) [Option description explaining what this choice means] | ||
| - [ ] (C) [Option description explaining what this choice means] | ||
| - [ ] (D) [Option description explaining what this choice means] | ||
| - [ ] (E) Other (describe) | ||
|
|
||
| ## Questions Answered by Context | ||
|
|
||
| [Always include this section, even if empty] | ||
|
|
||
| 1. **[Question 1]?** | ||
| - Answer: [Brief answer] | ||
| - Source: [Where you found the answer - file, docs, issue] | ||
|
|
||
| 2. **[Question 2]?** | ||
| - Answer: [Brief answer] | ||
| - Source: [Where you found the answer] | ||
|
|
||
| 3. **[Question 3]?** | ||
| - Answer: [Brief answer] | ||
| - Source: [Where you found the answer] | ||
| ``` | ||
|
|
||
| **Example - No User Questions:** | ||
|
|
||
| ```markdown | ||
| # 07 Questions - Prevent Duplicates | ||
|
|
||
| ## Questions for User | ||
|
|
||
| None - all questions resolved from existing context | ||
|
|
||
| ## Questions Answered by Context | ||
|
|
||
| 1. **What defines duplicate?** | ||
| - Answer: firstName+lastName+telephone | ||
| - Source: GitHub issue #4 | ||
|
|
||
| 2. **Case sensitive?** | ||
| - Answer: No, case-insensitive | ||
| - Source: IgnoreCase pattern in OwnerRepository.java | ||
|
|
||
| 3. **Apply to updates?** | ||
| - Answer: No, creation only | ||
| - Source: Issue scope mentions "creation" | ||
| ``` | ||
|
|
||
| **Example - Mixed (some for user, some resolved):** | ||
|
|
||
| ```markdown | ||
| # 07 Questions - Prevent Duplicates | ||
|
|
||
| ## Questions for User | ||
|
|
||
| ### 1. Duplicate Handling Strategy | ||
|
|
||
| What should happen when a duplicate is detected? | ||
|
|
||
| - [ ] (A) Block creation completely (hard stop) | ||
| - [ ] (B) Show warning but allow override | ||
| - [ ] (C) Show suggestion to merge with existing | ||
|
|
||
| ## Questions Answered by Context | ||
|
|
||
| 1. **What defines duplicate?** | ||
| - Answer: firstName+lastName+telephone | ||
| - Source: GitHub issue #4 | ||
|
|
||
| 2. **Case sensitive?** | ||
| - Answer: No, case-insensitive | ||
| - Source: IgnoreCase pattern in OwnerRepository.java | ||
| ``` | ||
|
|
||
| ### Questions File Process (If Questions Are Needed) | ||
|
|
||
| **Remember: If you're asking many questions, you're likely asking about things you should infer from context.** | ||
|
|
||
| 1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). | ||
| 2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. | ||
| 3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. | ||
| 4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. | ||
| 5. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). | ||
| - **Note**: Follow-up rounds should be rare. If you need a second round, you likely asked the wrong questions in round 1. | ||
|
|
||
| **Iterative Process:** | ||
|
|
||
| - If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. | ||
| - Build on previous answers - use context from earlier responses to inform subsequent questions. | ||
| - **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. | ||
| - Only proceed to Step 5 after: | ||
| - You have received and reviewed all user answers to clarifying questions (if any were needed) | ||
| - You have documented any questions resolved from context in the questions file | ||
| - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). | ||
|
|
||
| **Note:** If all questions were resolved from context (no user questions needed), proceed directly to Step 5 after creating the questions file with "Questions for User: None" and filling out the "Questions Answered by Context" section. |
Contributor
There was a problem hiding this comment.
"ALWAYS create a questions file" conflicts with the "If Questions Are Needed" section heading.
Line 249 declares **ALWAYS create a questions file:**, but line 341's process section is titled ### Questions File Process (If Questions Are Needed) — the conditional framing directly contradicts the mandate. The true intent (always create, but the user section may say "None") is only clarified in Output Requirements and Critical Constraints much later, causing ambiguity for anyone reading just the Step 4 section.
Consider aligning the section heading with the actual behavior:
🔧 Proposed fix
-### Questions File Process (If Questions Are Needed)
+### Questions File Process🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 249 - 362, The document currently
contradicts itself by stating "**ALWAYS create a questions file:**" then later
titling the process "### Questions File Process (If Questions Are Needed)";
update the heading and any conditional language so they match the mandate—e.g.,
change "### Questions File Process (If Questions Are Needed)" to "### Questions
File Process (Always)" and adjust the numbered steps under that heading to
clearly state that a questions file must always be created (with "Questions for
User" set to "None" when no user questions exist) and remove any wording that
implies the file is optional; ensure references to the filename pattern
"[NN]-questions-[N]-[feature-name].md" and the STOP AND WAIT requirement remain
intact and consistent.
Comment on lines
+254
to
+268
| 1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). | ||
| 2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. | ||
| 3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. | ||
| 4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. | ||
| 5. Look for comments under "Questions Answered from Context" and address them. | ||
| 6. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). | ||
|
|
||
| **Iterative Process:** | ||
|
|
||
| - If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. | ||
| - Build on previous answers - use context from earlier responses to inform subsequent questions. | ||
| - **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. | ||
| - Only proceed to Step 5 after: | ||
| - You have received and reviewed all user answers to clarifying questions | ||
| - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). |
Contributor
There was a problem hiding this comment.
Step 5 formatting is inconsistent and the proceed-gate is missing a Part 2 condition.
Two issues in the Questions File Process block:
- Step 5 (line 258) is the only step not formatted with bold key text, breaking the visual pattern established by steps 1–4 and 6.
- The "Only proceed to Step 5 after:" gate (lines 266–268) lists two conditions but omits addressing corrections flagged in the "Questions Answered from Context" section — which is the entire purpose of step 5.
🛠️ Proposed fix
-5. Look for comments under "Questions Answered from Context" and address them.
+5. **Address Part 2 Corrections**: Review comments under "Questions Answered from Context" and correct any inaccurate inferences. - Only proceed to Step 5 after:
- You have received and reviewed all user answers to clarifying questions
+ - You have addressed any corrections flagged in the "Questions Answered from Context" section
- You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.).📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). | |
| 2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. | |
| 3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. | |
| 4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. | |
| 5. Look for comments under "Questions Answered from Context" and address them. | |
| 6. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). | |
| **Iterative Process:** | |
| - If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. | |
| - Build on previous answers - use context from earlier responses to inform subsequent questions. | |
| - **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. | |
| - Only proceed to Step 5 after: | |
| - You have received and reviewed all user answers to clarifying questions | |
| - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). | |
| 1. **Create Questions File**: Save questions to a file named `[NN]-questions-[N]-[feature-name].md` where `[N]` is the round number (starting at 1, incrementing for each new round). | |
| 2. **Point User to File**: Direct the user to the questions file and instruct them to answer the questions directly in the file. | |
| 3. **STOP AND WAIT**: Do not proceed to Step 5. Wait for the user to indicate they have saved their answers. | |
| 4. **Read Answers**: After the user indicates they have saved their answers, read the file and continue the conversation. | |
| 5. **Address Part 2 Corrections**: Review comments under "Questions Answered from Context" and correct any inaccurate inferences. | |
| 6. **Follow-Up Rounds**: If answers reveal new questions, create a new questions file with incremented round number (`[NN]-questions-[N+1]-[feature-name].md`) and repeat the process (return to step 3). | |
| **Iterative Process:** | |
| - If a user's answer reveals new questions or areas needing clarification, ask follow-up questions in a new questions file. | |
| - Build on previous answers - use context from earlier responses to inform subsequent questions. | |
| - **CRITICAL**: After creating any questions file, you MUST STOP and wait for the user to provide answers before proceeding. | |
| - Only proceed to Step 5 after: | |
| - You have received and reviewed all user answers to clarifying questions | |
| - You have addressed any corrections flagged in the "Questions Answered from Context" section | |
| - You have enough detail to populate all spec sections (User Stories, Demoable Units with functional requirements, etc.). |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration4.md` around lines 254 - 268, Step 5 in the "Questions
File Process" is inconsistent and the proceed-gate is missing a condition;
update the Step 5 line to match formatting used by Steps 1–4 and 6 by making its
key text bold (e.g., "**Step 5**: Look for comments under \"Questions Answered
from Context\" and address them."), and extend the "Only proceed to Step 5
after:" gate to include a second part requiring that all corrections and issues
flagged under "Questions Answered from Context" have been reviewed and addressed
before moving on (explicitly mention "all corrections flagged in 'Questions
Answered from Context' are resolved").
Committed at iteration 1 content, will be updated to iteration 2 in working tree for IDE diff comparison. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
prompts/SDD-1-iteration3.md (1)
1-365: All 6 iteration files contain identical content — no progression documented.Files
iteration1,iteration3,iteration4,iteration5,iteration6, anditeration7are word-for-word identical. If these are meant to archive the iterative journey from question-heavy to context-first (as described in the PR commit history), each file should capture a distinct evolutionary state of the prompt. As-is, six copies of the same content provide no historical value and add maintenance noise.Consider either removing the intermediate iteration files, or ensuring they genuinely reflect the state of the prompt at each iteration stage.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@prompts/SDD-1-iteration3.md` around lines 1 - 365, The PR contains six identical iteration files (iteration1, iteration3, iteration4, iteration5, iteration6, iteration7) which adds noise instead of documenting prompt evolution; either remove the redundant iteration files or replace each with the actual distinct state for that iteration so the history is meaningful. Locate the duplicate files (e.g., prompts/SDD-1-iteration3.md and its siblings iteration1/4/5/6/7), and: if you want a clean history, delete the unnecessary copies and keep a single canonical file (or consolidate into one file plus a single changelog); otherwise, update each iteration file to contain the real previous-version content reflecting changes between iterations (question-heavy, context-first, refinements, etc.), ensuring file names match their iteration number and the first lines include the unique iteration marker and a short changelog entry. Ensure the final commit removes or updates exactly those filenames to eliminate duplicate content.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@prompts/SDD-1-iteration3.md`:
- Around line 1-11: The frontmatter in each iteration file reuses the same
prompt identifier "name: SDD-1-generate-spec", causing name collisions when the
prompt runner loads prompts; update each iteration file to use a unique name
(e.g., change "name: SDD-1-generate-spec" to "name:
SDD-1-generate-spec-draft-vN" or similar) or move those iteration files out of
the prompts/ directory into a separate folder (e.g., docs/prompt-history) so the
prompt runner only sees the canonical "name: SDD-1-generate-spec" in prompts/;
apply this change to all iteration files (iteration1 through iteration7) so the
only prompt left in prompts/ with the canonical name is
prompts/SDD-1-generate-spec.md.
- Around line 181-205: The heading currently hardcodes "Round 1" in the template
string "# [NN] Questions Round 1 - [Feature Name]"; update the template to use a
round placeholder (e.g., "# [NN] Questions [N] - [Feature Name]" or a variable
like "[round]" / "{round}") so generated files reflect the actual round number,
and search for any other occurrences of "Round 1" in the prompts file to replace
with the same placeholder (refer to the exact heading text "# [NN] Questions
Round 1 - [Feature Name]" when locating the change).
- Around line 286-296: The fallback directive "If no specific standards are
identified, state \"Follow established repository patterns and conventions.\""
is currently indented under the list item "- Build and deployment workflows" so
it renders as part of that bullet; fix this by unindenting that line in the
"Repository Standards" section of prompts/SDD-1-iteration3.md so the fallback
becomes its own standalone paragraph (remove the leading list indentation or
preceding hyphen) and ensure it appears exactly as the quoted sentence so
renderers treat it as a separate directive.
- Around line 255-272: The Proof Artifacts examples contain nested backticks
(e.g. the strings "`Screenshot: `--help` output demonstrates new command
exists`" and "`CLI: `command --flag` returns expected output demonstrates
feature works`") which break Markdown code spans; update those examples in the
Proof Artifacts section so the outer code spans use double-backtick delimiters
(e.g. ``Screenshot: `--help` output demonstrates new command exists``) or
convert them to fenced code blocks, ensuring inner backticks remain literal and
the examples render as single code spans.
---
Duplicate comments:
In `@prompts/SDD-1-iteration1.md`:
- Around line 1-365: The file duplicates the same problems from iteration3: a
non-unique YAML name, hardcoded "Round 1" in the Questions template,
nested/backtick quoting issues, mis-indented "Repository Standards" section, and
misaligned NEVER/ALWAYS constraint lists; fix by (1) making the front-matter
name unique (e.g., append iteration or feature suffix in the name field), (2)
replace the hardcoded "Round 1" token in the Questions file template with a
templated placeholder ([N]) so rounds are generated programmatically, (3) remove
or reformat nested backticks so inline code blocks use single backticks only and
fenced examples use triple backticks consistently, (4) correct indentation and
list formatting under "Repository Standards" so items are top-level bullets (no
extra leading spaces) and (5) reconcile the NEVER/ALWAYS constraint sections so
each rule is a separate bullet under the correct heading and follows the same
markdown list style; update the template instances in this file (markers: the
YAML name field, the Questions File Format block, the Examples with backticks,
the "Repository Standards" section heading, and the "NEVER"/"ALWAYS" constraint
lists) accordingly.
In `@prompts/SDD-1-iteration4.md`:
- Around line 1-365: The file is a duplicate of iteration3.md (same spec content
under name: SDD-1-generate-spec and heading "Generate Specification"); remove or
consolidate this duplicate by either deleting iteration4.md or replacing its
content with the intended unique changes for this iteration, update the metadata
(name/description/tags) if this iteration should differ, and ensure any
cross-reference to Step 5 / the proceed-gate remains correct in the retained
file (look for the top-level name: SDD-1-generate-spec and the "## Step 5: Spec
Generation" section to locate where to apply the fix).
In `@prompts/SDD-1-iteration5.md`:
- Around line 1-365: The file prompts/SDD-1-iteration5.md contains duplicate
content (identical to iteration3) as indicated by the review; remove or
consolidate this duplicate by either deleting prompts/SDD-1-iteration5.md or
merging any intentional differences into the canonical spec (the block with
"name: SDD-1-generate-spec" and the full spec workflow text), and ensure the
remaining spec file references the correct iteration number and unique sections
(e.g., "Step 5: Spec Generation", "Follow-Up Rounds") so there is only one
authoritative version; update any documentation or references that point to
iteration5 to use the canonical file to prevent future duplication.
In `@prompts/SDD-1-iteration6.md`:
- Around line 1-365: The file prompts/SDD-1-iteration6.md duplicates the content
of iteration3 (same spec text and the duplicate_comment marker); fix by either
removing this duplicate file or replacing its contents with iteration6-specific
updates and a clear changelog header, ensuring the marker SDD1️⃣ and Step 5
"Follow-Up Rounds" remain correct; remove the [duplicate_comment] tag or convert
it into a real review note, and confirm the spec filename and internal title
reflect the intended iteration (reference: iteration6.md, iteration3.md, SDD1️⃣,
and the [duplicate_comment] token).
In `@prompts/SDD-1-iteration7.md`:
- Around line 1-365: The file prompts/SDD-1-iteration7.md is a duplicate of
iteration3.md (same spec content and markers like SDD1️⃣); either delete
prompts/SDD-1-iteration7.md or replace its content with the intended unique
iteration changes — update the front-matter name/description and the spec body
so it differs from iteration3.md (or add a short note pointing to iteration3.md
as the canonical version), and ensure any references to the workflow marker
SDD1️⃣ remain correct and the file follows the same spec directory/filename
conventions used elsewhere.
---
Nitpick comments:
In `@prompts/SDD-1-iteration3.md`:
- Around line 1-365: The PR contains six identical iteration files (iteration1,
iteration3, iteration4, iteration5, iteration6, iteration7) which adds noise
instead of documenting prompt evolution; either remove the redundant iteration
files or replace each with the actual distinct state for that iteration so the
history is meaningful. Locate the duplicate files (e.g.,
prompts/SDD-1-iteration3.md and its siblings iteration1/4/5/6/7), and: if you
want a clean history, delete the unnecessary copies and keep a single canonical
file (or consolidate into one file plus a single changelog); otherwise, update
each iteration file to contain the real previous-version content reflecting
changes between iterations (question-heavy, context-first, refinements, etc.),
ensuring file names match their iteration number and the first lines include the
unique iteration marker and a short changelog entry. Ensure the final commit
removes or updates exactly those filenames to eliminate duplicate content.
Comment on lines
+1
to
+11
| --- | ||
| name: SDD-1-generate-spec | ||
| description: "Generate a Specification (Spec) for a feature with enhanced workflow guidance and scope validation" | ||
| tags: | ||
| - planning | ||
| - specification | ||
| arguments: [] | ||
| meta: | ||
| category: spec-development | ||
| allowed-tools: Glob, Grep, LS, Read, Edit, MultiEdit, Write, WebFetch, WebSearch | ||
| --- |
Contributor
There was a problem hiding this comment.
All iteration files share name: SDD-1-generate-spec — prompt name collision.
Every iteration file (iteration1 through iteration7) declares name: SDD-1-generate-spec in its frontmatter, identical to the canonical prompts/SDD-1-generate-spec.md. If the prompt runner resolves commands by name, loading all these files would create 7 ambiguous entries that silently shadow or override one another.
Consider either:
- Giving each iteration a distinct name (e.g.,
SDD-1-generate-spec-draft-v1), or - Moving the iteration files out of
prompts/entirely (e.g.,docs/prompt-history/).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 1 - 11, The frontmatter in each
iteration file reuses the same prompt identifier "name: SDD-1-generate-spec",
causing name collisions when the prompt runner loads prompts; update each
iteration file to use a unique name (e.g., change "name: SDD-1-generate-spec" to
"name: SDD-1-generate-spec-draft-vN" or similar) or move those iteration files
out of the prompts/ directory into a separate folder (e.g., docs/prompt-history)
so the prompt runner only sees the canonical "name: SDD-1-generate-spec" in
prompts/; apply this change to all iteration files (iteration1 through
iteration7) so the only prompt left in prompts/ with the canonical name is
prompts/SDD-1-generate-spec.md.
Comment on lines
+181
to
+205
| ```markdown | ||
| # [NN] Questions Round 1 - [Feature Name] | ||
|
|
||
| Please answer each question below (select one or more options, or add your own notes). Feel free to add additional context under any question. | ||
|
|
||
| ## 1. [Question Category/Topic] | ||
|
|
||
| [What specific aspect of the feature needs clarification?] | ||
|
|
||
| - [ ] (A) [Option description explaining what this choice means] | ||
| - [ ] (B) [Option description explaining what this choice means] | ||
| - [ ] (C) [Option description explaining what this choice means] | ||
| - [ ] (D) [Option description explaining what this choice means] | ||
| - [ ] (E) Other (describe) | ||
|
|
||
| ## 2. [Another Question Category/Topic] | ||
|
|
||
| [What specific aspect of the feature needs clarification?] | ||
|
|
||
| - [ ] (A) [Option description explaining what this choice means] | ||
| - [ ] (B) [Option description explaining what this choice means] | ||
| - [ ] (C) [Option description explaining what this choice means] | ||
| - [ ] (D) [Option description explaining what this choice means] | ||
| - [ ] (E) Other (describe) | ||
| ``` |
Contributor
There was a problem hiding this comment.
Questions file title template hardcodes "Round 1" — should use [N].
Line 182 is # [NN] Questions Round 1 - [Feature Name], but this template is also used for follow-up rounds (round 2, 3…). The heading will always say "Round 1" even when generating a second or third round file.
🔧 Proposed fix
-# [NN] Questions Round 1 - [Feature Name]
+# [NN] Questions Round [N] - [Feature Name]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 181 - 205, The heading currently
hardcodes "Round 1" in the template string "# [NN] Questions Round 1 - [Feature
Name]"; update the template to use a round placeholder (e.g., "# [NN] Questions
[N] - [Feature Name]" or a variable like "[round]" / "{round}") so generated
files reflect the actual round number, and search for any other occurrences of
"Round 1" in the prompts file to replace with the same placeholder (refer to the
exact heading text "# [NN] Questions Round 1 - [Feature Name]" when locating the
change).
Comment on lines
+255
to
+272
|
|
||
| **Proof Artifacts:** | ||
| - [Artifact type]: [description] demonstrates [what it proves] | ||
| - Example: `Screenshot: `--help` output demonstrates new command exists` | ||
| - Example: `CLI: `command --flag` returns expected output demonstrates feature works` | ||
|
|
||
| ### [Unit 2]: [Title] | ||
|
|
||
| **Purpose:** [What this slice accomplishes and who it serves] | ||
|
|
||
| **Functional Requirements:** | ||
| - The system shall [requirement 1: clear, testable, unambiguous] | ||
| - The system shall [requirement 2: clear, testable, unambiguous] | ||
|
|
||
| **Proof Artifacts:** | ||
| - [Artifact type]: [description] demonstrates [what it proves] | ||
| - Example: `Test: MyFeature.test.ts passes demonstrates requirement implementation` | ||
| - Example: `Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality` |
Contributor
There was a problem hiding this comment.
Nested backticks in Proof Artifact examples produce broken Markdown code spans.
Lines like:
`Screenshot: `--help` output demonstrates new command exists`
will not render as a single code span. The Markdown parser closes the outer span at the first inner backtick (before --help), leaving the rest as raw text.
Use double-backtick delimiters for the outer span to allow inner backticks:
🔧 Proposed fix
-- Example: `Screenshot: `--help` output demonstrates new command exists`
-- Example: `CLI: `command --flag` returns expected output demonstrates feature works`
+- Example: ``Screenshot: `--help` output demonstrates new command exists``
+- Example: ``CLI: `command --flag` returns expected output demonstrates feature works``-- Example: `Test: MyFeature.test.ts passes demonstrates requirement implementation`
-- Example: `Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality`
+- Example: ``Test: MyFeature.test.ts passes demonstrates requirement implementation``
+- Example: ``Order PDF: PDF downloaded from https://example.com/order-submitted shows completed flow demonstrates end-to-end functionality``🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 255 - 272, The Proof Artifacts
examples contain nested backticks (e.g. the strings "`Screenshot: `--help`
output demonstrates new command exists`" and "`CLI: `command --flag` returns
expected output demonstrates feature works`") which break Markdown code spans;
update those examples in the Proof Artifacts section so the outer code spans use
double-backtick delimiters (e.g. ``Screenshot: `--help` output demonstrates new
command exists``) or convert them to fenced code blocks, ensuring inner
backticks remain literal and the examples render as single code spans.
Comment on lines
+286
to
+296
| ## Repository Standards | ||
|
|
||
| [Identify existing patterns and practices that implementation should follow. Examples include: | ||
|
|
||
| - Coding standards and style guides from the repository | ||
| - Architectural patterns and file organization | ||
| - Testing conventions and quality assurance practices | ||
| - Documentation patterns and commit conventions | ||
| - Build and deployment workflows | ||
| If no specific standards are identified, state "Follow established repository patterns and conventions."] | ||
|
|
Contributor
There was a problem hiding this comment.
Repository Standards fallback instruction renders as a bullet continuation.
The closing note If no specific standards are identified, state "Follow established repository patterns and conventions." is indented under the last list item (- Build and deployment workflows), so most Markdown renderers will treat it as part of that bullet rather than a standalone closing directive.
🔧 Proposed fix
- Build and deployment workflows
- If no specific standards are identified, state "Follow established repository patterns and conventions."]
+
+If no specific standards are identified, state "Follow established repository patterns and conventions."]🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@prompts/SDD-1-iteration3.md` around lines 286 - 296, The fallback directive
"If no specific standards are identified, state \"Follow established repository
patterns and conventions.\"" is currently indented under the list item "- Build
and deployment workflows" so it renders as part of that bullet; fix this by
unindenting that line in the "Repository Standards" section of
prompts/SDD-1-iteration3.md so the fallback becomes its own standalone paragraph
(remove the leading list indentation or preceding hyphen) and ensure it appears
exactly as the quoted sentence so renderers treat it as a separate directive.
Committed at iteration 3 content, will be updated to iteration 4 in working tree for IDE diff comparison. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why?
The SDD-1 workflow was asking too many clarifying questions — including ones that could be answered by reading the existing codebase. This created unnecessary friction, especially in mature projects with clear patterns, specs, and conventions already documented.
What Changed?
prompts/SDD-1-generate-spec.mdStep 2 (Context Assessment) is now framed as a primary research phase with explicit categories to investigate: existing specs, architecture patterns, testing standards, repository conventions, and related implementations. The goal is to gather everything needed upfront so fewer user questions are required.
Step 4 (Clarifying Questions → Identify Information Gaps) is restructured into a two-phase approach:
Progressive Disclosure guidance is updated: mature codebases with established patterns should target 0–5 questions; new codebases may need 8–12. The workflow can skip to spec generation entirely if all requirements are clear from context.
Questions File Process retains the follow-up rounds step — if answers reveal new questions, a new questions file is created with an incremented round number and the process repeats.
NEVER/ALWAYS rules updated to reinforce context-first behavior before asking any questions.
Additional Notes
These changes improve the experience for teams with well-established codebases where the existing specs, tests, and code structure already answer most implementation questions. The change does not reduce spec quality — it shifts the burden of answering questions from the user to the research phase.
tasks/0002-spec-open-source-ready.md)uv run pytestuv run pre-commit run --all-filesSummary by CodeRabbit