@ngocsangairvds/vsaf 4.1.7 → 4.1.9

package/skills/vds-skill/vds-scripts/docs/vi/agents/how-to/03-memory-cross-agent.md

@@ -1,243 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# Using VDS AI Memory from External Agent CLIs
-
-This guide covers how external agent runtimes — Codex, OpenCode, and Qwen — can
-read from and write to VDS AI Memory using the `vds-cli memory` subcommand.
-
-## Prerequisites
-
-The VDS AI Memory API must be running and reachable. Start the active runtime stack if needed:
-
-```bash
-cd WHO-project/vds-scripts/memory_orchestrator
-docker compose --profile dev --profile mem0 up -d
-```
-
-This starts the active memory runtime stack from `memory_orchestrator/`.
-
-> `WHO-project/vds-ai-memory/` is historical/archive-only and should not be used for current startup or runtime guidance.
-
-## Runtime Environment Resolution
-
-| Variable | Purpose | Default |
-|---|---|---|
-| `VDS_MEMORY_API_URL` | Explicit base URL of the memory API | If unset: `http://localhost:${API_PORT:-8000}` |
-
-`vds-cli memory` loads `~/.vds/.env` automatically. Set an explicit URL only
-when the runtime is on a non-default host/port:
-
-```bash
-export VDS_MEMORY_API_URL="http://localhost:8010"
-```
-
-> **Note:** The memory API does not require an API key in its default
-> local-dev configuration. For current runtime/deployment guidance, prefer
-> `WHO-project/vds-scripts/memory_orchestrator/README.md` and the canonical spec
-> triplet under `.gpt-5.4/specs/vds-ai-memory/`.
-
-## Storing a Decision
-
-```bash
-# Store a decision scoped to a project using tags
-vds-cli memory store "decided to use Kafka for async event dispatch" \
-  --category business-logic --importance high \
-  --tags PAR,architecture,kafka
-
-# Minimal store
-vds-cli memory store "merchant-billing uses Spring Boot 3.2"
-```
-
-## Searching Memories
-
-```bash
-# Semantic search across all memories
-vds-cli memory search "kafka event dispatch" --limit 5
-
-# Filter by category
-vds-cli memory search "auth patterns" --category business-logic --limit 10
-```
-
-## Usage from Each Agent CLI
-
-All agent CLIs that can run shell commands can call `vds-cli` directly.
-Inherit `~/.vds/.env` via the shell session that launches the agent. Set
-`VDS_MEMORY_API_URL` only if you need an explicit override.
-
-### Codex
-
-```bash
-codex exec --skip-git-repo-check -m gpt-5.4 "your prompt here"
-```
-
-Within the Codex session, the agent runs shell commands:
-
-```bash
-vds-cli memory store "Codex discovered that merchant-report uses JPA auditing"
-vds-cli memory search "merchant-report auditing"
-```
-
-### OpenCode (Z.AI / GLM)
-
-```bash
-opencode run -m "zai-coding-plan/glm-5.1" "your prompt here"
-```
-
-The OpenCode agent shell-executes:
-
-```bash
-vds-cli memory store "OpenCode: PAR project checklist page is 88722450" \
-  --category business-logic --importance high
-vds-cli memory search "PAR checklist"
-```
-
-### Qwen
-
-```bash
-qwen -m qwen3-coder "your prompt here"
-```
-
-Qwen agents call:
-
-```bash
-vds-cli memory store "Qwen: insurance hexagonal boundary violations found in 3 repos"
-vds-cli memory search "hexagonal boundary violations"
-```
-
-## Project Scoping via Tags
-
-To keep memories scoped to a project, include the project key as a tag:
-
-```bash
-# Store scoped to project PAR
-vds-cli memory store "billing service auth pattern confirmed" \
-  --tags PAR,billing,auth
-
-# Search within PAR context (post-filter by tags)
-vds-cli memory search "billing auth" --limit 10
-```
-
-## Health Check
-
-Before a long agent run, verify the memory service is reachable:
-
-```bash
-vds-cli memory health
-```
-
-Expected output: `{"status": "healthy", ...}`
-
-## Practical Rules
-
-- Store decisions immediately after they are made — do not batch at end of session.
-- Include project key, service name, and date context in the content string.
-- Keep content under 500 characters per memory for searchability.
-- Do not store secrets, credentials, or personal data.
-- Use `--importance high` for irreversible architectural decisions.
-
----
-
-## Python SDK: `vds_memory_client` (VAMI-003)
-
-Since VAMI-003, a standalone Python package `vds_memory_client` provides
-programmatic access to VDS AI Memory for any Python agent or script — no
-`vds-cli` installation required.
-
-### Installing
-
-```bash
-# From the VDS monorepo (worktree or vds-scripts)
-uv run --project WHO-project/vds-scripts/vds_memory_client python3 -c "import vds_memory_client"
-
-# Or add as a dependency in your pyproject.toml
-[tool.uv.sources]
-vds_memory_client = { path = "../../vds_memory_client" }
-```
-
-### Basic Usage
-
-```python
-import asyncio
-from vds_memory_client import VDSMemoryClient
-
-async def main():
-    import os
-
-    base_url = os.getenv("VDS_MEMORY_API_URL") or f"http://localhost:{os.getenv('API_PORT', '8000')}"
-    client = VDSMemoryClient(base_url=base_url, timeout=10.0)
-
-    # Health check
-    status = await client.health()
-    print(status)  # {"status": "healthy", ...}
-
-    # Store a decision
-    result = await client.store(
-        content="Decided to use Kafka for async event dispatch",
-        category="business-logic",
-        importance="high",
-        tags=["PAR", "architecture"],
-    )
-    print(result["memory_id"])
-
-    # Search
-    results = await client.search(query="kafka event dispatch", limit=5)
-    for m in results["results"]:
-        print(f"[{m['category']}] {m['content'][:80]}")
-
-asyncio.run(main())
-```
-
-### Session State Caching
-
-`VDSMemoryClient` caches the health-check result in `~/.vds/.memory-session.json`
-using an atomic write (`tempfile.mkstemp` + `os.replace`). This file is:
-- **Not** in iCloud (lives in `~/.vds/`, not `~/Library/Mobile Documents/`)
-- Safe for concurrent writes from multiple agent processes
-- Valid for 60 minutes by default before the client re-checks health
-
-### iCloud Path Compatibility
-
-`vds_memory_client` runs correctly from iCloud-backed project paths
-(e.g. `~/Library/Mobile Documents/com~apple~CloudDocs/...`). The key properties
-that make this safe:
-
-| Concern | How it is handled |
-|---------|-------------------|
-| Spaces in path arguments | Wrap variables in double-quotes: `"$CLAUDE_PROJECT_DIR/..."` |
-| Atomic session writes | Written to `~/.vds/` (outside iCloud), using `os.replace()` |
-| `uv run --project <path>` | Path passed as a quoted argument; uv handles spaces correctly |
-
-### Hook Integration (now via Claude Code plugins)
-
-**Status (2026-04-24)**: The `vds_hooks` Python package was retired by
-`vds-hooks-claude-plugin-packaging` Phase 6. Hook integration with VDS AI Memory
-now lives entirely in the **Claude Code plugin format**:
-
-- `WHO-project/vds-skills/plugins/vds-hooks-core/` — generic hooks
-- `WHO-project/vds-skills/plugins/vds-hooks-extras/` — VDS-specific hooks (memory, audit, agent context)
-
-Plugins are installed via `/plugin marketplace add` + `/plugin install` and fire
-automatically on Claude Code events (`SessionStart`, `Stop`, `SessionEnd`,
-`UserPromptSubmit`, etc.) — no manual `vds-cli` invocation required.
-
-For the HTTP proxy endpoints, see
-`WHO-project/vds-scripts/memory_orchestrator/` — those endpoints are
-independent of the Python-package retirement and continue to serve
-`POST /api/v1/hooks/session-context` and `POST /api/v1/hooks/session-persist`.
-
-For SDK-level memory access from your own scripts, use `vds_memory_client`
-(see "Python SDK" section above). For the canonical hook semantics + dual-path
-safety-net design, see the spec at
-`.gpt-5.4/specs/vds-hooks-claude-plugin-packaging/` (Phase 6 archive +
-predecessor `hooks.RETIRED-2026-05-02/`).
-
-### Environment Variables
-
-| Variable | Effect | Default |
-|----------|--------|---------|
-| `VDS_MEMORY_API_URL` | API base URL | If unset: `http://localhost:${API_PORT:-8000}` |
-| `VDS_HOOK_SESSION_MEMORY` | Set to `"0"` to disable session context hook | `"1"` |
-| `VDS_HOOK_MEMORY_PERSIST` | Set to `"0"` to disable persist-stop hook | `"1"` |
-| `VDS_HOOK_MEMORY_DECISIONS` | Set to `"0"` to skip decision extraction | `"1"` |

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

