best-practices-tau-dag

# Best Practices: Tau DAG Use this skill to make project-agent DAGs strict enough that Tau can dispatch, reject, or course-correct them without guessing from prose. Related skills to load when the DAG contains those work types: `tau`, `best-practices-prompt`, `best-practices-python`, `best-practices-react`, and `best-practices-subagent`. ## Core Rule Project agents should give Tau a `tau.dag_contract.v1` by default for multi-step work. The DAG should declare workflow intent, capability requirements, skill gates, immutable goal, targets, evidence, retry limits, and terminal boundaries. Tau should choose or reject specific subagents from those declarations. Do not hide orchestration policy in prose, issue comments, or prompts. ## Authoring Model Use this split of responsibility: 1. Project agent declares the DAG contract. 2. Tau validates required fields, graph shape, skill gates, model policy, and evidence requirements. 3. Tau selects an eligible subagent or blocks with `tau.dag_error.v1`. 4. Creator/worker subagents produce artifacts and receipts. 5. Reviewer/validator nodes compare outputs against the immutable goal and declared skill gates. 6. Only a human may change the immutable goal. Prefer capability-based nodes: ```yaml nodes: - id: frontend-coder role: coder work_type: react required_skills: - best-practices-react ``` Use a specific subagent only when the project agent has a concrete reason: ```yaml nodes: - id: script-writer agent: script-writer executor: local ``` ## Required DAG Fields Every non-trivial project-agent DAG must include: - `schema: tau.dag_contract.v1` - `dag_id` - `goal.goal_id`, `goal.goal_version`, `goal.goal_hash` - `target.repo` and `target.target` - `entry_node` - `terminal_nodes` - `limits.max_total_attempts` - `nodes[]` - `edges[]` - `required_evidence` - `fail_closed_on` Missing fields should be treated as authoring errors before dispatch. ## Goal Specificity Reject nebulous goals. A goal is underspecified if the DAG cannot determine: - what artifact or behavior should change; - which target repo, issue, file, or proof lane is in scope; - which evidence proves the goal; - what must fail closed. Bad: ```yaml goal: goal_id: make-it-better goal_version: 1 goal_hash: sha256:active-goal required_evidence: [] ``` Good: ```yaml goal: goal_id: issue-47-script-contract-loop goal_version: 1 goal_hash: sha256:active-goal target: repo: grahama1970/tau target: issue#47 required_evidence: - script_contract_json - reviewer_verdict - focused_tests fail_closed_on: - goal_hash_mismatch - target_changed - missing_required_evidence ``` ## Skill Gates If a node requires a best-practices skill, declare it explicitly and declare how the gate will be proven. Prompt node: ```yaml nodes: - id: prompt-author role: prompt-writer work_type: prompt required_skills: - best-practices-prompt skill_gates: best-practices-prompt: required_checks: - rationale-header - exact-output-schema - complete-input-output-example - rejection-criteria - deterministic-check ``` Python node: ```yaml nodes: - id: backend-coder role: coder work_type: python required_skills: - best-practices-python skill_gates: best-practices-python: required_checks: - uv-run-pytest - ruff - py_compile - non-mocked-sanity ``` React node: ```yaml nodes: - id: frontend-coder role: coder work_type: react required_skills: - best-practices-react skill_gates: best-practices-react: required_checks: - data-qid - data-qs-action - title - useRegisterAction - live-dom-manifest - cdp-screenshot ``` If a required skill lacks a corresponding `skill_gates` entry, Tau should fail before execution with `failure_code: missing_skill_gate`. ## Provider And Model Policy Any provider/model node must declare model policy. Do not let subagents infer model selection from prose. ```yaml nodes: - id: provider-review role: reviewer work_type: prompt-review executor: local provider: adapter: generic-provider-dag-node model_policy: provider: scillm model: qwen-or-approved-selector timeout_seconds: 120 max_retries: 2 output_schema: tau.agent_handoff.v1 on_non_json: retry_then_block ``` Missing provider/model fields should fail before dispatch with `failure_code: model_unspecified` or `failure_code: provider_policy_missing`. ## Course-Correction Errors Prefer fail-closed errors that a project agent can act on. Use `tau.dag_error.v1` for blocked DAG receipts. Good error payloads include: - `failure_code` - `failed_node` - `failed_agent` - `attempts` and `max_attempts` - primary alert evidence - `recommended_action.type` - `recommended_action.next_agent` - `recommended_action.reason` Common mappings: | Failure | Recommended action | | --- | --- | | `underspecified_goal` | Route to `goal-guardian` to rewrite the DAG goal/evidence. | | `missing_skill_gate` | Route to planner or reviewer to add concrete skill gates. | | `prompt_contract_invalid` | Route to `prompt-reviewer`. | | `model_unspecified` | Route to `goal-guardian` or planner for model policy. | | `invalid_command_json` | Repair command/subagent response, then retry or reroute. | | `reviewer_goal_hash_mismatch` | Route to `goal-guardian`; do not continue normally. | ## Review Checklist Before running a Tau DAG, check: - immutable goal hash is present and reused; - target is concrete and unchanged; - every node has a role or specific agent; - every executable node has an executor and command/provider policy; - every skill requirement has a skill gate; - prompt, Python, React, and provider nodes cite the relevant best-practices skill when applicable; - retry limits are numeric and bounded; - terminal nodes are explicit; - required evidence is named and testable; - failure conditions are in `fail_closed_on`; - expected reviewer nodes compare creator output against the immutable goal. ## Non-Goals This skill does not replace Tau runtime validation. It tells agents how to author and review DAG contracts so Tau can validate them deterministically. Do not use this skill to justify unbounded autonomy, hidden chain-of-thought inspection, or provider/model execution without receipts.