chore: Phase 2 - Requirements Checklist Foundational Framework

.github/specs/010-requirements-checklist/checklists/requirements.md

@@ -144,3 +144,15 @@ This specification is ready for:
 - Edge cases identified and documented
 - Scope boundaries clear and realistic
 - Framework design aligns with LightSpeed `.github` repository constitution (Specification-First Process)
+
+## Clarifications Applied (2026-09-17)
+
+**Session completed**: 5 critical ambiguities resolved via `/speckit-clarify`:
+
+1. **Dimension Scoring**: Weighted item-count approach (passed ÷ total × 100%), ≥75% threshold
+2. **Item Count Ranges**: Target ranges per variant (Author 45–55, Peer 45–55, Stakeholder 20–30, Integration 25–35)
+3. **Variant Selection**: Smart system recommendation with user override; concurrent variants allowed
+4. **Conflict Resolution**: Documented dissent approach; both scores recorded, stricter score used for gate decision
+5. **MVP Scope**: PR review gate integration only; pre-commit and async stakeholder sign-off deferred to post-launch
+
+**Impact**: All clarifications make requirements MORE concrete, unambiguous, and testable. No checklist items negatively impacted; all remain passing. Specification enhanced for planning phase readiness.

.github/specs/010-requirements-checklist/spec.md

@@ -14,11 +14,21 @@ The Requirements Quality Checklist Framework is a structured set of quality gate
 
 The framework addresses the gap between "I wrote requirements" and "these requirements are ready to build"—reducing rework, preventing scope creep, and improving team alignment.
 
+## Clarifications
+
+### Session 2026-09-17
+
+- Q: How should each of the 8 quality dimensions be scored and measured? → A: Each dimension uses a weighted item-count approach: (passed items ÷ total applicable items) × 100%, with ≥75% threshold for dimension pass.
+- Q: Should checklist item counts be fixed targets or acceptable ranges? → A: Target ranges for each variant allow implementation flexibility while maintaining scope control (Author 45–55, Peer 45–55, Stakeholder 20–30, Integration 25–35).
+- Q: How should users determine which variant to use, and can specs use multiple variants simultaneously? → A: Smart variant selection system recommends a variant based on spec metadata (author/peer/stakeholder/integration context) with user override capability; allows concurrent variants for multi-party review scenarios.
+- Q: When a reviewer or stakeholder disagrees on whether a checklist item passes, what's the resolution path? → A: Documented dissent approach: both scores recorded separately, results show both perspectives, final gate decision uses stricter score (most conservative), promoting transparency and preventing false consensus.
+- Q: Which integration patterns are required for MVP launch? → A: PR review gate only for MVP (aligns with P1 peer workflow, provides immediate GitHub value). Pre-commit check and async stakeholder sign-off deferred to post-launch roadmap phases.
+
 ## User Scenarios & Testing *(mandatory)*
 
 ### User Story 1 - Author Pre-Review: Self-Validate Before Peer Review (Priority: P1)
 
-A requirements author completes a specification and wants to validate it before sending to peer review. They need a structured checklist they can run through in ~30 minutes that catches common quality gaps (ambiguous success criteria, missing acceptance scenarios, inconsistent terminology) so they can fix issues before the formal review cycle.
+A requirements author completes a specification and wants to validate it before sending to peer review. They need a structured checklist they can run through in 25–35 minutes that catches common quality gaps (ambiguous success criteria, missing acceptance scenarios, inconsistent terminology) so they can fix issues before the formal review cycle.
 
 **Why this priority**: Prevents peer reviewers from spending time on fixable gaps. Reduces review cycles and accelerates time-to-implementation. P1 because it's the entry point for all requirements into the quality process.
 
@@ -34,7 +44,7 @@ A requirements author completes a specification and wants to validate it before
 
 ### User Story 2 - Peer Review Gate: Structured Review Coordination (Priority: P1)
 
