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>
5.6 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Quick Dev | Snižte tření human-in-the-loop bez ztráty kontrolních bodů chránících kvalitu výstupu |
|
Záměr na vstupu, změny kódu na výstupu, s co nejmenším počtem human-in-the-loop kroků — bez obětování kvality.
Umožňuje modelu běžet déle mezi kontrolními body a poté přivede člověka zpět pouze tehdy, když úkol nemůže bezpečně pokračovat bez lidského úsudku nebo když je čas zkontrolovat konečný výsledek.
Proč to existuje
Human-in-the-loop kroky jsou nutné a nákladné.
Současné LLM stále selhávají předvídatelnými způsoby: chybně čtou záměr, vyplňují mezery sebevědomými odhady, odchylují se k nesouvisející práci a generují šumový výstup revize. Současně neustálá lidská intervence limituje rychlost vývoje. Lidská pozornost je úzké hrdlo.
bmad-quick-dev přenastavuje tento kompromis. Důvěřuje modelu, aby běžel bez dozoru delší úseky, ale pouze poté, co workflow vytvořil dostatečně silnou hranici, aby to bylo bezpečné.
Základní design
1. Nejprve komprimujte záměr
Workflow začíná tím, že člověk a model zkomprimují požadavek do jednoho koherentního cíle. Vstup může začínat jako hrubé vyjádření záměru, ale předtím, než workflow poběží autonomně, musí být dostatečně malý, jasný a bez protimluvů pro provedení.
Záměr může přijít v mnoha formách: pár frází, odkaz na bug tracker, výstup z plan mode, text zkopírovaný z chatové relace, nebo dokonce číslo story z BMAD vlastního epics.md. V posledním případě workflow nepochopí sémantiku sledování stories BMAD, ale stále může vzít samotnou story a pracovat s ní.
Tento workflow neodstraňuje lidskou kontrolu. Přemisťuje ji na malý počet vysoce hodnotných momentů:
- Vyjasnění záměru — přeměna nepřehledného požadavku na jeden koherentní cíl bez skrytých protimluvů
- Schválení specifikace — potvrzení, že zmrazené porozumění je správná věc k budování
- Revize konečného produktu — primární kontrolní bod, kde člověk rozhoduje, zda je výsledek přijatelný
2. Nasměrujte na nejmenší bezpečnou cestu
Jakmile je cíl jasný, workflow rozhodne, zda jde o skutečnou jednorázovou změnu nebo zda potřebuje plnější cestu. Malé změny s nulovým blast-radius mohou jít přímo k implementaci. Vše ostatní prochází plánováním, aby model měl silnější hranici před tím, než poběží déle samostatně.
3. Běžte déle s menším dozorem
Po tomto rozhodnutí o směrování může model nést více práce samostatně. Na plnější cestě se schválená specifikace stává hranicí, proti které model provádí s menším dozorem, což je celý smysl designu.
4. Diagnostikujte selhání na správné vrstvě
Pokud je implementace špatná, protože byl špatný záměr, oprava kódu je špatná oprava. Pokud je kód špatný, protože specifikace byla slabá, oprava diffu je také špatná oprava. Workflow je navržen tak, aby diagnostikoval, kde selhání vstoupilo do systému, vrátil se na tu vrstvu a přegeneroval odtamtud.
Nálezy revize se používají k rozhodnutí, zda problém pochází ze záměru, generování specifikace nebo lokální implementace. Pouze skutečně lokální problémy se opravují lokálně.
5. Přiveďte člověka zpět pouze když je potřeba
Interview o záměru je human-in-the-loop, ale není to stejný druh přerušení jako opakující se kontrolní bod. Workflow se snaží udržet tyto opakující se kontrolní body na minimu. Po úvodním formování záměru se člověk vrací hlavně tehdy, když workflow nemůže bezpečně pokračovat bez úsudku a na konci, když je čas zkontrolovat výsledek.
- Řešení mezer v záměru — vstoupení zpět, když revize prokáže, že workflow nemohl bezpečně odvodit, co bylo myšleno
Vše ostatní je kandidátem na delší autonomní provádění. Tento kompromis je záměrný. Starší vzory věnují více lidské pozornosti nepřetržitému dozoru. Quick Dev věnuje více důvěry modelu, ale šetří lidskou pozornost pro momenty, kde má lidské uvažování nejvyšší páku.
Proč systém revize záleží
Fáze revize není jen pro hledání chyb. Je tu pro směrování korekce bez ničení momentum.
Tento workflow funguje nejlépe na platformě, která může spouštět sub-agenty, nebo alespoň vyvolat jiné LLM přes příkazovou řádku a čekat na výsledek. Pokud to vaše platforma nativně nepodporuje, můžete přidat skill, který to udělá. Bezcontextové sub-agenty jsou základním kamenem designu revize.
Agentní revize často selhávají dvěma způsoby:
- Generují příliš mnoho nálezů, čímž nutí člověka prosévat šum.
- Vychýlí aktuální změnu odhalením nesouvisejících problémů a přemění každý běh na ad-hoc úklidový projekt.
Quick Dev řeší obojí tím, že s revizí zachází jako s triáží.
Některé nálezy patří k aktuální změně. Některé ne. Pokud je nález náhodný spíše než kauzálně vázaný na aktuální práci, workflow ho může odložit místo nucení člověka ho okamžitě řešit. To udržuje běh zaměřený a zabraňuje náhodným tangentám ve spotřebování rozpočtu pozornosti.
Ta triáž bude někdy nedokonalá. To je přijatelné. Obvykle je lepší špatně posoudit některé nálezy než zaplavit člověka tisíci nízkohodnotných revizních komentářů. Systém optimalizuje pro kvalitu signálu, ne vyčerpávající recall.