boshu
3fe37b1867
Make `scripts/docs-build.sh --check` a MEANINGFUL signal instead of advisory noise (was 82 strict-mode warnings, always ignored). Root cause: mkdocs --strict fails on 82 links that leave docs/ (the knowledge graph deliberately links out to skills/, scripts/, schemas/, evals/, and canonical repo-root docs). All 82 were verified to resolve to REAL repo files on disk — zero accidental breaks — so they are intentional cross-references, not bugs. Fixes (category A + B, INFO-level drift, verified against built HTML anchors): - Anchors: GLOSSARY SKILLS.md#beads->#beads-br; INCIDENT-RUNBOOK scenario-C double->single hyphen (x2); pawls.md directive-precedence / diversity-mode / escalation double->single (referrers in ADR-0007, autonomy-ladder, pawls self); catch-derived-fuel membrane update anchor (single + date suffix). - Suffixes: levels L1-L4 README next-level links + workflows meta-observer -> explicit README.md targets. Dispositions (category C + D): the 82 intentional external cross-refs are enumerated in tests/docs/mkdocs-strict-allowlist.txt and explained per-class in docs/docs-build-dispositions.md. `docs-build.sh --check` now runs mkdocs --strict end-to-end (nothing weakened, no --no-strict) and fails on any warning NOT on the allowlist — proven: a fresh broken link still fails the check; the 82 pass. Result: `docs-build.sh --check` is CLEAN-or-dispositioned (exit 0). Wired doc into nav + CONTRIBUTING pointer.
Workflow Guide
Which workflow should I use? Find the right one in seconds.
Golden Paths
Use these as the default user journeys before reaching for the full decision tree.
| Situation | Start with | Continue with |
|---|---|---|
| First repo setup | ao quick-start |
/bootstrap, then /rpi "a small goal" |
| Small, obvious change | Quick Fix | /implement, then /validate --quick recent |
| New feature or broad change | Complete Cycle | /rpi "goal" or /plan -> /crank <epic-id> |
| Existing tracked backlog | ao reconcile --json, then BEADS_DIR="$(ao beads dir)" br ready |
/implement <issue-id> or /crank <epic-id> |
| Review-only checkpoint | /council validate this PR |
/validate recent before merge |
| Terminal-native operation | ao session bootstrap |
ao lookup --query "<topic>", then drive the operating loop and ao gate check --fast --scope head |
Decision Tree
| I want to... | Use this workflow | Complexity | Key Skills |
|---|---|---|---|
| Fix a simple bug or make a quick change | Quick Fix | Low | /implement |
| Investigate and fix a hard bug | Debug Cycle | Medium | /bug-hunt, /implement, /retro |
| Build a new feature end-to-end | Complete Cycle | High | /research, /plan, /crank, /vibe |
| Deploy infrastructure changes | Infrastructure Deployment | High | /plan, /implement, /vibe |
| Work across multiple domains at once | Multi-Domain | High | /plan, /swarm |
| Validate research assumptions before planning | Assumption Validation | Medium | /research |
| Understand a new codebase or extract patterns | Knowledge Synthesis | Medium | /research, /knowledge-activation |
| Run a retrospective after completing work | Post-Work Retro | Low | /retro, /post-mortem |
| Improve system quality over time | Continuous Improvement | Medium | /retro, /vibe |
| Manage a session from start to finish | Session Lifecycle | Low | (natural language) |
| Coordinate N autonomous workers without a leader | Meta-Observer Pattern | High | /swarm |
Workflows
Quick Fix
When to use: Simple, low-risk changes to 1-2 files with an obvious solution. Complexity: Low (10-30 min, single session) Key skills: /implement
Debug Cycle
When to use: Production incidents, intermittent failures, performance issues, or integration bugs with unknown root cause. Complexity: Medium-High (1-3 hours, 1-3 sessions) Key skills: /bug-hunt, /implement, /retro
Complete Cycle
When to use: New features, complex multi-file changes, or architectural work that needs full Research-Plan-Implement-Validate-Learn phases. Complexity: High (2-4 hours, 2-4 sessions) Key skills: /research, /plan, /crank, /vibe, /retro
Infrastructure Deployment
When to use: Infrastructure deployments that need validation gates, reality checks, and tracer bullets at every phase. Complexity: High (multi-session) Key skills: /plan, /implement, /vibe
Multi-Domain
When to use: Work spanning multiple domains simultaneously (backend + frontend + infra, technical + personal tracking). Complexity: High (multi-session) Key skills: /plan, /swarm
Assumption Validation
When to use: Before planning, to verify that research findings match reality (APIs exist, images available, operators behave as expected). Complexity: Medium Key skills: /research
Knowledge Synthesis
When to use: Onboarding to a new codebase, creating comprehensive docs, extracting patterns from multiple implementations. Complexity: Medium (30-60 min, single session) Key skills: /research, /knowledge-activation
Post-Work Retro
When to use: After completing significant work, to capture learnings and identify improvements. Complexity: Low Key skills: /retro, /post-mortem
Continuous Improvement
When to use: Periodic reviews (weekly/monthly), after milestones, technical debt reduction, or pattern refinement. Complexity: Medium (ongoing, periodic) Key skills: /retro, /vibe
Session Lifecycle
When to use: Managing any working session from start to finish -- starting work, resuming context, wrapping up. Complexity: Low (use natural language) Key skills: Just talk naturally; commands are optional.
Meta-Observer Pattern
When to use: Coordinating N autonomous workers through shared memory (stigmergy) without central orchestration. Complexity: High (advanced, multi-session) Key skills: /swarm Deep dive: meta-observer/ (pattern guide, examples, showcase)
Flowchart
Start here
|
v
Is it a simple, obvious fix? ----YES----> Quick Fix
|
NO
|
v
Is something broken? ----YES----> Debug Cycle
|
NO
|
v
Am I deploying infrastructure? ----YES----> Infrastructure Deployment
|
NO
|
v
Does it span multiple domains? ----YES----> Multi-Domain
|
NO
|
v
Am I building something new? ----YES----> Complete Cycle
|
NO
|
v
Am I trying to understand code/patterns? ----YES----> Knowledge Synthesis
|
NO
|
v
Am I wrapping up or improving? ----YES----> Post-Work Retro / Continuous Improvement