-A peer reviewer receives a spec marked for review. Instead of ad-hoc comments, they follow a structured checklist that ensures consistent evaluation across 8 quality dimensions. The checklist provides both quantitative metrics (% completeness, coverage scores) and qualitative guidance (e.g., "Do success criteria link to measurable business outcomes?") so reviewers catch issues systematically in ~45 minutes.
+A peer reviewer receives a spec marked for review. Instead of ad-hoc comments, they follow a structured checklist that ensures consistent evaluation across 8 quality dimensions. The checklist provides both quantitative metrics (% completeness, coverage scores) and qualitative guidance (e.g., "Do success criteria link to measurable business outcomes?") so reviewers catch issues systematically in 40–50 minutes.
 
 **Why this priority**: Standardises review quality. Prevents reviewers from missing dimensions. Reduces review-to-rework cycles. P1 because it's the quality gate before stakeholder approval.
 
@@ -50,7 +60,7 @@ A peer reviewer receives a spec marked for review. Instead of ad-hoc comments, t
 
 ### User Story 3 - Stakeholder Gate: Business Alignment Validation (Priority: P1)
 
-A stakeholder or product manager needs to verify that a specification meets business requirements and is ready for commitment before handoff to implementation. They need a lightweight checklist (~15 minutes) that validates business-critical dimensions (completeness, scenario coverage, dependencies) without requiring technical depth. The checklist helps them identify scope creep, missing user journeys, or unresolved dependencies before signing off.
+A stakeholder or product manager needs to verify that a specification meets business requirements and is ready for commitment before handoff to implementation. They need a lightweight checklist (10–20 minutes) that validates business-critical dimensions (completeness, scenario coverage, dependencies) without requiring technical depth. The checklist helps them identify scope creep, missing user journeys, or unresolved dependencies before signing off.
 
 **Why this priority**: Prevents misalignment between business intent and implementation scope. Catches scope creep before it reaches code. P1 because stakeholder sign-off gates release.
 
@@ -66,7 +76,7 @@ A stakeholder or product manager needs to verify that a specification meets busi
 
 ### User Story 4 - Cross-Project Integration: Dependency Validation (Priority: P2)
 
-A technical lead on Project A needs to verify that a specification from Project B (which Project A depends on) meets Project A's requirements and won't create integration friction. They use a checklist focused on dependencies, interfaces, and cross-project contracts to validate alignment in ~20 minutes without needing full technical review. This prevents integration surprises and clarifies assumptions across project boundaries.
+A technical lead on Project A needs to verify that a specification from Project B (which Project A depends on) meets Project A's requirements and won't create integration friction. They use a checklist focused on dependencies, interfaces, and cross-project contracts to validate alignment in 15–25 minutes without needing full technical review. This prevents integration surprises and clarifies assumptions across project boundaries.
 
 **Why this priority**: Reduces integration rework and coordination overhead. P2 because it's used less frequently than author/peer/stakeholder reviews but is critical when cross-project dependencies exist.
 
@@ -84,26 +94,26 @@ A technical lead on Project A needs to verify that a specification from Project
 
 - What happens when a specification spans multiple complex domains (e.g., payment processing + analytics + compliance)? How does the checklist guide prioritisation of quality dimensions?
 - How does the checklist handle specifications with intentional flexibility or open requirements (e.g., "explore options for X" vs. defined requirements)?
-- What if a reviewer or stakeholder disagrees on whether a checklist item passes? Is there conflict resolution guidance or escalation?
+- **Disagreement on Item Pass/Fail**: When a reviewer and stakeholder disagree, both scores are recorded separately. Results show both perspectives without forcing consensus. Final gate decision (pass/fail) uses the stricter (more conservative) score. All dissenting viewpoints are documented in the results for audit and learning purposes.
 
 ## Requirements *(mandatory)*
 
 ### Functional Requirements
 
 - **FR-001**: System MUST provide 8 distinct quality dimensions (Completeness, Clarity, Consistency, Measurability, Scenario Coverage, Edge Cases, Dependencies, Ambiguities) with clear definition and measurable checkpoints for each
 - **FR-002**: System MUST generate a base checklist with 40+ items covering the 8 dimensions, structured as testable yes/no or scoring questions
