Emmanuel Atsé
cede485217
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
3.2 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Khai thác nâng cao | Buộc LLM xem xét lại kết quả của nó bằng các phương pháp lập luận có cấu trúc |
|
Buộc LLM xem xét lại những gì nó vừa tạo ra. Bạn chọn một phương pháp lập luận, nó áp dụng phương pháp đó lên chính output của mình, rồi bạn quyết định có giữ các cải tiến hay không.
Khai thác nâng cao là gì?
Đây là một lần xem xét lại có cấu trúc. Thay vì bảo AI "thử lại" hoặc "làm cho nó tốt hơn", bạn chọn một phương pháp lập luận cụ thể và AI sẽ xem lại output của chính nó dưới góc đó.
Khác biệt này rất quan trọng. Yêu cầu mơ hồ sẽ tạo ra bản sửa đổi mơ hồ. Một phương pháp được gọi tên buộc AI tấn công vấn đề theo một hướng cụ thể, qua đó phát hiện những ý tưởng mà một lần thử lại chung chung sẽ bỏ lỡ.
Khi nào nên dùng
- Sau khi workflow tạo nội dung và bạn muốn có phương án thay thế
- Khi output có vẻ ổn nhưng bạn nghi vẫn còn có thể đào sâu hơn
- Để stress-test các giả định hoặc tìm điểm yếu
- Với nội dung quan trọng, nơi mà việc nghĩ lại sẽ có giá trị
Các workflow sẽ đưa ra tùy chọn khai thác nâng cao tại các điểm quyết định - sau khi LLM tạo một kết quả, bạn sẽ được hỏi có muốn chạy nó hay không.
Nó hoạt động như thế nào
- LLM đề xuất 5 phương pháp phù hợp với nội dung của bạn
- Bạn chọn một phương pháp (hoặc đảo lại để xem lựa chọn khác)
- Phương pháp được áp dụng, các cải tiến được hiện ra
- Chấp nhận hoặc bỏ đi, lặp lại hoặc tiếp tục
Các phương pháp tích hợp sẵn
Có hàng chục phương pháp lập luận có sẵn. Một vài ví dụ:
- Pre-mortem Analysis - Giả sử dự án đã thất bại rồi lần ngược lại để tìm lý do
- First Principles Thinking - Loại bỏ giả định, xây lại từ sự thật nền tảng
- Inversion - Hỏi cách nào chắc chắn dẫn đến thất bại, rồi tránh những điều đó
- Red Team vs Blue Team - Tự tấn công công việc của chính mình, rồi tự bảo vệ nó
- Socratic Questioning - Chất vấn mọi khẳng định bằng "tại sao?" và "làm sao bạn biết?"
- Constraint Removal - Bỏ hết ràng buộc, xem điều gì thay đổi, rồi thêm lại có chọn lọc
- Stakeholder Mapping - Đánh giá lại từ góc nhìn của từng bên liên quan
- Analogical Reasoning - Tìm điểm tương đồng ở lĩnh vực khác và áp dụng bài học của chúng
Và còn nhiều nữa. AI sẽ chọn những lựa chọn phù hợp nhất với nội dung của bạn - bạn quyết định chạy cái nào.
:::tip[Bắt đầu từ đây] Pre-mortem Analysis là lựa chọn đầu tiên tốt cho bất kỳ bản spec hoặc kế hoạch nào. Nó thường xuyên tìm ra các lỗ hổng mà một lần review thông thường bỏ qua. :::