---
description: Create or update a repo-backed Brief — a long-form document committed as a markdown file under doc/<category>/. The server syncs it to a Comm Hub comment; you don't post it yourself. Use to capture a feature, architecture decision, requirement, or playbook in the repo.
---

# /kit:brief

A **Brief** is a structured long-form document that lives **both** as a markdown file in the repo at `doc/<category>/<slug>.md` **and** as a comment in the LaunchSecure Comm Hub. You write the file; the LS server's file-backed sync materializes the matching Comm Hub comment (favoring server → file convergence). See `doc/features/briefs.md`, `doc/playbook/runbooks/write-a-brief.md`, and `architecture/systems/briefs-discovery.md`.

**You write the file, the server does the sync.** Do NOT call `communication_write` / `communication_update` yourself — the brief becomes a Comm Hub comment automatically via the `discussion` handler once the file lands on the default branch (stamped with the category's `docCategory`, icon, and color). The only allowed Comm Hub touch from this skill is reading a `--from` discussion seed, and that's read-only.

## Categories

A Brief is **category-scoped** — the category determines its folder, icon, color, and where readers find it. Pick the one matching the question the reader is asking:

| Reader is asking… | Category | Folder |
|---|---|---|
| "What are we building / what does LS offer?" | `features` | `doc/features/` |
| "How does this system work / why built this way?" | `architecture` | `doc/architecture/` |
| "What rule must I follow?" | `requirement` | `doc/requirement/` |
| "How do I do X?" | `playbook` | `doc/playbook/` |
| "Something happened, I want to remember" | `incident` | `doc/incident/` |
| "Half-formed personal thought" | `ideas` | `doc/ideas/` (personal — see below) |

`features`, `architecture`, `requirement`, `playbook`, `shipping-logs` are framework defaults; `ideas` and `incident` are this project's custom categories (`.launch-secure.config`). Other projects may differ — read `.launch-secure.config` `docCategories[]` if unsure. **Do not default to `ideas`** — that's the personal-scratch category, not a dumping ground for real briefs. Shipping-log briefs are written by `/kit:ship`, not this skill.

Parse `$ARGUMENTS`:
- **subcommand** (required) — `new` | `update` | `list` | `show`.
- For **new**: `<title>` (required), `--category=<name>` (the category from the table; if omitted, infer from the title/intent and confirm before writing), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the resolved folder.
- For **update**: `<slug-or-path>` and either a body description (re-generates body) or `--append=<text>` to add a section.
- For **list**: `[--category=<name>]` to filter to one category, else lists briefs across all category folders. `[--dir=<path>]` to scan a specific dir.
- For **show**: `<slug-or-path>`.

Examples:
- `/kit:brief new "Comm Hub channels" --category=features`
- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123 --category=architecture`
- `/kit:brief list`
- `/kit:brief list --category=requirement`
- `/kit:brief show launch-watch`
- `/kit:brief update comm-hub-channels --append="Resolved: use the Slack metaphor not Teams."`

## Location

- **Folder**: `doc/<category>/` at the repo root, where `<category>` is resolved from `--category` (or inferred + confirmed).
- **Filename**: `<slug>.md`, where the slug is the kebab-cased title (e.g. "launch-watch — unified monitor" → `launch-watch.md`; keep it short — derive from the leading words, drop the subtitle after an em-dash).
- Override the folder with `--dir=<path>` only if the user asks.

## Preflight

1. Resolve the repo root (the working directory is the repo root in this project).
2. Resolve the category (from `--category`, or infer from the title and confirm with the user). Map it to `doc/<category>/`.
3. For **new**, check `doc/<category>/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently. Also check the slug isn't already used under a *different* category before creating a duplicate.
4. No `communication_write`. This skill writes the filesystem (+ optionally reads a `--from` seed); the server handles the Comm Hub side.

## Body template

When generating a NEW brief, write this skeleton as the file contents (plain markdown):

```markdown
# <Title>

**Status**: PROPOSED
**Owner**: <name or "unassigned">
**Module**: <module slug or "-">

## Problem

<1-2 paragraphs — what's broken or missing, who feels it, why now>

## Proposed direction

<1-3 paragraphs — the shape of the solution, not the implementation>

## Out of scope

- <bullets — what this brief deliberately does NOT cover>

## Open questions

- [ ] <bullets — what we still need to decide before this can become an Epic>

## Success looks like

<1-2 sentences — observable outcome, not "ship X">

## References

- <link to existing code, cited as `lib/foo/bar.ts:42` — use launch-chart (read_graph / grep_nodes) to find the right nodes; don't invent file paths>
```

## Write paths

### new

1. Resolve the category and folder (see Preflight).
2. Build the body from the template + the user's description (or the `--from=discussion:<id>` seed — fetch via `mcp__launch-secure__communication_read` and weave the relevant points into Problem / Proposed-direction; reading a seed discussion is fine, but the Brief itself is still written as a file, never posted back).
3. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
4. **Write the file** to `doc/<category>/<slug>.md` with the Write tool.
5. Print the path written and remind the user it materializes as a Comm Hub comment on the next default-branch push. Do NOT commit or push unless the user explicitly asks — leave it as a working-tree change for them to review and commit.

### update

1. Resolve `<slug-or-path>` with `node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug>` (it prints the resolved path on its `── <path> ──` header, or exits non-zero with candidates / an ambiguity list). If nothing matches, surface the candidates and stop; if ambiguous, ask which category.
2. If `--append=<text>`, Read the resolved file, append the text under a `## Update <ISO-date>` heading, and Write it back.
3. If a fresh description was passed, regenerate the body from the template + new description, show the user the diff briefly, then Write it back on confirmation.

### list

Run the bundled scanner — do NOT open and parse the brief files yourself:

```
node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" list [category]
```

It walks every `doc/<category>/` folder once and prints an aligned `CATEGORY  SLUG  STATUS  TITLE` table (pass a category to filter). Surface its output as-is; only read individual files if the user then asks to `show` one.

### show

Run the bundled scanner — it resolves the slug across all category folders and prints the file with a `── <path> ──` header:

```
node "$CLAUDE_PLUGIN_ROOT/skills/brief/briefs.mjs" show <slug-or-path>
```

Exit 1 = no match (it prints near-matches), exit 2 = ambiguous across categories (it lists them — re-run with the full path). Don't hand-glob `doc/` for the file.

## Constraints

- **You write a file; the server creates the comment.** Do NOT call `communication_write` / `communication_update`. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
- **Pick the right category.** The folder, icon, and color all follow from it. Don't default to `ideas`.
- **Plain markdown.** No HTML, no emojis unless the user wrote them.
- **One brief, one file.** Don't fragment a brief across multiple files — append via `--append` to keep the document continuous.
- **Don't commit or push on your own.** Write the file to the working tree and stop; committing/pushing is the user's call (per project conventions on no unauthorized pushes).
- **`doc/ideas/` is the user's personal scratch.** Write an `ideas` brief there only when the user explicitly asks for one, and do NOT reorganize, reclassify, or migrate other files in that directory. Promotion out of `doc/ideas/` is user-driven only.
- **Cite real code.** Use launch-chart node ids in the References section — don't invent file paths.
- **Don't auto-promote to Epic.** A Brief → Epic is a deliberate human action. Surface a hint at the end: "When DECIDED, promote this to an Epic on the Roadmap."