@@ -1,242 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# 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/vi/agents/how-to/08-semantic-search.md

@@ -1,16 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# How To Run Semantic Search
-
-Use the skill entrypoint and local references first:
-
-- [grepai-skill](../../../../vds-skills/skills/grepai-skill/SKILL.md)
-- [Advanced patterns](../../../../vds-skills/skills/grepai-skill/references/advanced-patterns.md)
-- [grepai commands](../../../../vds-skills/skills/grepai-skill/references/grepai-commands.md)
-
-Operational rule:
-
-- Start with semantic search to discover candidates.
-- Narrow with `rg` or `sg` once the search space is known.

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

@@ -1,36 +0,0 @@
-<!-- diátaxis: how-to -->
-
-<!-- TODO: translate — Vietnamese translation pending -->
-
-# 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/vi/agents/how-to/decision-tree.md

@@ -1,77 +0,0 @@
-<!-- diátaxis: how-to -->
-<!-- TODO: translate — Vietnamese translation needed -->
-
-# Tôi Đang Viết Loại Tài Liệu Nào?
-
-> **Lưu ý**: Tài liệu này cần được dịch sang tiếng Việt.
-> **Note**: This document needs Vietnamese translation. The English version is canonical.
-> English source: [docs/agents/how-to/decision-tree.md](../how-to/decision-tree.md)
-
----
-
-## Phương Pháp Một Câu Hỏi
-
-*(English content below — TODO: translate)*
-
-# 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`