-- **FR-003**: System MUST support 4 audience-specific checklist variants (Author Pre-Review ~50 items, Peer Review ~50 items, Stakeholder Gate ~25 items, Cross-Project Integration ~30 items) with tailored language and focus per audience
-- **FR-004**: System MUST allow specifications to be run against a checklist and produce a results document with pass/fail status per dimension, dimension scores (0-100%), and specific findings by checklist item
+- **FR-003**: System MUST support 4 audience-specific checklist variants with target item ranges and tailored language per audience: Author Pre-Review (45–55 items), Peer Review (45–55 items), Stakeholder Gate (20–30 items), Cross-Project Integration (25–35 items). System MUST recommend a variant based on spec metadata and workflow context, with user ability to override and run multiple variants concurrently
+- **FR-004**: System MUST allow specifications to be run against a checklist and produce a results document with pass/fail status per dimension (calculated as: passed items ÷ total applicable items × 100%; dimension passes if ≥75%), dimension scores (0-100%), and specific findings by checklist item. When multiple reviewers evaluate the same checklist, results MUST record individual scores separately and display the stricter (most conservative) score for gate decisions
 - **FR-005**: System MUST provide reference examples and clarification guidance for ambiguous checklist items (e.g., "What counts as 'measurable'?" with examples of good vs. poor criteria)
 - **FR-006**: System MUST support extension of the base checklist with project-specific quality rules (e.g., "All security specs MUST address [specific threat model]") without modifying the core framework
-- **FR-007**: System MUST enable integration with specification workflows (e.g., as a pre-commit check, as an automated PR review gate, as an async stakeholder sign-off tool)
+- **FR-007** (MVP): System MUST enable integration with GitHub PR review workflows as an automated PR gate for peer review (MVP scope). Future integrations (pre-commit check, async stakeholder sign-off tool) are deferred to post-launch roadmap
 - **FR-008**: System MUST track checklist results over time (e.g., which dimensions improved across iterations, which specs had the most rework cycles)
 
 ### Key Entities
 
 - **ChecklistTemplate**: Defines a named checklist variant (Author Pre-Review, Peer Review, Stakeholder Gate, Cross-Project Integration) with audience, time estimate, and set of checklist items
 - **ChecklistItem**: Individual quality checkpoint with dimension assignment, audience applicability, pass criteria, and reference examples
-- **ChecklistDimension**: One of the 8 quality dimensions (Completeness, Clarity, Consistency, Measurability, Scenario Coverage, Edge Cases, Dependencies, Ambiguities) with definition and success threshold
+- **ChecklistDimension**: One of the 8 quality dimensions (Completeness, Clarity, Consistency, Measurability, Scenario Coverage, Edge Cases, Dependencies, Ambiguities) with definition, success threshold (≥75% of applicable items must pass), and related checklist items
 - **ChecklistResult**: Output from running a checklist on a specification, including dimension scores, item-level pass/fail, findings, and recommendations
 - **SpecificationReference**: Metadata linking a result to a specification (path, version, author) for tracking and trend analysis
 
@@ -129,6 +139,7 @@ A technical lead on Project A needs to verify that a specification from Project
 - **Baseline comparison**: Success metrics assume a control baseline of specs written without the checklist framework; internal pilot will establish baseline before full rollout
 - **Scalability**: Checklist is designed for specifications ranging from 5-page features to 50-page systems; very large architectural specs (100+ pages) may require decomposition into sub-specs
 - **No real-time collaboration**: Checklist is asynchronous (author completes it, sends results to reviewer); real-time collaborative review is out of scope for MVP
+- **MVP scope**: PR review gate integration only. Pre-commit check integration and async stakeholder sign-off tool are post-launch roadmap items. Framework core and manual usage available in MVP
 - **Dependencies**: Assumes specifications follow a standard structure (user stories, functional requirements, success criteria, assumptions) as defined in CLAUDE.md specification standards
 
 ## References