brief

<!-- Generated by Embody/Envoy - Do not remove this comment - sha:2e8aad6a73d41770 --> # Task Brief Compiler (/brief) Turn a conversational request into a reviewable task brief -- a markdown contract that front-loads everything this project expects from a task: which skills to load and when, where to build, what "done" verifiably means, and which gates apply. Work executed from a brief fails less and reviews faster because the discipline is stated BEFORE the first tool call instead of remembered mid-flight -- and the brief is portable: a fresh session or a sub-agent can pick it up without the conversation. ## When to compile a brief - Substantive work: multi-operator builds, visual output, panel UI, extensions, exports, externalization changes -- anything multi-step, or anything another session or sub-agent will help execute. - Skip it for trivial one-shot asks (one parameter change, one operator, a quick query). A brief that takes longer than the task is overhead, not discipline. Say so and just do the task. - The user invokes this skill explicitly with `/brief <request>`. The request may be vague, conversational English -- that is the point. Everything after `/brief` is the request; if it is empty, use the conversation's current ask. ## Step 1 -- Understand before you ask Restate the request in TouchDesigner terms. Resolve as much ambiguity as possible from the live project BEFORE asking the user anything: - `query_network` on `/` for the real structure -- never guess paths like `/project1` into a brief. - `execute_python` with `result = op.Embody.parent().path` for the default build container (never `/local`). - `get_externalizations` when the ask touches externalized operators. The Step 2 routing applies to these compile-time calls too: load `/mcp-tools-reference` before the session's first MCP call and `/td-api-reference` before `execute_python` -- the compiler does not get to skip the discipline it front-loads. Ask the user only for decisions that are genuinely theirs: aesthetic direction, target output and resolution, scope boundaries. Everything else gets a conservative default recorded in the brief (resolution <= 1920x1080, modest instance counts, bounded feedback) per the performance rules. If TD is not running, do not guess: mark each network-dependent field `resolve at execution` with the exact call that will resolve it. ## Step 2 -- Classify the task and derive the skill list Map the ask to task types, then list every skill the executing session must load BEFORE the first call it governs -- skills are prerequisites, not optional reference: | The ask involves | Brief must require | |---|---| | Any MCP tool call (first in session) | `/mcp-tools-reference` | | Creating operators | `/create-operator` | | Creating or editing annotations | `/manage-annotations` | | Building an extension | `/create-extension` | | Externalizing operators | `/externalize-operator` | | Writing TD Python | `/td-api-reference` | | HTTP fetch, background, or long-running work | `/td-api-reference` (Background and Long-Running Work) | | Visual or rendered output | `/visual-aesthetics` | | POPs, particles, GPU geometry | `/pop-networks` | | Movie or image-sequence export | `/movie-export` | | Custom parameters on a COMP | `/parameter-design` | | Diagnosing operator errors | `/debug-operator` | Also carry the standing contingencies: `/td-recovery` if connectivity breaks beyond ~15s of self-heal, `/multi-session-etiquette` the moment a `_peers` advisory or second session appears. If this project defines additional skills beyond the set above, route the ask through those too. ## Step 3 -- Write the brief Write to `briefs/<yyyy-mm-dd>-<slug>.md` at the project root. Create the folder if missing, and make sure `briefs/` is gitignored (Embody's generated .gitignore includes it; append it if this project predates that). Use exactly these sections -- a section with nothing to say states that explicitly rather than being dropped: ```markdown # Brief: <short title> - Date: <yyyy-mm-dd> - Status: draft | approved | in progress | done - Request (verbatim): "<the user's conversational ask>" ## Goal One paragraph, in TD terms, with a measurable outcome. ## Task types The classification from Step 2. ## Skills to load Ordered list; each loaded before the first call it governs. ## Anchors - Build container: <discovered path -- never /local, never guessed> - Existing ops involved: <exact discovered paths> - Placement: extend group right / new chain below, per network-layout ## Success criteria Only verifiable statements: "capture_top of out1 shows <X>, assessed"; "get_op_errors recurse=true clean"; "layout verify pass -- no overlaps, nothing at (0,0), forward wires"; "fps within 10% of baseline"; "test suite <name> green". Never "looks good" or "should work". ## Gates and stop conditions - Performance: get_project_performance baseline before building; stop thresholds per the performance rule. - Multi-session: scopes to claim (claim_scope) before big or destructive steps -- peers can join mid-task. - Externalized files: multi-step edits happen in an isolated worktree per the worktree-td-safety rule, with a drift check before landing. - Destructive or hard-to-reverse steps, each flagged for explicit user confirmation. ## Plan sketch 3-7 steps max, each ending in a verification. ## Out of scope Explicit non-goals -- what this task must NOT touch. ## Open questions Decisions needing the user, each with a proposed default. ## Deviations (filled during execution -- what was done differently, and why) ``` ## Step 4 -- Review, then execute FROM the brief - Present the brief path and a 3-5 line summary; get approval or edits before executing. If the user pre-approved ("just do it"), set Status to approved and proceed. - The brief is the contract: load the listed skills at the listed moments, honor the gates, and check every success criterion before declaring done. "Done" with an unmet criterion is a failed task, not a finished one. - Sub-agents and workflows get the brief (path or content) in their prompts -- they cannot see the conversation. - Keep Status current and record every deviation in Deviations as it happens, not after. ## Step 5 -- Feed failures back When a task goes wrong despite a brief, the compiler missed a gate. Record in the brief's Deviations what the brief SHOULD have required, and propose an edit to this skill (routing table or brief template) so the next brief catches it. This loop is how briefs get better; skip it and this skill stays exactly as good as it is today.