Alex Verkhovsky
a1101534b2
* fix(docs): comprehensive documentation site review fixes Rehype plugins: - Rewrite rehype-markdown-links for correct relative .md resolution - Handle raw HTML base paths and bare .md links in rehype-base-paths - Guard protocol-relative URLs (//...) in all link processors - Use file.path instead of file.history[0] for vfile compatibility - Fail build when content directory cannot be detected - Export helpers for testability; add 107 unit tests Build & CI: - Revert cancel-in-progress to false to avoid mid-deploy cancellation - Remove redundant link-validation CI step (build validates internally) - Remove unnecessary fetch-depth:0 from docs deploy workflow - Refuse docs build on Windows (platform guard) - Remove dead build scripts and stale references Tooling: - Add DOCS_ROOT boundary check in validate-doc-links.js - Handle directory paths and prefix stripping in link validator - Remove dead regex and add // guard in fix-doc-links.js Accessibility & CSS: - Darken caution/danger aside title colors for WCAG AA 4.5:1 contrast - Fix 100vw scrollbar overflow (banner width:100%, html overflow-x:clip) - Add :focus-visible ring to banner link for keyboard navigation - Remove dead CSS declaration and add missing code block lang Documentation content: - Convert /docs/ absolute links to relative paths and fix llms.txt URLs - Correct command file paths and naming in commands reference - Update stale shard-doc command to current /bmad-shard-doc format - Fix incomplete sentence in install-bmad.md - Add Quick Flow next steps and fix 404 link path - Expand thin content pages with substantive detail - Add sidebar ordering frontmatter to all content pages - Remove BMGD docs (moved to dedicated repo) - Remove unused assets and misleading diagram caption - Add non-iframe fallback link to workflow map diagram - Remove dead noscript block from workflow-map - Standardize BMAD to BMad, fix spelling/grammar, normalize headings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides - Move non-interactive-installation.md into how-to/ directory so it appears in the sidebar navigation (was orphaned at docs root) - Rewrite the page based on editorial review: consolidate redundant sections, add missing how-to structure (prerequisites, "What You Get"), condense installation modes from 5 subsections to a table, cut speculative examples - Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3), then the rest following user journey order - Fix README link to point to docs site instead of repo-internal markdown path Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): address documentation review findings Fix broken directory tree, grammar errors, inconsistent naming, missing admonition/headings, enable lastUpdated timestamps in CI, and remove footer CSS that misapplied to the content footer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): move bleeding-edge install command out of Verify Installation The alternative npx command for installing from main was misplaced inside the "Verify Installation" section. Move it to a tip admonition under Step 1 where users look for install options. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.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. :::