@ngocsangairvds/vsaf 4.1.24 → 4.1.26

package/skills/sdlc/ba-validate-srs/data/srs-review-glossary.md

@@ -0,0 +1,237 @@
+# SRS Review — Glossary & Mô tả
+
+---
+
+## 1. REVIEW DIMENSIONS — Các chiều đánh giá
+
+| Dimension | Mô tả | Weight |
+|---|---|---|
+| Completeness | Kiểm tra tính đầy đủ: có Overview, Use Cases, AC, NFRs, ERD, Business Rules, Error Codes, Dependencies, Traceability không? | 1.0 |
+| Consistency | Kiểm tra tính nhất quán giữa các file: entity naming, UC ID prefix, state machine, data model, API patterns, terminology. | 1.0 |
+| Quality | Kiểm tra chất lượng viết: ngôn ngữ mơ hồ (TBD, có thể), testability, AC format, duplicate requirements, scope clarity. | 1.0 |
+| Readiness | Đánh giá mức độ sẵn sàng implement: API contracts, DB schema, error codes, state machines, integration specs, tech stack. | 1.0 |
+| Risk | Đánh giá rủi ro kinh doanh: flow completeness (create→delete), external dependencies, integration gaps, scope creep, assumptions. | 0.8 |
+| User Impact | Đánh giá tác động người dùng: persona coverage, journey completeness, error UX, onboarding, accessibility. | 0.7 |
+
+---
+
+## 2. SEVERITY LEVELS — Mức độ nghiêm trọng
+
+| Severity | Mô tả | Hành động |
+|---|---|---|
+| CRITICAL | Block implementation — dev không thể implement mà không có câu trả lời hoặc spec bổ sung. | Phải sửa TRƯỚC khi bắt đầu Sprint |
+| HIGH | Nên clarify sớm — có thể implement nhưng risk rework hoặc bugs. | Nên sửa trong Sprint 1 |
+| MEDIUM | Nice to fix — không block nhưng improve quality, UX, maintainability. | Phân bổ vào Sprint 2 |
+| LOW | Minor — pass hoặc cải thiện nhỏ. | Fix khi có thời gian |
+
+---
+
+## 3. QUESTION CATEGORIES — Phân loại câu hỏi
+
+| Category | Mô tả | Ví dụ |
+|---|---|---|
+| flow-gap | Thiếu luồng xử lý đối xứng/bổ sung (có create nhưng thiếu delete/cancel/refund). | Payment có create nhưng thiếu refund. Policy có cancel nhưng thiếu reinstate. |
+| ambiguity | Requirement mơ hồ, cần PO/stakeholder quyết định. | Figma cho skip CCCD, SRS yêu cầu bắt buộc — chọn cái nào? |
+| cross-doc-conflict | Mâu thuẫn giữa PRD/System spec/SRS feature files. | System spec dùng UC-IP cho FR-8, SRS FR-8 dùng UC-PU. |
+| domain-inference | Từ domain knowledge, thiếu flow thường gặp trong ngành bảo hiểm. | Grace period: claims allowed hay không? Endorsement reject: resubmit được không? |
+| missing-spec | Flow/entity đề cập nhưng thiếu spec chi tiết để implement. | Kafka events mention xuyên suốt nhưng không có payload schema. |
+
+---
+
+## 4. ITEM IDs — Mã định danh findings
+
+| Pattern | Mô tả | Ví dụ |
+|---|---|---|
+| has_* | Auto-check: kiểm tra section/content tồn tại trong document. | has_overview, has_nfrs, has_traceability, has_dependencies |
+| no_ambiguous_language | Auto-check: tìm từ mơ hồ (TBD, should, có thể, etc.). | Tìm thấy 15 ambiguous terms trong prd.md |
+| entity_naming | Auto-check: entity naming consistency across files. | entity_naming — kiểm tra cùng concept dùng cùng tên |
+| deployment_requirements | Auto-check: có section Deployment/Infrastructure không. | Không tìm thấy section Deployment trong PRD |
+| dependency_risk | Auto-check: external dependencies documented. | Không có section Dependencies/Third-party |
+| acceptance_criteria_format | Auto-check: AC theo format Given/When/Then. | AC không có GWT format |
+| clear_scope | Auto-check: có section phạm vi/ngoài phạm vi. | Không có section In-scope/Out-of-scope |
+| no_duplicate_requirements | Auto-check: requirements trùng lặp giữa các file. | Consent spec overlap giữa FR-1 và FR-15 |
+| api_contracts_defined | LLM-check: API contracts đầy đủ request/response schema. | Endpoints listed nhưng thiếu JSON schema |
+| api_naming_pattern | LLM-check: API prefix nhất quán. | FR10 dùng /v1/ trong khi các FR khác dùng /api/v1/ |
+| db_schema_specified | LLM-check: DB schema đầy đủ field types, PKs, FKs. | BIGINT PKs vs UUID v7 conflict |
+| data_model_fields | LLM-check: entity fields nhất quán giữa các files. | Policy entity 13 fields vs 9 fields giữa FR10 và System |
+| no_contradictions | LLM-check: không có mâu thuẫn nội dung giữa các files. | State machine 14 states vs 7 states |
+| terminology_consistent | LLM-check: thuật ngữ dùng nhất quán. | Customer vs User vs Khách hàng cho cùng concept |
+| error_handling_defined | LLM-check: error handling đầy đủ. | Không có central error code registry |
+| uc-id-*-mismatch | LLM-check: UC ID prefix không khớp giữa System spec và SRS file. | uc-id-purchase-mismatch: UC-IP vs UC-PU |
+| policy-* | LLM-check: Policy lifecycle/state machine issues. | policy-creation-flow-inconsistency |
+| srs-completeness-* | LLM-check: SRS file completeness per module. | srs-completeness-fr9: FR-9 thiếu ERD |
+| llm-* | LLM-check: semantic analysis results. | llm-missing-refund-spec, llm-testability-uw-timeout |
+| risk-* | LLM-check: business risk assessment. | risk-refund-flow-missing |
+| ui-* | LLM-check: user impact assessment. | ui-accessibility-missing |
+| tech_stack_consistent | LLM-check: DB/broker/cache technology nhất quán giữa files. | MongoDB vs MariaDB vs PostgreSQL cho cùng entity |
+| pk_fk_type_consistent | LLM-check: PK/FK type nhất quán theo canonical model. | BIGINT PKs vs UUID v7 conflict |
+| canonical_model_match | LLM-check: feature SRS fields khớp System SRS canonical model. | Policy entity 13 fields (FR10) vs 9 fields (System) |
+| currency_type_convention | LLM-check: currency fields thống nhất convention. | DECIMAL vs BIGINT (đơn vị nhỏ nhất) |
+| cross_file_state_machine_match | LLM-check: state machine feature SRS khớp System SRS. | Claim 14 states (FR11) vs 7 states (System) |
+| event_payload_schema | LLM-check: Kafka/event payload có schema đầy đủ. | Event mentioned nhưng không có payload fields/types |
+| *-implementation-ready | LLM-check: module readiness to implement. | fr1-implementation-ready |
+| br_assumptions_confirmed | LLM-check (V-02): BR không được viết dựa trên quyết định business chưa được confirm. Contradiction: luồng đã cứng hoá nhưng file ghi "câu hỏi cần confirm". | BR-PL-023 viết sẵn grace period behavior nhưng file ghi "cần business confirm" |
+| downstream_event_consumers | LLM-check (V-03): mỗi event được publish phải có downstream consumers và side effects được mô tả. | PaymentCompletedEvent không có promotion-service consumer |
+| cancellation_subflows_by_context | LLM-check (V-03): nếu có cooling-off concept, phải có nhánh huỷ riêng (trong/ngoài cooling-off) và ngày tính refund phải rõ ràng. | Chỉ có 1 luồng huỷ không phân biệt cooling-off |
+| service_ownership_consistent | LLM-check (V-04): entity/resource phải được giao cho cùng service nhất quán cross-file. | Voucher validate: pricing-service (FR8) vs promotion-service (FR7, FR17) |
+| api_contract_param_match | LLM-check (V-04): params trong SRS call phải match params required trong API contract. | FR7 gọi /vouchers/best?productId={id} nhưng contract yêu cầu userId+productId+premium |
+| currency_unit_intra_section | LLM-check (V-04): không trộn đơn vị tiền trong cùng entity/breakdown section. | discount_amount=50000 đồng cạnh premium=5000000 cents trong cùng entity |
+| state_name_uc_vs_diagram | LLM-check (V-04): state names trong UC flow steps phải khớp với nodes trong State Diagram. | UC dùng PENDING_ACTIVATION nhưng diagram chỉ có PENDING_ISSUANCE |
+| referenced_fr_exists | LLM-check (V-04): FR được tham chiếu trong SRS phải tồn tại trong FR inventory. | "cross-insurer fallback (FR29)" — FR29 không tồn tại |
+| upstream_artifact_alignment | LLM-check (V-02): Mọi structured artifact trong SRS (entity enums, fields, actors, phases, BR references) phải traceable về BRD/PRD. Diff: additions, removals, renames, type mismatches. Silent drops = CRITICAL, inventions = HIGH, naming divergence = HIGH. | BRD: 7 claim states (PAID); SRS: 11 states (thêm DISPUTED, tách PAID→DISBURSING+COMPLETED) — SRS refines nhưng phải documented |
+| upstream_structural_consistency | LLM-check (V-04): SRS structural artifacts (state machines, transitions, field schemas, API paths, Kafka events) phải consistent với BRD state diagrams + Architecture event catalog + PRD AC state names. Transition order conflicts, field type mismatches, event coverage gaps = HIGH+. | BRD: UNDER_REVIEW→PROCESSING; SRS: PROCESSING→UNDER_REVIEW (reversed). PRD AC: DOCUMENTS_PENDING; SRS: DOCS_REQUIRED (name mismatch) |
+| rules_self_explanatory | LLM-check (V-05): mỗi rule phải self-explanatory không cần PO interpret, tránh undefined terms. | "not exposed until acceptance" — acceptance không được định nghĩa |
+| async_sla_defined | LLM-check (V-07): mỗi async flow phải có SLA timeout + escalation path + behavior khi quá SLA. | Endorsement treo ở INSURER_PROCESSING vô thời hạn vì không có timeout |
+| auth_method_mapping | LLM-check (V-07): API spec phải có bảng mapping actor/channel → auth method. | "5 phương thức xác thực" nhưng không nói ai dùng cái nào |
+| configurable_thresholds_flagged | LLM-check (V-07): threshold/config values phải đánh dấu configurable, không hardcode trong spec. | OCR threshold 0.85 hardcode thay vì configurable per insurer |
+| error_code_edge_states | LLM-check (V-07): phải có error codes cho cross-state edge cases (action X trên entity ở state Y). | Không có mã lỗi cho: gia hạn HĐ đã quá grace, huỷ HĐ đang LAPSED, quote expired |
+| insurer_rejection_rollback | LLM-check (V-08): mỗi flow gọi insurer phải có nhánh insurer từ chối + rollback. | Renewal assume insurer luôn accept — không có rejection path |
+| platform_insurer_sync_gap_risk | LLM-check (V-08): khi platform confirm trước insurer sync, phải định nghĩa trách nhiệm trong gap. | KH nhận "kích hoạt thành công" nhưng insurer chưa ghi nhận — claim trong 15 phút đó? |
+| concurrent_operation_conflict | LLM-check (V-08): nếu cho phép concurrent ops, phải có conflict resolution rule. | Nhiều endorsements đồng thời — delta premium tính thế nào? |
+| dlq_alert_action_defined | LLM-check (V-08): DLQ/webhook failure phải có action plan, không chỉ "alert admin". | Webhook EXPIRED → alert admin → admin làm gì? bấm retry ở đâu? |
+| pre_payment_benefit_disclosure | LLM-check (V-09): KH phải được acknowledge nếu thanh toán cho quyền lợi có waiting period / coverage gap. | Add-on waiting period: KH trả tiền hôm nay nhưng coverage từ ngày X — không có acknowledge step |
+| auto_financial_action_advance_notice | LLM-check (V-09): mọi hành động tài chính tự động phải có thông báo advance cho KH. | Auto-renewal trừ tiền mà KH không nhận được thông báo trước (mâu thuẫn PRD AC39.4) |
+| async_wait_ux | LLM-check (V-09): khi KH chờ async processing, phải mô tả UX: KH thấy gì, có thể huỷ không, nhận gì khi timeout. | Đang mua BH chờ UW: "đang xử lý" — KH làm gì? Có nút Huỷ không? |
+
+---
+
+## 5. SCORING — Cách tính điểm
+
+| Metric | Mô tả | Giá trị |
+|---|---|---|
+| Score per finding | 1.0 = pass, 0.5 = partial, 0.0 = fail | |
+| Dimension score | Trung bình weighted của tất cả findings trong dimension | OK >= 80%, WARN 60-79%, FAIL < 60% |
+| Overall score | Weighted average: completeness/consistency/quality/readiness x 1.0, risk x 0.8, user-impact x 0.7 | |
+| Source: auto | Kiểm tra tự động — structure, keyword, section check | |
+| Source: llm | LLM agent phân tích semantic — cross-reference, testability, flow gaps, contradictions | |
+
+---
+
+## 6. AUTO-CHECK ITEMS — Kiểm tra tự động theo SRS template
+
+### 6.1 Completeness — Section existence checks
+
+| Item ID | Check | Section trong template | Severity |
+|---|---|---|---|
+| has_overview | Section "1. Mô tả chung" tồn tại với đầy đủ fields | Section 1 | CRITICAL |
+| has_use_case_summary | Bảng "1.1 Tóm tắt Use Cases" có data | Section 1.1 | CRITICAL |
+| has_glossary | Section "1.2 Định nghĩa & Từ viết tắt" | Section 1.2 | MEDIUM |
+| has_references | Section "1.3 Tài liệu tham chiếu" | Section 1.3 | MEDIUM |
+| has_uc_screens | Mỗi UC có subsection "Màn hình" với bảng controls | Section 2.X.1 | CRITICAL |
+| has_uc_sequence | Mỗi UC có Sequence Diagram (PlantUML) | Section 2.X.2 | CRITICAL |
+| has_uc_flow_table | Mỗi UC có Bảng mô tả luồng nghiệp vụ | Section 2.X.2 | CRITICAL |
+| has_erd | Section "3. Bảng/Thực thể liên quan" có ER diagram | Section 3 | HIGH |
+| has_error_codes | Section "4. Danh sách mã lỗi" | Section 4 | HIGH |
+| has_impact | Section "5. Chức năng ảnh hưởng" | Section 5 | MEDIUM |
+| has_business_rules | Section "6. Business Rules tổng hợp" | Section 6 | HIGH |
+| has_nfrs | Section "7. Yêu cầu phi chức năng" | Section 7 | MEDIUM |
+| has_dependencies | Section "8. Ràng buộc, Giả định & Phụ thuộc" | Section 8 | HIGH |
+| has_state_diagrams | Section "9. State Diagrams" hoặc ghi "Không áp dụng" | Section 9 | MEDIUM |
+| has_traceability | Section "10. Ma trận truy xuất (Mini-RTM)" | Section 10 | HIGH |
+| has_edge_cases | Luồng ngoại lệ/exception flows rõ ràng | Trong UC flows | MEDIUM |
+| has_acceptance_criteria | Acceptance Criteria đo lường được | Per UC | HIGH |
+
+### 6.2 Quality — Content quality checks
+
+| Item ID | Check | Severity |
+|---|---|---|
+| no_ambiguous_language | Không có "có thể", "nên", "thường", "tùy trường hợp", TBD | HIGH |
+| acceptance_criteria_format | AC theo Given/When/Then hoặc checklist measurable | HIGH |
+| no_duplicate_requirements | Không trùng lặp requirements giữa các UC/files | MEDIUM |
+| clear_scope | Có section phạm vi + ngoài phạm vi rõ ràng | HIGH |
+| no_placeholder | Không còn {{...}}, TODO, TBD chưa xử lý | HIGH |
+| consistent_language | Ngôn ngữ nhất quán (toàn VN hoặc toàn EN) | LOW |
+| flow_step_numbering | Bảng mô tả luồng có đánh số bước liên tục | HIGH |
+| diagram_syntax_valid | PlantUML/Mermaid syntax hợp lệ | CRITICAL |
+
+### 6.3 Consistency — Cross-file checks (cần so sánh nhiều files)
+
+| Item ID | Check | Severity |
+|---|---|---|
+| entity_naming | Entity names nhất quán giữa ER, bảng mô tả, luồng | CRITICAL |
+| uc_id_pattern | UC ID tuân theo UC-FX-NN pattern | HIGH |
+| screen_id_pattern | Screen ID tuân theo SCR-FX-NN pattern | HIGH |
+| actor_naming | Actor names nhất quán | HIGH |
+| api_naming_pattern | API endpoint prefix nhất quán (/api/v1/) | HIGH |
+| state_naming | State names nhất quán giữa diagrams và bảng | HIGH |
+| error_code_consistency | Error codes nhất quán giữa section 4 và flow steps | HIGH |
+| br_code_consistency | Business Rule mã BR-XXX nhất quán | HIGH |
+| terminology_consistent | Thuật ngữ thống nhất, không dùng lẫn lộn | MEDIUM |
+| rtm_fr_match | FR IDs trong Mini-RTM khớp PRD source | HIGH |
+| data_model_fields | Entity fields nhất quán giữa các files | CRITICAL |
+| no_contradictions | Không mâu thuẫn nội dung giữa các files | CRITICAL |
+| tech_stack_consistent | DB technology, message broker, cache nhất quán giữa các files cho cùng entity/module | CRITICAL |
+| pk_fk_type_consistent | PK type (UUID v7 vs BIGINT vs SERIAL) và FK references nhất quán theo canonical model | HIGH |
+| canonical_model_match | Entity fields trong feature SRS khớp System SRS canonical model (field count, field names, data types) | CRITICAL |
+| currency_type_convention | Currency fields thống nhất convention: BIGINT (đơn vị nhỏ nhất) hoặc DECIMAL — không trộn lẫn | HIGH |
+| cross_file_state_machine_match | State machine trong feature SRS khớp System SRS (state count, state names, transitions) | CRITICAL |
+
+### 6.4 Readiness — Implementation readiness checks
+
+| Item ID | Check | Severity |
+|---|---|---|
+| api_contracts_defined | API contracts: method, endpoint, request/response schema | CRITICAL |
+| db_schema_specified | DB schema đầy đủ: field types, PKs, FKs | HIGH |
+| error_handling_defined | Error codes: mã, message, HTTP status, step trigger | HIGH |
+| state_machine_complete | State machine: transitions, guards, actions | HIGH |
+| integration_specs | External API: format, auth, timeout, retry | HIGH |
+| event_payload_schema | Kafka/event payload schema defined: topic, fields, types, version — không chỉ mention event name | CRITICAL |
+| validation_rules | Input field validation: regex, range, format | HIGH |
+| navigation_flow | Screen navigation rõ ràng: A → action → B | MEDIUM |
+| mockup_reference | Mockup/wireframe reference cho mỗi màn hình | MEDIUM |
+| br_implementable | Business rules có thể code trực tiếp | HIGH |
+
+### 6.5 Risk — Risk assessment checks
+
+| Item ID | Check | Severity |
+|---|---|---|
+| exception_flows_handled | Tất cả exception flows: network error, timeout, invalid data | HIGH |
+| external_deps_fallback | External dependencies có fallback | HIGH |
+| integration_gaps | Integration gaps giữa flows đã document | HIGH |
+| scope_creep | Không có requirements vượt PRD scope | MEDIUM |
+| assumptions_listed | Assumptions đã liệt kê và đánh dấu cần confirm | MEDIUM |
+| concurrency_considered | Race condition scenarios đã xem xét | HIGH |
+| migration_risk | Data migration risks đã xử lý (nếu thay flow cũ) | HIGH |
+| security_risks | Authentication, authorization, data exposure | CRITICAL |
+
+### 6.6 User Impact — User experience checks
+
+| Item ID | Check | Severity |
+|---|---|---|
+| persona_coverage | Tất cả personas/actors trong PRD đã cover | HIGH |
+| journey_complete | User journey hoàn chỉnh entry → completion | HIGH |
+| error_ux | Error messages rõ ràng, có hướng dẫn xử lý | HIGH |
+| onboarding | First-time experience đã xem xét | MEDIUM |
+| loading_empty_states | Loading states, empty states đã mô tả | MEDIUM |
+| accessibility | Accessibility considerations (nếu yêu cầu) | LOW |
+| back_cancel_undo | Navigation back/cancel/undo đã xử lý | MEDIUM |
+| destructive_confirmation | Confirmation dialogs cho destructive actions | MEDIUM |
+
+---
+
+## 7. OUTPUT REPORT STRUCTURE
+
+### Frontmatter
+
+```yaml
+---
+type: srs-validation-report
+date: {date}
+validator: BA Validate SRS Skill
+scope: {single | batch | full}
+files_reviewed: [list of files]
+overall_score: {number}%
+overall_status: {OK | WARN | FAIL}
+stepsCompleted: []
+---
+```
+
+### Report Sections
+
+1. **Executive Summary** — Overall score, status, findings count by severity
+2. **Per-Dimension Scorecard** — Table: dimension, weight, score, status, findings count
+3. **Critical & High Findings** — Must-fix: #, severity, dimension, file, item_id, score, evidence, suggestion
+4. **Medium & Low Findings** — Nice-to-fix items
+5. **Unresolved Questions** — Questions needing PO/stakeholder decision: #, severity, dimension, category, question, context, related_files, impact, suggested_clarification
+6. **Recommendations** — Prioritized action plan
+7. **Appendix: Full Scoring Matrix** — All items with scores

