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>
2.7 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Adversarial Review | Forced reasoning technique that prevents lazy "looks good" reviews |
|
Force deeper analysis by requiring problems to be found.
What is Adversarial Review?
A review technique where the reviewer must find issues. No "looks good" allowed. The reviewer adopts a cynical stance - assume problems exist and find them.
This isn't about being negative. It's about forcing genuine analysis instead of a cursory glance that rubber-stamps whatever was submitted.
The core rule: You must find issues. Zero findings triggers a halt - re-analyze or explain why.
Why It Works
Normal reviews suffer from confirmation bias. You skim the work, nothing jumps out, you approve it. The "find problems" mandate breaks this pattern:
- Forces thoroughness - Can't approve until you've looked hard enough to find issues
- Catches missing things - "What's not here?" becomes a natural question
- Improves signal quality - Findings are specific and actionable, not vague concerns
- Information asymmetry - Run reviews with fresh context (no access to original reasoning) so you evaluate the artifact, not the intent
Where It's Used
Adversarial review appears throughout BMad workflows - code review, implementation readiness checks, spec validation, and others. Sometimes it's a required step, sometimes optional (like advanced elicitation or party mode). The pattern adapts to whatever artifact needs scrutiny.
Human Filtering Required
Because the AI is instructed to find problems, it will find problems - even when they don't exist. Expect false positives: nitpicks dressed as issues, misunderstandings of intent, or outright hallucinated concerns.
You decide what's real. Review each finding, dismiss the noise, fix what matters.
Example
Instead of:
"The authentication implementation looks reasonable. Approved."
An adversarial review produces:
- HIGH -
login.ts:47- No rate limiting on failed attempts- HIGH - Session token stored in localStorage (XSS vulnerable)
- MEDIUM - Password validation happens client-side only
- MEDIUM - No audit logging for failed login attempts
- LOW - Magic number
3600should beSESSION_TIMEOUT_SECONDS
The first review might miss a security vulnerability. The second caught four.
Iteration and Diminishing Returns
After addressing findings, consider running it again. A second pass usually catches more. A third isn't always useless either. But each pass takes time, and eventually you hit diminishing returns - just nitpicks and false findings.
:::tip[Better Reviews] Assume problems exist. Look for what's missing, not just what's wrong. :::