@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/agents/how-to/04-using-progress-reports.md

@@ -1,240 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# How To: Generate Progress Reports
-
-## Prerequisites
-
-1. **Repos synced**: `vds-cli audit sync repos --bitbucket-project INSURANCE-AI`
-2. **BMAD knowledge graph**: Must exist at `~/.vds/cache/repos/INSURANCE-AI-project/bmad_ntbh/`
-3. **Database** (optional): Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` for persistence
-
-## Quick Start
-
-```bash
-# Structural-only report (fast, ~2s)
-vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync
-
-# Check your score
-vds-cli progress db status
-```
-
-## Common Workflows
-
-### Daily Score Check
-
-```bash
-# Generate report and check trend
-vds-cli progress report -p INSURANCE-AI --dimensions structural --skip-sync -q
-vds-cli progress db status
-```
-
-### Deep-Dive a Specific FR
-
-```bash
-# FR8 analysis in JSON
-vds-cli progress report -p INSURANCE-AI --fr FR8 --dimensions structural --format json --skip-sync -q
-```
-
-### Scripted/CI Usage
-
-Use `--quiet` (`-q`) and `--format json` for clean machine-readable output:
-
-```bash
-SCORE=$(vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
-  | python3 -c "import sys,json; print(json.load(sys.stdin)['overall_score'])")
-echo "Current score: $SCORE"
-```
-
-### Resume an Interrupted Run
-
-If a run fails mid-pipeline, the checkpoint is saved in the DB:
-
-```bash
-# The run_id is printed in the log output
-vds-cli progress report -p INSURANCE-AI --resume-run-id <uuid-from-failed-run>
-```
-
-### Topology Exploration
-
-```bash
-# List all FRs in the knowledge graph
-vds-cli progress topology -p INSURANCE-AI -q | jq '.fr_modules[].fr_id'
-
-# Count services
-vds-cli progress topology -p INSURANCE-AI -q | jq '.service_catalog | length'
-```
-
-## LLM Provider Selection (Phase 3)
-
-Use `--llm-provider` to control which LLM backend scores dimensions 7-8:
-
-```bash
-# Auto-detect from environment (default)
-vds-cli progress report -p INSURANCE-AI --llm-provider auto
-
-# Explicit provider
-vds-cli progress report -p INSURANCE-AI --llm-provider openai    # requires OPENAI_API_KEY
-vds-cli progress report -p INSURANCE-AI --llm-provider anthropic # requires ANTHROPIC_AUTH_TOKEN
-vds-cli progress report -p INSURANCE-AI --llm-provider ollama    # requires Ollama on localhost:11434
-
-# Disable LLM entirely (equivalent to --dimensions structural)
-vds-cli progress report -p INSURANCE-AI --llm-provider none --skip-sync
-```
-
-Auto-detect order: explicit `--profile` → `VDS_AUDIT_LLM_ENABLED=0` hard-disable → `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` env → structural-only.
-
-**Ollama is NOT auto-detected** — it must be requested via `--llm-provider ollama` explicitly. This is because Ollama's installed models may be cloud-routed, embedding-only, or reasoning models that need different token budgets, so aggressive auto-detection caused score regressions. When auto mode finds no provider, it leaves dims 7-8 as `None` and scores renormalize across structural dimensions only — **auto-detect is guaranteed to produce the same score as `--llm-provider none`**.
-
-## JSON Report Schema (Phase 3)
-
-Phase 3 reports include three new top-level keys in `--format json` output:
-
-```bash
-vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q \
-  | jq '{heatmap: .heatmap, repo_health: .repo_health, coverage: .dimension_coverage}'
-```
-
-- **`heatmap`**: List of FR × dimension objects — boolean pass/fail and numeric scores per FR
-- **`repo_health`**: Per-repo test ratio and `green`/`yellow`/`red` health indicator
-- **`dimension_coverage`**: Pass-rates and averages across all FRs (e.g. `service_exists: 0.9`)
-
-## Scripted Score + Coverage
-
-```bash
-vds-cli progress report -p INSURANCE-AI --dimensions structural --format json --skip-sync -q | \
-  python3 -c "
-import sys, json
-d = json.load(sys.stdin)
-print(f'Score: {d[\"overall_score\"]}')
-print(f'Doc chain: {d[\"dimension_coverage\"].get(\"doc_chain_complete\", \"N/A\")}')
-print(f'Recommendations: {sum(len(s[\"recommendations\"]) for s in d[\"sections\"])}')
-"
-```
-
-## Progressive Disclosure Modes (Phase 4)
-
-`--mode` picks a rendering tier. All four modes use the same underlying computation — only the rendered output differs:
-
-```bash
-# Exec: ≤20 lines. Slack pastes, email digests, GitHub status checks.
-vds-cli progress report -p INSURANCE-AI --mode exec --skip-sync -q
-
-# Summary: ≤100 lines. Standup review, code-review context, daily digest.
-vds-cli progress report -p INSURANCE-AI --mode summary --skip-sync -q
-
-# Standard: ~564 lines. Default. Byte-identical to pre-Phase-4 output (heatmap,
-# per-FR detail, trend, risk register). Use when daily development review.
-vds-cli progress report -p INSURANCE-AI --skip-sync -q   # --mode standard is implicit
-
-# Full: ~581 lines. Standard + stratified cluster sub-reports + appendices.
-# Use for quarterly audits, retrospectives, compliance packets.
-vds-cli progress report -p INSURANCE-AI --mode full --skip-sync -q
-```
-
-**Tip**: Start with `--mode exec` when piping into chat notifications and bump up to `summary` or `full` only when someone asks "why did the score move?"
-
-## CI/CD Quality Gates (Phase 4)
-
-Make progress report failures break your pipeline. `vds-cli progress report` exits with:
-
-- `0` — report generated, no gates tripped
-- `1` — runtime error (missing DSN, sync failed, crash)
-- `2` — **quality gate failed** (report file still written)
-
-```bash
-# Fail the build if overall score drops below 60
-vds-cli progress report -p INSURANCE-AI --skip-sync --fail-under 60 -q
-
-# Fail if any FR regressed by more than 15 points vs the previous run
-vds-cli progress report -p INSURANCE-AI --skip-sync --fail-on-regression -q
-
-# Compare against a specific historical run instead of "previous"
-vds-cli progress report -p INSURANCE-AI --skip-sync \
-  --fail-on-regression --baseline <run-id> -q
-
-# Combine gates — any trip exits 2
-vds-cli progress report -p INSURANCE-AI --skip-sync \
-  --fail-under 60 --fail-on-regression -q
-echo $?   # 2 if either gate fails
-```
-
-**Important**: Unlike SonarQube's `sonar-scanner` (which silently exits 0 even on gate failure unless you pass `-Dsonar.qualitygate.wait=true`), `vds-cli progress` honors gate flags immediately when set. The report file is always written before the non-zero exit, so your CI can still upload it as an artifact.
-
-**GitHub Actions example**:
-
-```yaml
-- name: Progress check
-  run: |
-    vds-cli progress report -p INSURANCE-AI --skip-sync \
-      --fail-under 60 --mode exec -q > progress.txt
-  continue-on-error: false   # exit 2 fails the step
-
-- name: Upload report
-  if: always()   # still upload when the step failed
-  uses: actions/upload-artifact@v4
-  with:
-    path: ~/.vds/cache/progress-reports/
-```
-
-## Bimodal Distribution / Stratified Clusters (Phase 4)
-
-When your FR scores split cleanly into "passing FRs" and "failing FRs" with no middle tier, the report emits a `bimodal_warning` block. This is the **valence-gap heuristic** — a UX signal, not statistical bimodality (ADR-Q7).
-
-Detection rules (all must hold):
-
-1. `total_frs ≥ 10`
-2. `medium == 0`
-3. `high_count > 0 AND low_count > 0`
-4. `min(high, low) / total ≥ 0.25` (dominance guard — kills skewed-unimodal false positives like 14/0/1)
-
-When detected, `summary` and `full` modes render **stratified sub-reports**: a high-cluster mini-report (passing FRs, avg score, weakest remaining dim, top remaining action) and a low-cluster mini-report (blocked FRs, dominant blocker, highest-priority fix).
-
-Extract cluster data from JSON:
-
-```bash
-vds-cli progress report -p INSURANCE-AI --format json --skip-sync -q \
-  | jq '.bimodal_warning'
-# {
-#   "detected": true,
-#   "stratification_variable": "service_exists",
-#   "high_cluster": {
-#     "label": "passing",
-#     "fr_ids": ["FR6", "FR7", "FR8", ...],
-#     "avg_score": 83.6,
-#     "dominant_blocker": "test_coverage",
-#     "top_recommendation_fr": "FR8"
-#   },
-#   "low_cluster": { ... }
-# }
-```
-
-**Interpretation**: A bimodal warning usually means *"the services that exist are healthy; the ones that are failing aren't built yet"* — your work is recipe-style scaffolding, not debugging the passing services. Use `dominant_blocker` to pick the next sprint focus and `top_recommendation_fr` as the starting FR.
-
-## Trend Regression Bucketing (Phase 4)
-
-When a previous run exists, the report bucketizes FR deltas vs baseline:
-
-| Δ score | Bucket | Render |
-|---------|--------|--------|
-| `Δ ≤ -15` | **Critical regression** | Loud callout + risk register entry |
-| `-15 < Δ ≤ -5` | Minor regression | Subtle callout |
-| `-5 < Δ < 5` | Noise floor | Ignored |
-| `5 ≤ Δ < 15` | Improvement | Noted |
-| `Δ ≥ 15` | Major improvement | Highlighted |
-
-Thresholds are intentionally simple for Phase 4. Phase 4.1 will upgrade to **Western Electric Rules** (3σ single-point, 2-of-3 at 2σ, 4-of-5 at 1σ) using rolling mean/stddev from `daily_scores`.
-
-## Troubleshooting
-
-| Problem | Solution |
-|---------|----------|
-| "no DSN provided" | Set `VDS_PROGRESS_STATE_DSN` in `~/.vds/.env` |
-| "bmad_ntbh not found" | Run `vds-cli audit sync repos --bitbucket-project INSURANCE-AI` |
-| Structlog lines in output | Use `-q` flag or redirect stderr (`2>/dev/null`) |
-| Score unchanged after code changes | Re-sync repos (remove `--skip-sync`) |
-| LLM not detected | Check `OPENAI_API_KEY` / `ANTHROPIC_AUTH_TOKEN` in `~/.vds/.env`, or use `--llm-provider none` |
-| CI shows exit 0 when score is low | Confirm `--fail-under <score>` flag is set — gates are opt-in |
-| `--fail-on-regression` not tripping | No baseline exists yet (first run) or baseline is outside the noise floor — pass `--baseline <run-id>` explicitly |
-| `bimodal_warning.detected: false` when I expected true | Check `total_frs ≥ 10`, `medium == 0`, dominance `≥ 0.25` — skewed distributions like 14/0/1 are rejected by design |
-| `--mode exec` output missing trend | Exec mode is deliberately ≤20 lines; use `--mode summary` for trend sparklines |
-| Standard mode output looks different | Should be byte-identical to Phase 3. File a bug if it's not — the G-Q11c structural invariants test guards this. |

package/skills/vds-skill/vds-scripts/docs/agents/how-to/08-semantic-search.md

@@ -1,46 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Semantic Search
-
-> Use semantic search to find code and documentation by meaning, not exact string.
-
-## Scope
-
-- **Does:** Search by concept, intent, and semantic meaning across code and docs.
-- **Does NOT:** Replace exact-string search (`rg`) when you know the symbol name.
-
-## CLI Entry
-
-```bash
-# Via unified router
-vds-cli research --help
-
-# Direct entry
-vds-cli research --help
-```
-
-## Key Commands
-
-| Command | Purpose |
-|---------|---------|
-| `search` | Semantic search |
-| `score` | Score evidence quality |
-
-## Workflow
-
-### Search by Meaning
-
-1. Run: `vds-cli research search "credential resolution pattern"`
-2. Review ranked results by relevance
-3. Filter by source: `--tool tavily`, `--tool grepai`
-
-```bash
-# Example: find how VDS handles retry
-grepai search "retry pattern with exponential backoff"
-```
-
-## Related
-
-- [Search Tools Reference](../reference/search-tools.md)
-- [Research Orchestrator](../reference/research-orchestrator.md)
-- [Memory Orchestrator](../reference/memory-orchestrator.md)

package/skills/vds-skill/vds-scripts/docs/agents/how-to/apply-phase3-migration.md

@@ -1,148 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# How to apply the Phase 3 alembic migration
-
-> Operator runbook to bring the live `sched.ecosystem_report_runs` schema into
-> alignment with the Phase 3 collector code merged at `412b067b`.
-
-**Time budget**: ≤ 10 minutes. **Risk**: low (additive migration; reversible).
-
-## Why
-
-Phase 3 of the ecosystem-daily-report (`edr-phase3/intelligent-watchdog`,
-merged at `412b067bcbb44c466cf62f5f62a11d0888090848` on 2026-04-30) added
-five new collectors and a Slack delivery step. Their results are persisted
-to **new columns** on `sched.ecosystem_report_runs`:
-
-- `llm_summary` (JSONB) — LLM provider/model token totals + USD cost
-- `dora_summary` (JSONB) — deploy frequency, lead time, CFR, time-to-restore
-- `trend_summary` (JSONB) — z-scores + sparklines + trend directions
-- `security_summary` (JSONB) — placeholder for SecurityAdvisoryCollector
-- `slack_delivered` (boolean), `slack_delivered_at` (timestamptz)
-
-Plus a new table `sched.ecosystem_report_archive` with a GIN-indexed
-`full_report` JSONB column for historical search.
-
-The migration file shipped at `412b067b` (revision `b2c3d4e5f8a9`,
-down-revision `a1b2c3d4e5f8`) but the live database still points at
-the Phase 2 head. **Until you run `alembic upgrade head`**, the cron
-that fires at 06:00 UTC will hand the SQLAlchemy model rows containing
-the Phase 3 columns to a database that does not have those columns,
-which leads to either persistence failure or silent loss of Phase 3 data
-depending on driver behavior.
-
-## When
-
-After the Phase 3 merge has landed on master (verify with
-`git log --oneline 412b067b -1`) and **before** you rely on persisted
-Phase 3 reports — i.e. before the next 06:00 UTC cron fire, or before
-the next manual `vds-cli scheduler schedules trigger-now ecosystem-daily-report`.
-
-## Prerequisites
-
-- `~/.vds/.env` populated (Postgres DSN, `VDS_SCHEDULER_ENABLED=true`).
-- Working tree at master `412b067b` or later.
-- Postgres 16 healthy (`docker ps | grep postgres` shows the
-  `vds-postgres` container with status `healthy`).
-
-## Steps
-
-### 1. Apply the migration
-
-```bash
-cd WHO-project/vds-scripts
-./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic upgrade head
-```
-
-Expected output:
-
-```
-INFO  [alembic.runtime.migration] Running upgrade a1b2c3d4e5f8 -> b2c3d4e5f8a9, add_phase3_report_columns
-```
-
-### 2. Verify the scheduler service is running
-
-```bash
-docker ps | grep scheduler                      # vds-scheduler container healthy
-vds-cli scheduler schedules show ecosystem-daily-report
-```
-
-The schedule should be listed with status `active` (not `paused`) and a
-`next_run` timestamp set to the next 06:00 UTC. If `Status: paused`, run
-`vds-cli scheduler schedules resume ecosystem-daily-report`.
-
-### 3. Trigger one workflow run for verification
-
-Don't wait for 06:00 UTC; force one fire so you can confirm the new
-schema is being written through:
-
-```bash
-vds-cli scheduler schedules trigger-now ecosystem-daily-report
-```
-
-Then check the workflow result:
-
-```bash
-vds-cli scheduler workflows list --status SUCCESS --limit 1
-```
-
-A new `reports/ecosystem/<today>-ecosystem-report.md` file should also
-appear in the worktree.
-
-### 4. Confirm the new row populates Phase 3 columns
-
-```bash
-vds-cli ecosystem report history --days 1
-```
-
-The latest row should show non-NULL `dora_summary`, `trend_summary`,
-`llm_summary`, `slack_delivered`, `slack_delivered_at`. NULL or
-`[unavailable]` payloads are *also* acceptable — what matters is that
-the cron successfully wrote through the migrated schema rather than
-crashing on `column does not exist`.
-
-> Caveat: `llm_summary` will report `[unavailable]` until the Phase 4
-> producer-wiring task lands (see the spec's "Phase 4 Followup — JSONL
-> Producer Wiring" note). This is graceful degradation per AC-P3.9, not
-> a regression.
-
-## Verification
-
-You will know the migration worked when:
-
-- `alembic current` shows `b2c3d4e5f8a9 (head)`.
-- `psql ... -c "\d sched.ecosystem_report_runs"` lists the six new
-  columns above.
-- `psql ... -c "\d sched.ecosystem_report_archive"` shows the new
-  archive table with a GIN index on `full_report`.
-- A fresh row from `vds-cli ecosystem report history --days 1` is
-  written without error after step 3.
-
-## Rollback
-
-If you need to revert (for example, a downstream consumer is not yet
-ready for the new columns):
-
-```bash
-# 1. Pause the schedule so the next cron does not crash on the
-#    pre-Phase-3 schema.
-vds-cli scheduler schedules pause ecosystem-daily-report
-
-# 2. Downgrade.
-cd WHO-project/vds-scripts
-./scripts/worktree_uv.sh run --project scheduler_orchestrator alembic downgrade -1
-```
-
-`alembic downgrade -1` reverts to `a1b2c3d4e5f8` (Phase 2 head), drops
-the six Phase 3 columns and the `ecosystem_report_archive` table.
-**Do not resume the schedule** until either you re-apply the migration
-or you check out a pre-`412b067b` master tip whose model code matches
-the Phase 2 schema.
-
-## See also
-
-- Spec post-merge runbook: `.gpt-5.4/specs/ecosystem-daily-report/tasks.md`
-  → "Post-Merge Operator Runbook"
-- DORA bootstrap criterion: `.gpt-5.4/specs/ecosystem-daily-report/design.md`
-  → "Bootstrap criterion (verdict locked 2026-04-30, Lane Alpha)"
-- Existing daily-report runbook: `docs/agents/how-to/run-ecosystem-daily-report.md`

package/skills/vds-skill/vds-scripts/docs/agents/how-to/choose-the-right-command-or-skill.md

@@ -1,34 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Choose The Right WHO Command Or Skill
-
-Use this guide when you know the task you want to perform but are not sure whether to start with a CLI command family or a specialist skill.
-
-## Step 1: Is this a platform-routing question?
-
-Use `vds-scripts-skill` when you need to:
-- find the right WHO command family
-- bootstrap the scripts workspace
-- understand which workspace capability owns a task
-- route to the correct specialist skill
-
-## Step 2: Route by task intent
-
-| Intent | Start Here |
-|-------|------------|
-| Run audit workflow, readiness, rerun, upload | `audit-orchestrator-skill` + `vds-cli audit` |
-| Evaluate README/API docs/security docs with LLM support | `llm-analysis-skill` |
-| Create or update specs | `spec-creation-skill` + `vds-cli spec` |
-| Develop a CLI/orchestrator | `cli-development-skill` |
-| Use Jira/Confluence/Bitbucket/Git | `vds-scripts-skill` + `vds-cli` integration family |
-| Validate docs, links, schemas, OpenAPI, diagrams, sheets | `vds-scripts-skill` + validation family |
-| Configure LSP | `lsp-skill` |
-| Analyze dependency cycles | `circular-dependency-skill` |
-| Research across local + external sources | `research-skill` |
-
-## Step 3: Follow canonical sources
-
-- Scripts: `WHO-project/vds-scripts/`
-- Skills: `WHO-project/vds-skills/skills/`
-- Do not edit `.agent/skills/` directly
-- For shared env/config/cache path behavior, use `../reference/portable-paths-and-config.md`

package/skills/vds-skill/vds-scripts/docs/agents/how-to/contribute-new-orchestrator.md

@@ -1,149 +0,0 @@
-<!-- diátaxis: how-to -->
-
-# Contribute a New Orchestrator
-
-## Prerequisites
-
-- Python 3.14+
-- uv installed
-- Docker (for testing with Postgres/Redis)
-- Familiarity with Typer and structlog
-
-## Workflow
-
-### 1. Create Branch
-
-```bash
-# From vds-scripts root
-git checkout -b feature/my-new-orchestrator
-```
-
-### 2. Scaffold the Orchestrator
-
-```bash
-# Create directory
-cd vds-scripts
-mkdir my_orchestrator
-cd my_orchestrator
-
-# Initialize uv project
-uv init --lib
-
-# Add dependencies
-uv add typer structlog pydantic-settings
-```
-
-### 3. Implement the CLI
-
-Create `my_orchestrator/src/my_orchestrator/cli.py`:
-
-```python
-import typer
-import structlog
-
-app = typer.Typer(help="My new orchestrator")
-logger = structlog.get_logger(__name__)
-
-@app.command()
-def run(input: str):
-    """Run my orchestrator."""
-    logger.info("starting", input=input)
-    # Implementation here
-    logger.info("completed", input=input)
-
-if __name__ == "__main__":
-    app()
-```
-
-### 4. Add Entry Point
-
-Update `pyproject.toml`:
-
-```toml
-[project.scripts]
-vds-my-orchestrator = "my_orchestrator.cli:app"
-```
-
-### 5. Register in Router
-
-Add to `vds_cli/src/vds_cli/router.py`:
-
-```python
-ORCHESTRATORS = {
-    # ... existing entries
-    "my_orchestrator": {
-        "module": "my_orchestrator.cli",
-        "path": "my_orchestrator",
-        "entry": "vds-my-orchestrator",
-    },
-}
-```
-
-### 6. Write Tests
-
-Create `tests/test_my_orchestrator.py`:
-
-```python
-import pytest
-from my_orchestrator.cli import app
-from typer.testing import CliRunner
-
-runner = CliRunner()
-
-def test_run():
-    result = runner.invoke(app, ["run", "test-input"])
-    assert result.exit_code == 0
-    assert "completed" in result.output
-```
-
-### 7. Add Documentation
-
-Create `docs/agents/reference/my-orchestrator.md` following the Diátaxis pattern.
-
-### 8. Update Ecosystem Files
-
-- Add to `AGENTS.md` router section
-- Append to `llms.txt`
-- Update `ECOSYSTEM-DOCS.md`
-
-### 9. Run Validation
-
-```bash
-vds-cli docs validate
-pytest
-```
-
-### 10. Commit and PR
-
-```bash
-git add .
-git commit -m "feat: add my-orchestrator orchestrator
-
-- Implements X functionality
-- Adds Y tests
-- Updates docs and AGENTS.md"
-```
-
-## PR Checklist
-
-- [ ] Tests pass (`pytest`)
-- [ ] Docs validated (`vds-cli docs validate`)
-- [ ] AGENTS.md line count ≤250
-- [ ] New doc has YAML frontmatter
-- [ ] Entry point registered in router
-- [ ] No hardcoded secrets
-- [ ] Error handling with context
-
-## Code Review Criteria
-
-Reviews check for:
-- Correct Typer/structlog patterns
-- Proper error handling
-- Test coverage ≥80%
-- Documentation completeness
-- No external API calls in tests (use mocks)
-
-## See Also
-
-- [Orchestrator Architecture](../reference/orchestrator-architecture.md)
-- [Add a Skill](../how-to/add-a-skill.md)

package/skills/vds-skill/vds-scripts/docs/agents/how-to/decision-tree.md

@@ -1,63 +0,0 @@
-<!-- diátaxis: how-to -->
-# What Kind of Doc Am I Writing?
-
-Quick decision tree for choosing the correct Diátaxis quadrant.
-
----
-
-## The One-Question Method
-
-Start at the top and answer each question. The first "YES" tells you the quadrant.
-
-```
-Q1: Is this for someone who has NEVER done this before?
-     → YES → TUTORIAL
-     → NO → Q2
-
-Q2: Is this a step-by-step recipe for a SPECIFIC task?
-     → YES → HOW-TO GUIDE
-     → NO → Q3
-
-Q3: Is this listing exact flags, contracts, or API surfaces?
-     → YES → REFERENCE
-     → NO → Q4
-
-Q4: Is this explaining WHY something works or background concepts?
-     → YES → EXPLANATION
-     → NO → Re-examine your scope. You may be mixing quadrants.
-```
-
----
-
-## Examples by Quadrant
-
-| Doc Title | Quadrant | Why |
-|-----------|----------|-----|
-| "Day 0: Install the WHO toolchain" | Tutorial | First-time learner |
-| "How to add a new skill to the catalog" | How-to | Specific task |
-| `vds-cli --help` auto-generated docs | Reference | Exact flags |
-| "Why we use Diátaxis for doc architecture" | Explanation | Background concept |
-
----
-
-## Common Anti-Patterns
-
-| Anti-Pattern | Fix |
-|--------------|-----|
-| Tutorial sneaks in unrelated tasks | Split to a separate How-to |
-| Reference doc tells a story | Delete narrative; keep only facts |
-| How-to explains the "why" | Move "why" to a linked Explanation doc |
-| Explanation gives step-by-step commands | Move commands to a How-to |
-
----
-
-## Header Convention
-
-Every `.md` in `docs/agents/` should include its quadrant as the very first line:
-
-```markdown
-<!-- diátaxis: tutorial -->
-# Title
-```
-
-Valid values: `tutorial`, `how-to`, `reference`, `explanation`