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).
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- brief
- description
- 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).
- argument-hint
- [the raw request, often a transcribed voice note]
- disable-model-invocation
- true
03 SKILL.md 正文
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*, pluginagents/**, trust roots, keychains, or release files. It is done in the same session withbin/check, one in-session lean-critic pass, and the branch policy inAGENTS.mdrule 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 withcontrol-loam, not a grep, in the formdocs/factory/CONTRACT.mdgives (Done checks for a rendered-project change). The author runs the block onmainby 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
04 同仓库更多 Skills
verify-loam
Prove a Loam change in a real rendered project: copier-render this checkout, then drive headless and interactive Claude Code sessions, stubbed Codex runs and copier updates in the render and capture hook, memory, deny-rule, update and check evidence. Use before shipping any seed, hook, settings or copier.yml change.
hypothesis-tree
Persistent hypothesis tree for multi-step, multi-session investigations. Use when a "why does X fail" question branches into sub-hypotheses that must survive across sessions, or when falsifiable claims need tracking with dated, linked evidence. Maintains one markdown file with add, update, review, and prune subcommands, each gated on verifying the cited evidence file exists and supports the claim. NOT for a single-session bug hunt, a one-command question, or general note-taking.
fable-prompting
Which Claude Fable 5.2 guide sections you can act on from a session, and which Claude Code already injects. Use before writing a Fable session prompt or brief.
catchup
Read-only session bootstrap briefing of git state, commits, handoff, tasks and red flags. Use when resuming work, starting a fresh session, or unsure of project state.
writing-for-agents
Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
wizard
Generate an interactive bash wizard that walks a human through steps only they can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.