boshu
4a7c6a0701
Add an --all-docs mode to check-doc-skill-refs.sh that scans the union of the pinned doctrine files PLUS the full LIVE docs/** set (scripts/lib/docs-scope.sh), ratcheted by a new filename-pinned shrink baseline (scripts/.docs-skill-refs-baseline). Two-way ratchet: a non-baselined live doc with a dead `/skill` ref FAILS; a baselined file that no longer offends FAILS demanding a prune. Detection stays slash-syntax + headings only (never bare skill names). Default (no-flag) behavior is byte-identical. docs/SKILL-ROUTER.md (the curated router) is covered by --all-docs (a live docs/** file, never baselined) so a dead ref there FAILS strict, without perturbing the byte-identical default doc count. seed.go docs.skill-refs row: Match widened to docs/** + the baseline + the lib; Args set to [--all-docs --strict]. Burn-down (long-tail only): repointed retired `/retro`->/post-mortem, `/vibe`->/validate, `/ratchet`->/flywheel, `/research-multi`->/research, `/implement-wave`->/crank, and reworded the retired `/dream` across 13 docs/levels + docs/workflows + docs/philosophy pages, then pruned them from the baseline (91 -> 78 offenders). Owner-locked pages (comparisons/getting-started/positioning) stay baselined. Bats twin tests/scripts/check-doc-skill-refs-all-docs.bats covers all the modes.
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