Arguments: $ARGUMENTS
brief
Turn agent work (a plan, a spec, a run's progress, a revision) into one document that its owner,
who does not write code, can read alone in a few minutes and then approve, reject, answer or
comment on. Deciding needs plain words; implementing needs precise ones: the precise detail
stays, in the appendix or a separate developer document.
Reader. Owns the outcome, knows the goals, does not know the technical context, this
conversation's working names or the tools. Reads alone, decides alone, often on a small window.
Not for: documents read by machines, legal text, notes between experts, developer guides,
explainer pages about finished work (that is visual-doc). This skill owns the words, the
document shapes, the decision block and the checks; visual-doc owns the look.
When. On request (/wanjang:brief), or when an orchestrating agent (the PM) reaches a
decision point or a reviewable state and its workflow calls for a document. Never start one
on your own initiative otherwise.
Language. Write in the user's language (the conversation's, or the one the caller names).
The rules hold in every language; the sentence checks have an English and a Korean track.
Files
${CLAUDE_PLUGIN_ROOT}/skills/brief/references/writing-rules.md: every writing rule with its
check (structure, decisions, words, honesty, tables, length, language tracks), the passes, and
the grep commands. Read it before writing.
${CLAUDE_PLUGIN_ROOT}/skills/brief/references/render.md: the HTML markup (the .decide
block, the top block, the receipt) and the Markdown form. Read it before rendering.
${CLAUDE_PLUGIN_ROOT}/skills/brief/references/reader-test.md: the rubric R1-R10, the
fresh-agent reader test, the real-person variant and the starting values to calibrate.
- The look is visual-doc's:
${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/assets/skeleton.html and
${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/assets/base.css, plus its
${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/references/components.md. Use them in place; never
copy them into this skill.
Workflow
- Pick the type and the form. Type from the arguments or the caller (A-D below); if the
user invoked it and the type is unclear, ask once with AskUserQuestion. Form: an HTML
page by default; Markdown when the reader works in a doc connector the session has (a
living document with comments). Both come from the same content.
- Before writing, keep two notes beside the document (same folder, not shown to the
reader): a facts list (every number, unit, date, count word, named amount, baseline, limit, risk, hedge and
decision taken from the source, each with where it came from) and an answer key for R1-R9
(
reader-test.md). Source = what was decided, built or found in this conversation, the run's
files and what the caller hands over. Anything else is not a fact: leave it out or mark it.
- Write the content (the types below, the rules in
writing-rules.md): top block, at most
four body sections, at most three decision blocks, the appendix.
- Render (
render.md). Files go in the run folder when a wanjang run called you, else in
the scratchpad under brief/<slug>.html or .md.
- Passes, in order, each separate: tells pass (remove the habits of machine prose; it may
not add or drop a fact), mechanical checks (
writing-rules.md: the commands and the D8 consistency check), then the
reader test by a fresh agent (reader-test.md). Fix the document, never the key; at most
two loops, then return with what still fails. R1-R4 failing blocks publishing.
- Publish or hand over. HTML: publish as visual-doc does when the session has the Artifact
tool (visual-doc's publish step, including loading artifact-design first), unless the caller
asked for a local file; otherwise return the path. Markdown: write it into the doc connector,
scaffold first (
render.md).
- Ask each decision with AskUserQuestion, paired as below, after the document is out and
with a link to it. A subagent cannot ask the user: return the questions ready to pass to
AskUserQuestion as they are, as JSON
{"questions": [{"header", "question", "multiSelect", "options": [{"label", "description"}]}]} plus the document's path, and the session that asks
writes the answers back.
- Write the answer back into the document as its receipt and republish the same path.
Every document: one frame
Top block → body (at most 4 sections) → appendix. Two levels only: a section and the blocks
in it (a decision block is a block, not a level; the table of contents lists sections, never
blocks). The appendix is the only fold: no fold inside a fold, no chain of links.
The top block stands alone: someone who reads only this part still decides correctly.
- h1: the answer or the question, one sentence.
- What we need from you: the decision (or approval) and the deadline, or "no deadline".
- We recommend: the option, with one reason.
- If you don't answer: what happens, and when. When choosing do nothing differs from not
answering, add If you choose to do nothing: what happens.
- One status word if the type has one; under it one line with the basis and the single main caveat.
A. Decision brief (one decision per document)
- Top block.
- The decision block (below). In HTML it sits in the opening, under the top block.
- Why now: what changed and what it means for the reader, 2-4 sentences.
- What happens next for each choice, one line each, including when it stops being undoable.
- Optional: 3-5 questions the reader will likely ask, each answered in more than one line.
- Appendix: evidence, method, sources, developer detail.
A changed decision is a new dated brief that names the one it replaces; the old one is never
edited again.
B. Approvable spec
- Top block: "Approve this to start building X. It takes about N. Later you can still change Y,
not Z."
- What you will be able to do: 2-5 claims, each one sentence (about 12 words, a starting
value) the reader can answer yes or no to, split by what the person sees or does, never by
file or component.
- What it will not do, each with its reason.
- How you will know it works: checks the reader can try themselves ("add a booking; it
appears in the calendar"), instead of acceptance criteria or priority labels.
- Open questions: who answers each and whether it blocks the start; blocking ones become
decision blocks.
- Cost and time, and the main risk in one sentence: what could go wrong, how badly, how
likely, what we will do about it, what we need from you.
- Appendix: components, files, data, commands.
Verdict: Approve / Request a change / Cancel.
C. Progress update
- Top block: one status word (on track, at risk, stuck), and its reason if it changed since the
last update.
- Done, Next, Problems: 1-3 sentences each, outcomes rather than tasks.
- Decisions needed: a link to each decision brief, or an inline decision block if small;
never a table of decisions.
No verdict; comments only. A problem that needs an answer gets a decision brief.
D. What changed since you read
- Top block: one sentence on what changed and why. If the change touches scope, cost or a
decision already made, the first line reads "This needs your approval again" and the
document carries the verdict again.
- Your comments: each comment the reader left, with what was done: changed, answered, or
not done and why.
- What changed: the changed parts in document order, each linked in place; unchanged parts
are not repeated.
- The host may offer views (with changes marked, as it is now, as it was); write the content, the
host draws the views. Before revising, save the current version under a dated name and never
edit that copy; approval applies only to the latest version.
Once a decision is answered or a spec is built, the same document becomes its receipt: each
claim is marked done, changed or not done, with the date. That is type D applied to an approved
document, not a fifth type.
The red line
Making a sentence plainer never changes a number, a unit, a baseline, a limit, a risk, or the
words "unverified" and "estimate". If the plain version would lose accuracy, keep the accurate
wording and split it into two sentences. The checker compares the facts list with the document;
a fact changed, added or dropped by rewording is a blocker.
The decision block
One per decision, at most three per document (the manager's progress page, /wanjang:manager, may carry up to four). The same fields in HTML and Markdown:
| Field |
Rule |
id |
short and stable (d1, d2); survives revisions; the wizard and comments use it |
question |
one sentence the reader can answer; label: at most 12 characters, the wizard header |
options |
2-3 action options, then do nothing; each: name (1-5 words, in the reader's terms, never a technical noun), changes (one sentence: what changes for the reader), cost, time, risk, undo (yes / until a date / no). A value you do not have is written "unknown", never left out |
recommended |
one option, listed first; one reason and one downside, one sentence each |
no_answer |
what happens if nobody answers, and when; it may differ from choosing do nothing ("the work waits" vs "we go ahead with the recommendation on "): state both |
owner, by |
who decides; the date, or "no deadline" |
answer |
after the reply: the option, the reader's comment, the date (the receipt) |
At least one real option you do not recommend; do nothing always has its cost. A document that
recommends says so; it never poses as a neutral comparison.
Pairing each decision with one question
AskUserQuestion takes 1-4 questions per call and 2-4 options per question, allows multiSelect,
adds "Other" (free text) by itself, and limits each header to 12 characters. Hence: at most 3
action options plus do nothing, and at most 3 decision blocks plus one verdict per document.
| In the document |
AskUserQuestion |
Decision block d1 |
header = label; question = question word for word; options = the block's options in the same order (recommended first, with "(Recommended)" in its label; do nothing last); each description = changes and the cost, one line; multiSelect off (the options exclude each other) |
| Verdict (spec, re-approval) |
"Approve ?"; options Approve / Request a change / Cancel; if comments are still open, Approve's description says how many |
| A comment on a passage |
no question: comments stay in the document, anchored by block id and an exact phrase |
| Progress update |
no question unless it holds a decision block |
A block with two action options gives a question with three options (recommended, the other, do
nothing); with three action options, four, the limit. Option label = the option's name (1-5
words), and only the recommended one adds " (Recommended)". The header (label, at most 12
characters) is different in every block of the document.
- Same
id, option names and order in the document and the question.
- An "Other" answer counts as Request a change on that block, never as approval.
- The answer goes into
answer and into the top block ("Decided on : "), and
that decision is closed in this document; changing it later takes a new brief that replaces it.
- A comment the reader marked as blocking prevents Approve; other open comments stay open. Before
an approval that would drop feedback the reader has not sent, say so.
- Proposed edits to text already approved are shown as suggestions to accept or reject, never
swapped in silently. Never resolve a comment thread the reader started.
Hard rules
- No secrets, tokens or internal addresses in the document (name a secret by its role). Scan
before publishing; publishing distributes it.
- Never invent a number, a name, a date or a behaviour. What the source does not say is written as
"the source doesn't say"; "not found" never becomes "does not exist".
- Revisions change only what was asked; say what else you would change and ask first.
1---2name: brief3description: Write a brief a person who does not code can read in minutes and answer (a decision brief, an approvable spec, a progress update, or what changed since they last read), and pair each decision in it with one AskUserQuestion. Use when the user or an orchestrating agent needs a non-developer to decide, approve or catch up on agent work. /wanjang:brief [decision|spec|update|changes] <subject>4argument-hint: "[decision|spec|update|changes] <subject>"5metadata:6 source: https://skillmd.com/skills/levx-me/brief7---89Arguments: $ARGUMENTS1011# brief1213Turn agent work (a plan, a spec, a run's progress, a revision) into one document that its owner,14who does not write code, can read alone in a few minutes and then approve, reject, answer or15comment on. Deciding needs plain words; implementing needs precise ones: the precise detail16stays, in the appendix or a separate developer document.1718**Reader.** Owns the outcome, knows the goals, does not know the technical context, this19conversation's working names or the tools. Reads alone, decides alone, often on a small window.2021**Not for:** documents read by machines, legal text, notes between experts, developer guides,22explainer pages about finished work (that is visual-doc). This skill owns the words, the23document shapes, the decision block and the checks; visual-doc owns the look.2425**When.** On request (`/wanjang:brief`), or when an orchestrating agent (the PM) reaches a26decision point or a reviewable state and its workflow calls for a document. Never start one27on your own initiative otherwise.2829**Language.** Write in the user's language (the conversation's, or the one the caller names).30The rules hold in every language; the sentence checks have an English and a Korean track.3132## Files3334- `${CLAUDE_PLUGIN_ROOT}/skills/brief/references/writing-rules.md`: every writing rule with its35 check (structure, decisions, words, honesty, tables, length, language tracks), the passes, and36 the grep commands. Read it before writing.37- `${CLAUDE_PLUGIN_ROOT}/skills/brief/references/render.md`: the HTML markup (the `.decide`38 block, the top block, the receipt) and the Markdown form. Read it before rendering.39- `${CLAUDE_PLUGIN_ROOT}/skills/brief/references/reader-test.md`: the rubric R1-R10, the40 fresh-agent reader test, the real-person variant and the starting values to calibrate.41- The look is visual-doc's: `${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/assets/skeleton.html` and42 `${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/assets/base.css`, plus its43 `${CLAUDE_PLUGIN_ROOT}/skills/visual-doc/references/components.md`. Use them in place; never44 copy them into this skill.4546## Workflow47481. **Pick the type and the form.** Type from the arguments or the caller (A-D below); if the49 user invoked it and the type is unclear, ask once with AskUserQuestion. Form: an **HTML50 page** by default; **Markdown** when the reader works in a doc connector the session has (a51 living document with comments). Both come from the same content.522. **Before writing, keep two notes** beside the document (same folder, not shown to the53 reader): a **facts list** (every number, unit, date, count word, named amount, baseline, limit, risk, hedge and54 decision taken from the source, each with where it came from) and an **answer key** for R1-R955 (`reader-test.md`). Source = what was decided, built or found in this conversation, the run's56 files and what the caller hands over. Anything else is not a fact: leave it out or mark it.573. **Write the content** (the types below, the rules in `writing-rules.md`): top block, at most58 four body sections, at most three decision blocks, the appendix.594. **Render** (`render.md`). Files go in the run folder when a wanjang run called you, else in60 the scratchpad under `brief/<slug>.html` or `.md`.615. **Passes, in order, each separate:** tells pass (remove the habits of machine prose; it may62 not add or drop a fact), mechanical checks (`writing-rules.md`: the commands and the D8 consistency check), then the63 **reader test** by a fresh agent (`reader-test.md`). Fix the document, never the key; at most64 two loops, then return with what still fails. R1-R4 failing blocks publishing.656. **Publish or hand over.** HTML: publish as visual-doc does when the session has the Artifact66 tool (visual-doc's publish step, including loading artifact-design first), unless the caller67 asked for a local file; otherwise return the path. Markdown: write it into the doc connector,68 scaffold first (`render.md`).697. **Ask** each decision with AskUserQuestion, paired as below, after the document is out and70 with a link to it. A subagent cannot ask the user: return the questions ready to pass to71 AskUserQuestion as they are, as JSON `{"questions": [{"header", "question", "multiSelect",72 "options": [{"label", "description"}]}]}` plus the document's path, and the session that asks73 writes the answers back.748. **Write the answer back** into the document as its receipt and republish the same path.7576## Every document: one frame7778**Top block → body (at most 4 sections) → appendix.** Two levels only: a section and the blocks79in it (a decision block is a block, not a level; the table of contents lists sections, never80blocks). The appendix is the only fold: no fold inside a fold, no chain of links.8182The **top block** stands alone: someone who reads only this part still decides correctly.83- h1: the answer or the question, one sentence.84- **What we need from you:** the decision (or approval) and the deadline, or "no deadline".85- **We recommend:** the option, with one reason.86- **If you don't answer:** what happens, and when. When choosing do nothing differs from not87 answering, add **If you choose to do nothing:** what happens.88- One status word if the type has one; under it one line with the basis and the single main caveat.8990### A. Decision brief (one decision per document)911. Top block.922. **The decision block** (below). In HTML it sits in the opening, under the top block.933. **Why now:** what changed and what it means for the reader, 2-4 sentences.944. **What happens next** for each choice, one line each, including when it stops being undoable.955. Optional: 3-5 questions the reader will likely ask, each answered in more than one line.966. Appendix: evidence, method, sources, developer detail.9798A changed decision is a new dated brief that names the one it replaces; the old one is never99edited again.100101### B. Approvable spec1021. Top block: "Approve this to start building X. It takes about N. Later you can still change Y,103 not Z."1042. **What you will be able to do:** 2-5 claims, each one sentence (about 12 words, a starting105 value) the reader can answer yes or no to, split by what the person sees or does, never by106 file or component.1073. **What it will not do**, each with its reason.1084. **How you will know it works:** checks the reader can try themselves ("add a booking; it109 appears in the calendar"), instead of acceptance criteria or priority labels.1105. **Open questions:** who answers each and whether it blocks the start; blocking ones become111 decision blocks.1126. **Cost and time**, and the main risk in one sentence: what could go wrong, how badly, how113 likely, what we will do about it, what we need from you.1147. Appendix: components, files, data, commands.115116Verdict: **Approve / Request a change / Cancel**.117118### C. Progress update1191. Top block: one status word (on track, at risk, stuck), and its reason if it changed since the120 last update.1212. **Done, Next, Problems:** 1-3 sentences each, outcomes rather than tasks.1223. **Decisions needed:** a link to each decision brief, or an inline decision block if small;123 never a table of decisions.124125No verdict; comments only. A problem that needs an answer gets a decision brief.126127### D. What changed since you read1281. Top block: one sentence on what changed and why. If the change touches scope, cost or a129 decision already made, the first line reads **"This needs your approval again"** and the130 document carries the verdict again.1312. **Your comments:** each comment the reader left, with what was done: changed, answered, or132 not done and why.1333. **What changed:** the changed parts in document order, each linked in place; unchanged parts134 are not repeated.1354. The host may offer views (with changes marked, as it is now, as it was); write the content, the136 host draws the views. Before revising, save the current version under a dated name and never137 edit that copy; approval applies only to the latest version.138139Once a decision is answered or a spec is built, the same document becomes its **receipt**: each140claim is marked done, changed or not done, with the date. That is type D applied to an approved141document, not a fifth type.142143## The red line144145Making a sentence plainer never changes a number, a unit, a baseline, a limit, a risk, or the146words "unverified" and "estimate". If the plain version would lose accuracy, keep the accurate147wording and split it into two sentences. The checker compares the facts list with the document;148a fact changed, added or dropped by rewording is a blocker.149150## The decision block151152One per decision, at most three per document (the manager's progress page, `/wanjang:manager`, may carry up to four). The same fields in HTML and Markdown:153154| Field | Rule |155|---|---|156| `id` | short and stable (`d1`, `d2`); survives revisions; the wizard and comments use it |157| `question` | one sentence the reader can answer; `label`: at most 12 characters, the wizard header |158| `options` | 2-3 action options, then **do nothing**; each: `name` (1-5 words, in the reader's terms, never a technical noun), `changes` (one sentence: what changes for the reader), `cost`, `time`, `risk`, `undo` (yes / until a date / no). A value you do not have is written "unknown", never left out |159| `recommended` | one option, listed first; one `reason` and one `downside`, one sentence each |160| `no_answer` | what happens if nobody answers, and when; it may differ from choosing do nothing ("the work waits" vs "we go ahead with the recommendation on <date>"): state both |161| `owner`, `by` | who decides; the date, or "no deadline" |162| `answer` | after the reply: the option, the reader's comment, the date (the receipt) |163164At least one real option you do not recommend; do nothing always has its cost. A document that165recommends says so; it never poses as a neutral comparison.166167## Pairing each decision with one question168169AskUserQuestion takes 1-4 questions per call and 2-4 options per question, allows multiSelect,170adds "Other" (free text) by itself, and limits each header to 12 characters. Hence: at most 3171action options plus do nothing, and at most 3 decision blocks plus one verdict per document.172173| In the document | AskUserQuestion |174|---|---|175| Decision block `d1` | header = `label`; question = `question` word for word; options = the block's options in the same order (recommended first, with "(Recommended)" in its label; do nothing last); each description = `changes` and the cost, one line; multiSelect off (the options exclude each other) |176| Verdict (spec, re-approval) | "Approve <title>?"; options Approve / Request a change / Cancel; if comments are still open, Approve's description says how many |177| A comment on a passage | no question: comments stay in the document, anchored by block id and an exact phrase |178| Progress update | no question unless it holds a decision block |179180A block with two action options gives a question with three options (recommended, the other, do181nothing); with three action options, four, the limit. Option label = the option's `name` (1-5182words), and only the recommended one adds " (Recommended)". The header (`label`, at most 12183characters) is different in every block of the document.184185- Same `id`, option names and order in the document and the question.186- An "Other" answer counts as **Request a change** on that block, never as approval.187- The answer goes into `answer` and into the top block ("Decided on <date>: <option>"), and188 that decision is closed in this document; changing it later takes a new brief that replaces it.189- A comment the reader marked as blocking prevents Approve; other open comments stay open. Before190 an approval that would drop feedback the reader has not sent, say so.191- Proposed edits to text already approved are shown as suggestions to accept or reject, never192 swapped in silently. Never resolve a comment thread the reader started.193194## Hard rules195196- No secrets, tokens or internal addresses in the document (name a secret by its role). Scan197 before publishing; publishing distributes it.198- Never invent a number, a name, a date or a behaviour. What the source does not say is written as199 "the source doesn't say"; "not found" never becomes "does not exist".200- Revisions change only what was asked; say what else you would change and ask first.