# Brief

> Compile a conversational request into an Embody task brief (briefs/*.md): skills to load, discovered anchors, verifiable success criteria, and gates -- then execute the work from that contract. User-invoked via /brief.

- Skill: `dylanroscover/brief` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dylanroscover/brief`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dylanroscover/brief/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: dylanroscover (https://skillmd.com/u/dylanroscover)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dylanroscover/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.