---
description: Create or update a repo-backed Brief — a long-form idea document committed as a markdown file under doc/ideas/. NOT a Comm Hub / CapCom comment. Use to capture an idea in the repo before promoting it to an Epic.
---

# /kit:brief

A **Brief** is a repo-backed idea document: a long-form description of a problem/opportunity written as a **markdown file committed to the repo** under `doc/ideas/<slug>.md`. It is the structured alternative to a free-form thought when the idea has enough shape to write down. Briefs get promoted to Epics on the Roadmap once they're DECIDED.

**A Brief is a FILE, not a comment.** Do NOT post Briefs to the LaunchSecure Comm Hub / CapCom via `communication_write`. Briefs live in the repo and travel through git like any other source artefact. (An earlier version of this skill posted Briefs as Comm Hub comments — that was wrong; Briefs are file commits.)

Parse `$ARGUMENTS`:
- **subcommand** (required) — `new` | `update` | `list` | `show`.
- For **new**: `<title>` (required), `--from=discussion:<id>` to seed body from an existing discussion thread, `--dir=<path>` to override the default `doc/ideas/` location.
- For **update**: `<slug-or-path>` and either a body description (re-generates body) or `--append=<text>` to add a section.
- For **list**: `[--dir=<path>]` — defaults to listing `doc/ideas/`.
- For **show**: `<slug-or-path>`.

Examples:
- `/kit:brief new "Channels for Comm Hub"`
- `/kit:brief new "Roadmap nav" --from=discussion:cmt_abc123`
- `/kit:brief list`
- `/kit:brief show launch-watch`
- `/kit:brief update launch-watch --append="Resolved: use the Slack metaphor not Teams."`

## Location

- **Default directory**: `doc/ideas/` at the repo root.
- **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 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. For **new**, check `doc/ideas/<slug>.md` does not already exist. If it does, surface it and ask whether to `update` instead — do NOT overwrite silently.
3. No MCP, no network, no Comm Hub calls. This skill only touches the filesystem + git.

## 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. 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 to a file, never posted back).
2. Use launch-chart (`read_graph`, `grep_nodes`) to populate the References section with real code paths — don't invent them.
3. **Write the file** to `doc/ideas/<slug>.md` with the Write tool.
4. Print the path written. 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>` to a file under `doc/ideas/` (or the `--dir` override). If nothing matches, list candidates and stop.
2. If `--append=<text>`, Read the 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

List `doc/ideas/*.md` (or `--dir`). Render one line per brief: `slug  status  title` — read each file's `# Title` and `**Status**:` line to fill those columns.

### show

Read the file and print its contents as-is, no transformation.

## Constraints

- **A Brief is a file, never a Comm Hub comment.** Do NOT call `communication_write` / `communication_update` to create or store a Brief. Reading a `--from` discussion seed is the only allowed Comm Hub touch, and it's read-only.
- **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 the brief the user asked for, but 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."