package/skills/sdlc/ba-validate-srs/steps-v/step-v-01-discovery.md

@@ -0,0 +1,280 @@
+---
+# model: haiku
+# contextOutput: '{output_folder}/_validation_temp/context.yaml'
+# grepPatterns: '../data/grep-patterns-srs.yaml'
+---
+
+# Step V-01: Discovery — Xác định scope và tạo report skeleton
+
+---
+
+## 1. Xác định SRS files cần validate
+
+Hỏi user:
+
+```
+Bạn muốn validate SRS nào?
+
+1. **Single file** — Validate 1 file SRS cụ thể
+2. **Batch** — Validate nhiều files SRS (chọn danh sách)
+3. **Full** — Validate toàn bộ SRS trong folder output
+
+Chọn (1/2/3):
+```
+
+Chờ user chọn.
+
+---
+
+## 2. Scan files
+
+Dựa vào lựa chọn:
+
+### Option 1 — Single file
+- User cung cấp file path hoặc FR number
+- Đọc file, xác nhận file tồn tại và có nội dung
+
+### Option 2 — Batch
+- Liệt kê tất cả SRS files trong `{output_folder}/`
+- User chọn files cần validate
+- Đọc danh sách files đã chọn
+
+### Option 3 — Full
+- Scan toàn bộ `{output_folder}/05-srs*.md`
+- Liệt kê cho user confirm
+
+---
+
+## 3. Load Project Context (auto — không cần user input)
+
+Tự động load project context từ VSAF artifacts:
+
+1. Read `graphify-out/graph.json` (nếu tồn tại) → extract document nodes, feature nodes, service nodes
+2. For each SRS file in scope:
+   - Determine feature name from file path
+   - Locate upstream docs trong `.vsaf/docs/features/{feature-name}/`
+3. Cross-validation sources (auto-load):
+   - PRD: `.vsaf/docs/features/{feature-name}/02-prd.md`
+   - Architecture: `.vsaf/docs/features/{feature-name}/03-adr.md`
+   - Epics: `.vsaf/docs/features/{feature-name}/04-epics.md` (nếu tồn tại)
+   - BRD: tìm trong `.vsaf/docs/` (optional — chỉ khi project có BRD)
+   - System SRS: tìm trong `.vsaf/docs/` (optional)
+
+**Token efficiency rule:** PRD và ADR trong VSAF thường nhỏ (<500 lines). Đọc toàn bộ file thay vì dùng line-range optimization.
+
+---
+
+## 3b. Build SRS Section Index and UC Cache
+
+After loading KG context, build two caches to eliminate redundant reads in parallel validation steps.
+
+### 3b-1. SRS Section Index
+
+Load `../data/grep-patterns-srs.yaml` → get `srs_structure` patterns.
+
+For each SRS file in scope:
+- Run Grep `^## ` on SRS file, output_mode="content", -n=true → extract all Level-2 section headers with line numbers
+- Build `section_index`: list of `{heading, start_line, end_line}` for each `##` header
+- Compute `end_line` for each heading = next heading's `start_line - 1` (or file total lines for last section)
+
+### 3b-2. UC Cache
+
+For each SRS file:
+- Run Grep `^### .*UC-` with -n=true → extract all UC headers and line numbers
+- For each UC found, record:
+  - `id`: UC identifier (e.g., UC-CA-01)
+  - `title`: UC title text  
+  - `start_line`: line of UC header
+  - `end_line`: start_line of next UC (or +80 as estimate)
+  - `has_gherkin`: run Grep `Given.*When.*Then` within UC line range → true/false
+- Build `uc_cache`: list of all UCs across all SRS files in scope
+
+### 3b-3. Extract Glossary Dimension Items
+
+To avoid each parallel agent loading the full glossary:
+- From the glossary already loaded in workflow initialization, extract item IDs per dimension:
+  - completeness_items: [has_overview, has_use_case_summary, has_glossary, ...]
+  - consistency_items: [uc_id_pattern, screen_id_pattern, ...]
+  - quality_items: [no_ambiguous_language, acceptance_criteria_format, ...]
+  - (etc. for each dimension)
+
+### 3b-4. Write context.yaml
+
+Create directory `{output_folder}/_validation_temp/` if it does not exist.
+
+Write `{output_folder}/_validation_temp/context.yaml`:
+
+```yaml
+# SRS Validation session context — auto-generated by step-v-01
+# DO NOT EDIT manually
+validation_date: "{date}"
+scope: "{single|batch|full}"
+report_path: "{report_output_path}"
+silent_mode: {false}   # set true if --silent invocation arg
+
+# SRS files in scope
+srs_files:
+  - path: "{srs_file_path}"
+    fr_id: "{FR_ID}"
+    section_index:    # from Grep ^## with computed end_line
+      - heading: "1. Mô tả chung"
+        start_line: 39
+        end_line: 134      # next heading start_line - 1
+      - heading: "2. Đặc tả Use Cases"
+        start_line: 135
+        end_line: 1318
+      # ... all ## headings with computed end_line (last section end_line = total file lines)
+    uc_cache:         # from Grep ^### UC-
+      - id: "UC-CA-01"
+        title: "Đăng ký tài khoản chủ động"
+        start_line: 120
+        end_line: 200
+        has_gherkin: true
+      # ... etc
+
+# Project context (VSAF convention)
+upstream:
+  prd_path: ".vsaf/docs/features/{feature-name}/02-prd.md"
+  adr_path: ".vsaf/docs/features/{feature-name}/03-adr.md"
+  epics_path: ".vsaf/docs/features/{feature-name}/04-epics.md"
+  brd_path: null  # set if project has BRD
+  graph_json: "graphify-out/graph.json"  # set if graphify index exists
+
+# Glossary item IDs per dimension (pre-extracted for agent efficiency)
+dimension_items:
+  business_alignment: []
+  completeness: [has_overview, has_use_case_summary, has_glossary, has_references, has_uc_screens, has_uc_sequence, has_uc_flow_table, has_erd, has_error_codes, has_impact, has_business_rules, has_nfrs, has_dependencies, has_state_diagrams, has_traceability, has_edge_cases, has_acceptance_criteria]
+  consistency: []
+  quality: [no_ambiguous_language, acceptance_criteria_format, no_duplicate_requirements, clear_scope, flow_step_numbering, diagram_syntax_valid]
+  system_nfr: []
+  delivery_readiness: []
+  risk_analysis: []
+  user_impact: []
+```
+
+**Token efficiency note:** context.yaml (~100-150 lines) replaces 8+ separate KG file reads across parallel agents. Each agent reads context.yaml once instead of re-loading project artifacts independently.
+
+**Derived-from traceability rule (CRITICAL):**
+SRS is a **derived document** — every requirement MUST trace back to PRD, BRD, or Architecture. If SRS contains requirements not in any upstream source, flag as:
+- **CRITICAL** if SRS invents new functional requirements not in PRD/BRD
+- **HIGH** if SRS adds business rules not traceable to BRD
+- **MEDIUM** if SRS adds NFRs/constraints beyond Architecture specs
+
+Upstream chain: `BRD → PRD → SRS`, `Architecture → SRS`
+
+---
+
+## 3c. Regression Check — Load Previous Reports
+
+Scan `.vsaf/docs/features/{feature-name}/05-srs-validation-report*.md` for existing reports.
+
+If previous reports exist:
+1. Find the most recent report (by date in filename, excluding the report being created now)
+2. Read its frontmatter to get `overall_score`, `overall_status`, `files_reviewed`
+3. Read its "Critical & High Findings" section (section 4) — extract finding IDs
+4. Write to context.yaml:
+
+```yaml
+regression:
+  previous_report: "05-srs-validation-report-2026-04-06.md"
+  previous_score: 72.3
+  previous_status: WARN
+  previous_critical_high_ids:
+    - {id: C-001, dimension: consistency, summary: "service boundary violation"}
+    - {id: DR-002, dimension: delivery, summary: "API specs missing"}
+```
+
+If no previous reports exist:
+```yaml
+regression:
+  previous_report: null
+  note: "First validation run — no regression baseline"
+```
+
+---
+
+## 4. Tạo report skeleton
+
+Tạo file output: `.vsaf/docs/features/{feature-name}/05-srs-validation-report.md`
+
+Viết frontmatter:
+
+```yaml
+---
+type: srs-validation-report
+date: {date}
+validator: BA Validate SRS Skill
+scope: {scope}
+files_reviewed:
+  - {list of files}
+overall_score: TBD
+overall_status: TBD
+stepsCompleted:
+  - step-v-01-discovery
+---
+```
+
+Viết section headers (chưa có nội dung):
+
+```markdown
+## 1. Executive Summary
+
+_(Sẽ được điền ở Step V-10)_
+
+## 2. Overall Score & Confidence
+
+_(Sẽ được điền ở Step V-10)_
+
+## 3. Heatmap — Score by Dimension
+
+_(Sẽ được điền ở Step V-10)_
+
+## 4. Critical & High Findings
+
+_(Sẽ được điền ở Steps V-02 → V-09)_
+
+## 5. Medium & Low Findings
+
+_(Sẽ được điền ở Steps V-02 → V-09)_
+
+## 6. Top Missing Areas
+
+_(Sẽ được điền ở Step V-10)_
+
+## 7. Unresolved Questions
+
+_(Sẽ được điền ở Steps V-02 → V-09)_
+
+## 8. Action Plan
+
+_(Sẽ được điền ở Step V-10)_
+
+## 9. Appendix: Full Scoring Matrix
+
+_(Sẽ được điền ở Step V-10)_
+```
+
+---
+
+## 5. Confirm & Route
+
+Xuất cho user:
+
+```
+Scope: {scope}
+Files: {count} file(s)
+  - {file list}
+Cross-validate: PRD=auto, ADR=auto, Epics=auto (if exists), BRD=auto (if exists)
+Report: .vsaf/docs/features/{feature-name}/05-srs-validation-report.md
+Context: {output_folder}/_validation_temp/context.yaml ✓
+UC Cache: {uc_count} UCs indexed ✓
+Graph: {graph_json status}
+
+[C] Continue — Bắt đầu validate Business Alignment (Step V-02)
+[X] Cancel — Dừng lại
+```
+
+**Chờ user chọn.**
+
+Khi user chọn **C** và `{parallel_mode}` là `true`: Hiển thị "Parallel validation mode: launching Round 1..." rồi follow **PARALLEL EXECUTION ROUNDS → Round 1** trong workflow.md
+Khi user chọn **C** và `{parallel_mode}` là `false`: đọc fully và follow `./step-v-02-business-alignment.md` (sequential fallback)