docs: enforce What/How separation in the SDD document architecture#120
Conversation
- **Create** specs/_shared/constants.md as the single source of truth for constants used by 2+ specs (22 constants extracted from 16 specs), eliminating duplicated definitions that drifted independently - **Record** 2 value conflicts (TASK_ROLES subset in spec 015, DEFAULT_SORT divergence between 010/006) and 4 same-value alias pairs as explicit reconciliation notes instead of silent inconsistency - **Define** usage rules: reference-only citation from specs, promotion threshold (used by 2+ specs), and version-bump propagation to referencing specs on any change Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- **Move** generation rules and the review/acceptance checklist into HTML comments so they guide /speckit.specify at generation time without landing in spec instances, cutting meta-instruction noise from every future spec - **Delete** the execution-status subsection because specs/STATUS.md is already the single source of pipeline state, removing a second copy that drifted - **Require** shared constants to be cited from specs/_shared/constants.md instead of redefined, and ban system-layer participants (API/Service/DB) in spec flow diagrams per the Flow Chart Ownership rule (system flow belongs in plan.md) - **Sync** the spec-format skill with the v1.6.0 section table, grandfather clause for the 16 existing specs, and two new common-error entries Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- **Add** a Decisions section (technical decisions + clarify resolutions, each with rationale and rejected alternatives) between Technical Context and Constitution Check, adapted from duty-mate's design.md pattern - **Route** /speckit.clarify resolutions into plan.md instead of the spec body so the spec stays What-only while decision history remains traceable - **Clarify** the split with ADRs: feature-scoped trade-offs live here; cross-feature decisions still open ADRs under docs/adr/ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- **Add** a HIGH-severity check for shared-constant duplication so specs that redefine constants from specs/_shared/constants.md fail the pre-PR gate instead of silently drifting - **Add** a MEDIUM-severity check for system-layer participants (API/Service/DB) in spec flow diagrams, enforcing the Flow Chart Ownership rule mechanically - **Add** a LOW-severity check for deprecated meta sections, grandfathered: only flags specs whose latest changelog entry is on or after 2026-07-21, so the 16 existing specs migrate lazily on their next version bump Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
This PR successfully implements What/How separation in the SDD document architecture. The changes are well-structured and correctly enforce the principle that spec.md instances contain only requirement content (What), while generation rules, review checklists, and technical decisions are moved to their proper locations.
Key improvements:
- Spec template v1.6.0 moves meta-instructions to HTML comments that don't appear in spec instances
- New
specs/_shared/constants.mdeliminates duplication of 22 constants across 16 specs - Plan template v1.15.0 adds a Decisions section for technical decisions and clarify resolutions
- Three new consistency checks added to speckit.analyze enforce the separation
- Grandfather clause allows existing specs to migrate lazily on their next version bump
All files are internally consistent, cross-references are correct, and the implementation aligns with the documented design. No blocking issues found.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the specification and planning templates, commands, and skills to enforce better separation of concerns, such as moving generation rules to comments, restricting flow diagrams to business-layer participants, and introducing a centralized shared constants file. The review feedback points out a logical contradiction with the DEFAULT_SORT constant in the new shared constants file, as its conflicting values across specs mean it should remain spec-specific to avoid triggering static analysis duplication errors.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
- **Remove** DEFAULT_SORT from the shared constants table and conflict notes because its value differs by context (010: updated_at desc, 006: created_at desc) — promoting it would force local overrides that trip the HIGH duplicate-definition check in /speckit.analyze - **Tighten** the promotion rule to require identical values (or alias/subset pending unification) across specs, so context-dependent constants stay spec-specific by definition - **Keep** a note documenting why DEFAULT_SORT was evaluated and rejected, preventing re-promotion later Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- **Resolve** the spec-template changelog conflict by keeping both entries: 1.6.0 (this branch) above 1.5.1 (PR #119 story-number stability rule, merged to main after this branch was cut) - **Verify** PR #119's story-number stability additions auto-merged intact into the v1.6.0 AC comment block and the spec-format skill Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
Purpose
Enforce What/How separation in the SDD document architecture so spec.md instances contain only requirement content (What), while generation rules, review checklists, and technical decisions live where they belong.
Reason
A comparison against duty-mate's OpenSpec architecture surfaced three structural problems in our 16 existing specs:
specs/STATUS.md.TASK_ROLESandMOBILE_BPare redefined in up to 16 specs and have already drifted (2 value conflicts, 4 same-value aliases found).Result
specs/_shared/constants.md(22 constants extracted from 16 specs, conflicts documented); specs must reference, not redefine/speckit.analyzegains 3 checks: shared-constant duplication (HIGH), system-layer participants in spec flow diagrams (MEDIUM), deprecated meta sections (LOW, grandfathered)Changed Files
specs/_shared/constants.md.specify/templates/spec-template.md.specify/templates/plan-template.md.claude/commands/speckit.analyze.md.claude/skills/spec-format/SKILL.mdTest Plan
MOBILE_BP767px,TASK_ROLESsubset in 015,PASSWORD_MIN_LENGTHin 003/005,ACTIVE_TASK_TYPE_STORAGE_KEYin 010/008/015)../../_shared/constants.mdresolves correctly fromspecs/[module]/NNN-feature/.claude/commands/content stays English; templates/specs content in Traditional Chinese (language boundary respected)Notes
checklist-template.mdCHK008/CHK018 still reference the removed§輸入與生成規則section name; fixing it here would exceed the 5-file PR limit, so it ships as a small follow-up PR (same pattern as docs: align spec 001 acceptance scenarios with blueprint-grade AC standard #118 → docs: define story-number stability and source-tag examples for AC IDs #119).prd-export.mdreferences the removed sections only in its export skip-list, which is a no-op when the sections are absent and still needed for grandfathered specs — intentionally unchanged.Impact Scope
Related
None
🤖 Generated with Claude Code