# Brief

> Turn a raw request (often a transcribed voice note) into a brief: four lines and three fields, echoed back for correction, then handed to the ticket contract for a Track B ticket. Use when you type /brief or start a ticket from a request. Manual only. NOT for writing the ticket body itself (docs/factory/CONTRACT.md) or breaking a large request into several tickets (Track C).

- Skill: `samyakjhaveri/brief` (Agent Skill)
- Install (CLI): `npx get-skill add samyakjhaveri/brief`
- Raw SKILL.md: https://api.skillmd.com/api/skills/samyakjhaveri/brief/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: SamyakJhaveri (https://skillmd.com/u/samyakjhaveri)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/samyakjhaveri/brief

---


# brief

**Trigger:** user types `/brief [raw request]`. Manual-only (`disable-model-invocation: true`).
`$ARGUMENTS` is the raw request. If it is empty, ask for the request; never guess it.

You turn a raw request, often a transcribed voice note, into four lines and three fields, then echo them back for correction.
If you catch yourself improving the idea rather than the sentence, stop.

| You may | You may not |
|---|---|
| carry every constraint forward, verbatim | quietly drop a requirement because it looks hard or odd |
| fix grammar, cut rambling, order the steps | soften a strong ask ("rewrite" into "refactor a bit") |
| name the files you verified exist | invent files, numbers, or done conditions |
| ask one question when two readings produce different work | ask a second question, or ask one the codebase can answer |

The form:

```
<the ask, one imperative sentence, their words where they were specific>
Where: <files or dirs verified to exist>
Done means: <observable result: a passing command, a rendered element, a merged PR>
Out of scope: <what you were tempted to add, named so nobody adds it>
Track: A | B | C    Risk: low | high    Mode: build | figure-out    Open question: <at most one>
```

Before echoing, diff your draft against the request: every specific thing they said still there, anything in your draft they did not say deleted.
Do not address the harness in the brief; retry counts, models, and reviewers are configuration.

## Finding the open question

Run a blindspot pass: what in this request depends on a fact you have not read; what would a second engineer read differently; which named file, command, or number have you not verified; what does "done" look like to them that a command cannot see.
Keep the one question whose two answers produce different work.
Drop the rest or answer them from the codebase.

## When the solution is not known

`Mode: figure-out` is set when the ask is a question, names no solution, or says "help me figure out".
It is always Track C.
Stage 1 then opens with `/surprise-me` in panel mode, which the user types (it is manual-only), and a research pass against primary sources before any plan is written; the actors and order are in the `docs/factory/ARCHITECTURE.md` stage table.
When an open question is a fact a quick throwaway prototype could observe, build it in a scratch directory and let its output answer before you ask.
The design issue records the options considered, the evidence for each, and the ones rejected with a reason.

## Tracks, by blast radius

- Track A touches none of `seed/**`, `.claude/**`, `bin/factory*`, plugin `agents/**`, trust roots, keychains, or release files.
  It is done in the same session with `bin/check`, one in-session lean-critic pass, and the branch policy in `AGENTS.md` rule 1.
  The commit or PR body is the spec.
- Track B is one feature that fits one ticket.
  The brief becomes the ticket: the ask becomes Goal and why, Done means becomes the done-checks block, Out of scope carries over.
  When the target is Loam and the ticket changes what a rendered project does (`seed/**`, the hooks and settings under it, `copier.yml`), Done means names a behavior seen in a render, and its check drives that render with `control-loam`, not a grep, in the form `docs/factory/CONTRACT.md` gives (Done checks for a rendered-project change).
  The author runs the block on `main` by hand once and confirms every non-guard check prints FAIL; lint never runs it; round 0 repeats it on the runner.
  Then lint, then publish.
- Track C is several tickets.
  The brief becomes the top section of a design issue; stage 1 follows, then the stage-2 breakdown (`docs/factory/CONTRACT.md`, Publishing a breakdown).

Risk high means anything Track A excludes, plus outward-facing behavior.
It sets `codex-review: yes` on every ticket, which adds the Codex review stage after the graders (`docs/factory/LOOP.md`), and asks for a human diff read before merge.

## Worked brief, Track A

```
Remove the stale loam-s3 worktree registered at ~/Desktop/loam-s3.
Where: git worktree list shows it on branch lean/s3; PR #29 merged that branch.
Done means: git worktree list no longer shows loam-s3 and git status is clean.
Out of scope: pruning any other worktree; deleting the lean/s3 remote branch.
Track: A    Risk: low    Mode: build    Open question: none
```

## Worked brief, Track B

```
Add a static linter for factory tickets so a bad ticket is rejected before a loop starts.
Where: bin/ (new bin/factory with a lint subcommand), bin/factory.d/fixtures/ (committed by F0).
Done means: bin/factory lint rejects the pre-addendum S5 body, accepts the five contract-form bodies, and bin/check runs it.
Out of scope: running any check command; bin/factory run.
Track: B    Risk: high    Mode: build    Open question: none
```

