Brief

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:

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:

# 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.