@ngocsangairvds/vsaf 4.1.24 → 4.1.26

package/skills/sdlc/ba-validate-srs/steps-v/step-v-03-completeness.md

@@ -0,0 +1,353 @@
+---
+# model: opus
+# findingsOutput: '{output_folder}/_validation_temp/findings-completeness.yaml'
+# contextFile: '{output_folder}/_validation_temp/context.yaml'
+# grepPatterns: '../data/grep-patterns-srs.yaml'
+---
+
+# Step V-03: Completeness — Kiểm tra tính đầy đủ
+
+---
+
+## 1. Section Existence Check (Grep-only)
+
+**Load context:** Read `{contextFile}` → get `srs_path`, `section_index`, `uc_cache`.
+**Load patterns:** Read `{grepPatterns}` → get `srs_structure` pattern group.
+
+**Use `section_index` from context.yaml first** (already built — no SRS read needed):
+- Check each required section against the section_index titles
+- If section_index is unavailable, run Grep using `srs_structure` patterns against `srs_path`
+
+> **Template note (2026-04):** ERD section và Sequence Diagrams đã bị xóa khỏi template. API/DB/Kafka specs chuyển sang TSD. Template mới focus vào screen control tables + Activity Diagrams + Figma mapping + Gap Analysis. Không check `has_erd` và `has_uc_sequence` nữa.
+
+Check presence of each item and record score:
+
+| Item ID | Check | Pattern/Section | Score |
+|---|---|---|---|
+| has_overview | Section 1 "Mô tả chung" | section_overview | |
+| has_use_case_summary | Bảng 1.1 UC Summary | section_uc_summary | |
+| has_glossary | Section 1.2 Glossary | section_glossary | |
+| has_references | Section 1.3 References | section_references | |
+| has_uc_screens | Each UC có mục Màn hình (2.X.1) | section_uc_screens OR uc_cache | |
+| has_screen_control_table | Each UC có bảng control (cột STT / Tên control / Loại control) | grep "Tên control\|Loại control" | |
+| has_activity_diagram_per_uc | Each UC có Activity Diagram (@startuml block trong 2.X.2) | grep "@startuml UC-\|@startuml.*Activity" | |
+| has_uc_flow_table | Each UC có bảng luồng (cột Bước / Đối tượng / Mô tả) | section_uc_flow_table OR uc_cache | |
+| has_figma_mapping | Section 2 có bảng Figma mapping HOẶC explicit "chưa có Figma" / "Không có Figma" note | grep "Figma.*node\|chưa có Figma\|Không có Figma" | |
+| has_error_codes | Section 3 "Danh sách mã lỗi đối tác trả về" | section_error_codes | |
+| has_impact | Section 4 "Chức năng ảnh hưởng" | section_impact | |
+| has_dependency_map | Section 4 có Dependency Map (@startuml component diagram) | grep "@startuml" within section 4 range | |
+| has_business_rules | Section 5 Business Rules | section_business_rules | |
+| has_nfrs | Section 6 Yêu cầu phi chức năng | section_nfr | |
+| has_dependencies | Section 7 Ràng buộc / Giả định / Phụ thuộc | section_dependencies | |
+| has_gap_analysis | Section 7.4 hoặc Section 9 có Gap Analysis table (cột Gap ID) | grep "Gap ID\|GA-[A-Z]" | |
+| has_state_diagrams | Section 8 State Diagrams hoặc "Không áp dụng" note | section_state_diagrams | |
+| has_traceability | Section 9 Mini-RTM | section_traceability | |
+| has_edge_cases | "Luồng ngoại lệ" hoặc "EX" flows có mặt trong các UC | exception_flow pattern | |
+| has_acceptance_criteria | Acceptance Criteria section | acceptance_criteria pattern | |
+| has_open_questions_footer | Doc có "Các điểm cần Business confirm" footer | grep "cần Business confirm\|cần confirm" | |
+
+Score: 1.0=present, 0.0=missing. Items "not applicable" (e.g., state diagrams cho FR không có entity lifecycle, Figma mapping cho backend-only FR) = skip from denominator.
+
+Severity defaults khi thiếu:
+- `has_screen_control_table`, `has_activity_diagram_per_uc` → MEDIUM
+- `has_figma_mapping`, `has_dependency_map`, `has_gap_analysis` → MEDIUM
+- `has_open_questions_footer` → LOW
+
+---
+
+## 2. Semantic completeness checks (LLM analysis)
+
+Ngoài section existence, kiểm tra **nội dung** có đầy đủ:
+
+### 2.1 UC coverage
+- Đếm số UC trong bảng tóm tắt (1.1)
+- Đếm số UC có section đặc tả chi tiết (2.X)
+- Nếu thiếu UC spec → finding CRITICAL
+
+### 2.2 Flow completeness
+- Mỗi UC có: Precondition, Main flow, Alternative flow, Exception flow, Postcondition?
+- Nếu chỉ có Main flow → CRITICAL
+- Nếu thiếu Exception flow → HIGH
+
+### 2.3 Cross-reference coverage (nếu có PRD)
+- Đối chiếu FRs trong PRD với UCs trong SRS
+- FR nào trong PRD chưa có UC tương ứng? → HIGH
+
+### 2.4 Entity coverage
+- Entities mention trong flow tables có trong ERD section 3 không?
+- Entities trong ERD có mô tả trong bảng 3.2 không?
+
+### 2.5 Downstream event consumer coverage
+- Với mỗi event được publish trong flow (VD: `PaymentCompletedEvent`, `PolicyIssuedEvent`):
+  - Có mô tả service nào consume event này không?
+  - Có mô tả side effects quan trọng của downstream consumer không?
+  - VD: payment SRS publish `PaymentCompletedEvent` nhưng không mô tả promotion-service consume event này để redeem voucher → thiếu side effect quan trọng
+- Nếu downstream consumer quan trọng bị thiếu → HIGH
+
+Item ID: `downstream_event_consumers`
+
+### 2.6 Cancellation sub-flow by context
+- Nếu feature có cooling-off period: có nhánh huỷ riêng cho trong-cooling-off vs ngoài-cooling-off?
+  - Trong cooling-off: hoàn 100%, không bắt buộc lý do
+  - Ngoài cooling-off: pro-rata, bắt buộc lý do
+- Nếu chỉ có 1 luồng huỷ duy nhất → HIGH
+- Cũng kiểm tra: khi có refund, ngày tính pro-rata có được xác định rõ không?
+  - VD: tính từ ngày KH yêu cầu hay ngày insurer confirm? → Nếu không rõ → MEDIUM
+
+Item ID: `cancellation_subflows_by_context`
+
+### 2.7 PRD Acceptance Criteria coverage (via KG)
+
+**Token-efficient:** Read PRD entity → find AC section line range → targeted read.
+
+1. From KG fr-to-docs index: find PRD sections for this FR
+2. Targeted read of PRD acceptance criteria for this FR
+3. For each PRD acceptance criterion:
+   - Is there a corresponding SRS UC or AC that covers it?
+   - Map: PRD AC → SRS UC/AC
+4. Finding: any PRD AC not covered → HIGH severity
+
+Item ID: `prd_ac_coverage`
+
+### 2.8 Derived-from Traceability — Two-Pass Invention Detection (CRITICAL)
+
+**This is an Opus-level check. Two passes prevent false negatives.**
+
+#### Pass 1 — Haiku extraction (exhaustive ID listing)
+
+Run Grep to extract ALL formally defined SRS artifacts:
+
+1. Grep `UC-[A-Z]{2,4}-\d{2}` in `srs_path` → extract unique UC IDs (e.g., UC-FR8-01)
+2. Grep `BR-[A-Z]{2,4}-\d{3}|BR-\d{3}` in `srs_path` → extract unique BR IDs
+3. Grep `NFR-|constraint:|Ràng buộc:` in `srs_path` → extract unique NFR/constraint IDs
+4. Result: `extracted_uc_ids`, `extracted_br_ids`, `extracted_constraint_ids`
+
+#### Pass 2 — Opus semantic judgment (traceability per extracted item)
+
+Using KG pre-loaded data from `context.yaml` (`kg.prd_key_sections`, `kg.brd_key_sections`, `kg.fr_to_docs`):
+
+For EACH UC ID in `extracted_uc_ids`:
+- Can this UC's PURPOSE trace to a PRD FR or BRD requirement? (decomposition is OK — 1 PRD FR → many UCs)
+- If NOT traceable → **CRITICAL: "Invented requirement — {UC_ID} has no upstream source in PRD/BRD"**
+- Use targeted PRD/BRD reads via line ranges from context.yaml `kg` section
+
+For EACH BR ID in `extracted_br_ids`:
+- Is this BR derivable from BRD business rules or PRD acceptance criteria?
+- If NOT traceable → **HIGH: "Untraceable business rule — {BR_ID} not found in BRD/PRD"**
+
+For EACH constraint in `extracted_constraint_ids`:
+- Is this from Architecture decisions or PRD NFR section?
+- If NOT traceable → **MEDIUM: "Added constraint — not in Architecture/PRD"**
+
+**Zero-miss guarantee:** Pass 1 (Grep) ensures every UC/BR is captured before Pass 2 (Opus) judges traceability. No LLM scanning of raw SRS text.
+
+Item ID: `derived_from_traceability`
+
+### 2.9 Role & Permission per UC
+
+Kiểm tra mỗi UC có định nghĩa rõ role/permission không — riêng biệt với RBAC NFR ở V-06:
+
+- Mỗi UC table có cột Actor hoặc ghi rõ actor role trong precondition không?
+- Nếu có nhiều role có thể trigger cùng UC (VD: Admin vs Customer), có sub-flow riêng hoặc note rõ sự khác biệt không?
+- Các action nhạy cảm (approve, cancel, refund, config) có ghi rõ role nào được phép không?
+- Nếu SRS có Section 6 Business Rules hoặc bảng actor riêng, danh sách role có đầy đủ với thực tế không?
+
+**Không yêu cầu bảng RACI đầy đủ.** Chỉ cần: mỗi UC không bị "ambiguous actor" — người đọc biết ngay ai có quyền trigger/thực hiện.
+
+**Scoring:**
+- Tất cả UC có actor rõ, role nhạy cảm đều có permission note → 1.0
+- Phần lớn UC rõ, 1-2 action nhạy cảm thiếu permission boundary → 0.75
+- Nhiều UC chỉ ghi "User" hoặc "System" không phân biệt role → 0.5
+- Không có role/actor định nghĩa trong UC nào → 0.0 (CRITICAL)
+
+Item ID: `role_permission_per_uc`
+
+---
+
+### 2.10 Input / Output / Validation Coverage per UC
+
+Kiểm tra mỗi UC có mô tả đầy đủ input, output, và validation rules không.
+
+> **Template note (2026-04):** Template mới embed validation trực tiếp vào cột Mô tả của screen control table (`**Validate:** • ...` inline), không còn separate input spec table. API request/response specs chuyển sang TSD.
+
+**Input (screen control tables — Section 2.X.1):**
+- Mỗi UC có màn hình → có bảng control với các cột: STT, Tên control, Loại control, Require, Maxlength, Giá trị mặc định, Mô tả
+- Mỗi input control quan trọng (Text Input, Checkbox, Dropdown) có ghi Require (Bắt buộc/Tùy chọn)?
+- Maxlength có điền cho Text Input không?
+
+**Validation (inline trong cột Mô tả):**
+- Có `**Validate:**` keyword trong Mô tả của các input controls không?
+- Validation messages có tham chiếu đến Error Code trong Section 3 không?
+
+**Output (flow table — Section 2.X.2):**
+- Bảng luồng nghiệp vụ có mô tả kết quả sau khi UC thành công không?
+- Cột "Bảng/Thực thể liên quan" có ghi entity nào bị tạo/cập nhật không?
+
+**Scoring:**
+- Screen control table đầy đủ + `**Validate:**` inline + error code reference → 1.0
+- Có screen control table nhưng thiếu validate messages → 0.75
+- Chỉ có flow table, không có screen control table (cho UC có màn hình) → 0.5
+- Không có screen control table lẫn validate messages → 0.25 (HIGH)
+- UC không có màn hình (backend-only) → skip item
+
+Item ID: `input_output_validation_coverage`
+
+---
+
+### 2.11 Loop / Backward Flow Coverage
+
+Kiểm tra các luồng có thể lặp lại hoặc quay lui mà SRS chưa xử lý:
+
+**Loop flows (lặp lại trong cùng session):**
+- User re-submit sau khi sửa lỗi (VD: form validation fail → sửa → submit lại)?
+- User reload / refresh giữa chừng — state có được preserve không?
+- Retry action sau timeout — có idempotency concern không?
+
+**Backward flows (quay lui bước trước):**
+- User bấm "Quay lại" từ bước N về bước N-1 — data có bị mất không?
+- Checkout wizard: quay lại step 2 từ step 3 → có ảnh hưởng gì đến đơn đang tạo không?
+- Multi-step process: nếu step giữa fail, có cần rollback toàn bộ hay partial?
+
+**Dấu hiệu cần flag:**
+- Flow chỉ có "happy path thẳng" mà không có nhánh cho re-try / back-navigation
+- Business rule áp dụng tại step N phụ thuộc data step N-1, nhưng không có guard khi backward
+
+**Scoring:**
+- Tất cả loop/backward scenarios có explicit handling → 1.0
+- Có note "user có thể quay lại" nhưng không mô tả data impact → 0.75
+- Flow chỉ one-way, không đề cập loop/backward dù UC có multi-step → 0.5
+- Wizard / multi-step hoàn toàn thiếu backward handling → 0.25 (HIGH)
+- Không applicable (UC single-step) → skip
+
+Item ID: `loop_backward_flow_handled`
+
+---
+
+### 2.12 Figma screen coverage (via figma-cache manifests)
+
+1. Read Figma design references for screens mapping to this FR:
+   - Use Figma MCP tools if available → filter screens matching this feature's FR ID
+2. Read SRS screen mapping section (Mapping Figma ↔ SRS Screens table)
+3. Cross-check:
+   - Every SRS screen (SCR-XX-XX) has a mapped Figma page/node? → check manifest
+   - Every Figma manifest screen for this FR has a corresponding SRS screen? → orphan design check
+4. Finding: SRS screen without Figma design → MEDIUM; Figma screen without SRS → LOW (informational)
+
+Item ID: `figma_screen_coverage`
+
+---
+
+## 3. Ghi findings
+
+Với mỗi finding, ghi theo format:
+
+```markdown
+| # | Severity | Dimension | File | Item ID | Score | Evidence | Suggestion | Business Impact | Source |
+```
+
+Each finding MUST include `business_impact` with three sub-fields:
+- **WHO**: Primary stakeholder affected (Dev, QA, PO, Ops, Customer)
+- **WHAT**: Impact type (Blocked, Rework risk, UX degradation, Compliance risk)
+- **WHEN**: When impact materializes (Before Sprint, During Sprint, After Release)
+```
+
+- Source = `auto` cho section checks, `llm` cho semantic analysis
+- Score: 1.0 / 0.75 / 0.5 / 0.25 / 0.0
+
+---
+
+## 4. Tính Completeness dimension score
+
+```
+completeness_score = round(sum(item_scores.values()) / 29 × 100, 1)
+```
+
+Canonical item IDs (N = 29, fixed — excludes meta fields `uc_count`, `invented_requirements`):
+`has_overview`, `has_use_case_summary`, `has_glossary`, `has_references`, `has_uc_screens`, `has_screen_control_table`, `has_activity_diagram_per_uc`, `has_uc_flow_table`, `has_figma_mapping`, `has_error_codes`, `has_impact`, `has_dependency_map`, `has_business_rules`, `has_nfrs`, `has_dependencies`, `has_gap_analysis`, `has_state_diagrams`, `has_traceability`, `has_edge_cases`, `has_acceptance_criteria`, `has_open_questions_footer`, `prd_ac_coverage`, `derived_from_traceability`, `role_permission_per_uc`, `input_output_validation_coverage`, `loop_backward_flow_handled`, `figma_screen_coverage`, `downstream_event_consumers`, `cancellation_subflows_by_context`
+
+⚠️ MANDATORY: N = 29 (fixed). N/A items → score = 1.0 (do not skip from denominator). No post-hoc calibration. dimension_score in YAML = formula result only.
+
+Ghi nhận: `completeness_score = X%`, status = OK/WARN/FAIL
+
+---
+
+## 5. Append findings vào report
+
+Append tất cả CRITICAL/HIGH findings vào section "4. Critical & High Findings" của report file.
+Append MEDIUM/LOW findings vào section "5. Medium & Low Findings".
+
+Update frontmatter: thêm `step-v-03-completeness` vào `stepsCompleted`.
+
+---
+
+## [NEW] Write Structured Findings
+
+Write file `{findingsOutput}`:
+```yaml
+# findings-completeness.yaml — generated by step-v-03
+# model: opus | weight: 1.0
+
+dimension: completeness
+weight: 1.0
+dimension_score: 0   # = round(sum(item_scores.values()) / 29 × 100, 1)
+status: OK  # OK | WARN | FAIL
+findings: []
+summary:
+  total: 0
+  critical: 0
+  high: 0
+  medium: 0
+  low: 0
+item_scores:
+  has_overview: 0.0
+  has_use_case_summary: 0.0
+  has_glossary: 0.0
+  has_references: 0.0
+  has_uc_screens: 0.0
+  has_screen_control_table: 0.0      # NEW — screen control table per UC
+  has_activity_diagram_per_uc: 0.0   # NEW — Activity Diagram per UC (replaces has_uc_sequence)
+  has_uc_flow_table: 0.0
+  has_figma_mapping: 0.0             # NEW — Figma mapping or explicit N/A note
+  has_error_codes: 0.0               # Section 3 (was Section 4)
+  has_impact: 0.0                    # Section 4 (was Section 5)
+  has_dependency_map: 0.0            # NEW — Dependency Map plantuml in Section 4
+  has_business_rules: 0.0            # Section 5 (was Section 6)
+  has_nfrs: 0.0                      # Section 6 (was Section 7)
+  has_dependencies: 0.0              # Section 7 (was Section 8)
+  has_gap_analysis: 0.0              # NEW — Gap Analysis table in Section 7.4 or Section 9
+  has_state_diagrams: 0.0            # Section 8 (was Section 9)
+  has_traceability: 0.0              # Section 9 (was Section 10)
+  has_edge_cases: 0.0
+  has_acceptance_criteria: 0.0
+  has_open_questions_footer: 0.0     # NEW — "Các điểm cần Business confirm" footer
+  prd_ac_coverage: 0.0
+  derived_from_traceability: 0.0
+  role_permission_per_uc: 0.0
+  input_output_validation_coverage: 0.0
+  loop_backward_flow_handled: 0.0
+  figma_screen_coverage: 0.0
+  downstream_event_consumers: 0.0
+  cancellation_subflows_by_context: 0.0
+  uc_count: 0
+  invented_requirements: []    # list of UC/BR IDs flagged as invented
+```
+
+---
+
+## 6. Menu
+
+```
+Completeness Score: {X}% ({status})
+- CRITICAL: {count}
+- HIGH: {count}
+- MEDIUM: {count}
+- LOW: {count}
+
+[C] Continue — Sang Consistency (Step V-04)
+[D] Detail — Xem chi tiết findings
+[X] Cancel
+```
+
+**Chờ user chọn.**
+
+Khi user chọn **C**: đọc fully và follow `./step-v-04-consistency.md`