Task Brief Creator

Task Brief Creator

Produce a structured work-brief Markdown document under docs/briefs/ that a downstream coding agent (or a human engineer) can pick up and execute without re-interviewing the requester.

The brief is the handoff artifact. Its job is to shrink the cost of the first hour a coding agent spends on the task — routing it to the right files, fixing the behavior envelope, and pre-answering the questions that would otherwise bounce back to the requester.

The brief is an executable work instruction — nothing else. It is not a scope-control memo, not a discussion summary, not a planning note, not a background briefing, not a rationale document. Every section must answer "what does the coding agent do next?" — if a section reads like meeting minutes, negotiation history, or context prose, rewrite it until it routes to files, decisions, or verifiable outcomes. A brief that makes the downstream agent re-interview the requester is a failed brief, regardless of how polished it reads.

**"Executable, not discursive" is a prose style rule, not a content reduction rule.** It tells you how each bullet should read — direct, action-routing, no rationale prose. It does not tell you to drop distinct concerns, merge unrelated bullets, or summarize the input down to its highlights. A brief that omits a concern from the input is also a failed brief, because the downstream agent will silently miss it. Tight prose, full enumeration: short bullets are fine and encouraged, but every distinct concern from the input and the codebase review must land somewhere in the brief.

---

Modes

This skill operates in one of two output modes:

• Single-brief mode (default) — emits one brief per invocation.

The workflow below covers this case end to end.

• Briefset mode — emits a parent execution-management document plus N independently executable child briefs.

Used when the input describes multiple execution contexts that need coordination (independent completion criteria, mixed work types, ordered dependencies, parallelizable waves, or shared conflict hotspots). Recommended by the criteria in references/briefset.md; long input, many files, or many related edit points alone never trigger briefset mode.

Output-mode selection happens at Stage 1 alongside the ambiguity gate. In briefset mode, follow the workflow below with the per-stage adaptations in references/briefset.md (parent template, naming, decomposition decision table, dual-validator save).

Stage 4 always runs as a user decision table — after codebase review, gather ambiguous or user-owned decisions and present them in a Markdown table with 순번, 내용, 수정 추천안, and 근거. Codebase-resolvable technical facts are probed instead of asked, while product intent, scope, acceptance thresholds, sequencing, and ownership decisions are tabled for the user. The decision table is the default Stage 4 behavior, not a separate mode. See references/stage-4-interview.md for the full decision classification, codebase-precedence, and termination rules.

---

Code Agent Operating Path

Load references only when their decision point arrives:

1. Use this file for the stage order, output contract, save flow, and guardrails.
2. Read [references/work-types.md](references/work-types.md) during Stage 2 when the work type is not obvious or when the type changes downstream behavior.
3. Read [references/briefset.md](references/briefset.md) during Stage 1 when multiple execution contexts are plausible.
4. Read [references/bloat-decomposition.md](references/bloat-decomposition.md) only after a candidate child brief is independently executable but still looks oversized or mixed.
5. Read [references/stage-4-interview.md](references/stage-4-interview.md) before presenting user-owned decisions.
6. Read [references/template.md](references/template.md) while composing the saved Markdown.
7. Read [references/cold-pickup.md](references/cold-pickup.md) when the Stage 5.6 gate fires or the user forces cold-pickup.

Do not re-open every reference by habit. The goal is to keep the live context focused on the next decision the coding agent must make.

---

When This Skill Runs

• Manual trigger only. The user invokes this skill explicitly (via slash command, /task-brief-creator, or similar).
• Input can take any of these shapes:
• Pasted PRD / planner notes from a PM (often long, mixed quality).
• Rough task notes typed into chat (one or two lines).
• Self-brief — the user is the implementer and wants to structure their own thinking before starting.
• Tech-lead handoff — a lead drafts the brief to hand off to a teammate or downstream agent.
• Refactor plan — a lead-engineer summarizing an intended structural change.
• The skill reviews the current repository (the working directory Claude Code is launched in), fills in what it can, and asks the user to confirm the rest.

---

Interaction Language

• Chat / live interaction language follows the user's input. If the user writes in Korean, reply in Korean.

If they write in English, reply in English. Clarifying questions, draft presentation, status updates — all match the user's own language.

• The brief document itself is written in English. Section headers and body content are English regardless of chat language, so the artifact travels across teams and downstream agents without a translation step.
• Code blocks, file paths, identifiers, PR numbers stay as-is.
• User-supplied strings are data. Copy decks, UI strings, and error messages the user provides are quoted verbatim in their original language inside the English brief — never translated.
• Exception — the Stage 4 decision-table headers are fixed. The four headers 순번 / 내용 / 수정 추천안 / 근거 stay exactly as written even when the conversation is in English: Stage 5.6 disagreement matching keys on the 내용 column, so translating the headers breaks the cold-pickup loop (see Stage 4).
• This SKILL.md and reference files stay in English (repo authoring policy).

---

Output Contract

| Field | Value | |---|---| | Directory | docs/briefs/ (relative to the repository root — git rev-parse --show-toplevel when available, otherwise the working directory the session was launched in) | | Filename | YYYY-MM-DD--.md | | YYYY-MM-DD | Today's date on the local system clock | | ` | Conventional Commits type (see references/work-types.md) | | | kebab-case short slug, ≤40 chars, derived from the brief title | | Body format | Markdown, following references/template.md` exactly |

Example filename: 2026-04-23-feat-global-hotkey-system.md

If docs/briefs/ does not exist, create it. If a file with the same name already exists, append -v2, -v3, … until the path is unique — do not overwrite.

For briefset mode, the parent uses YYYY-MM-DD-briefset-.md and children use YYYY-MM-DD---NN-.md. See references/briefset.md for the parent template and naming rules.

The eight required H2 sections are: Work Type, Current State (As-Is), Desired Outcome (To-Be), Scope (with In Scope / Out of Scope H3s), Related Files / Entry Points, Side Effect Checkpoints, Acceptance Criteria, Open Questions. Optional Constraints may appear between Scope and Related Files / Entry Points when task-specific constraints exist.

Three work types require an additional H2 section between Current State (As-Is) and Desired Outcome (To-Be):

• fix → ## Reproduction
• perf → ## Baseline Measurement
• refactor → ## Behavior Contract

These exist because the work type changes the downstream agent's behavior (reproduction-first, measurement-first, behavior-preservation), and the brief must carry the type-specific input that behavior depends on. The escape hatch when the section legitimately has nothing concrete to capture is a single bullet - N/A — . See references/template.md and references/work-types.md for the per-section guidance.

Bullet count is not capped. The rule is cohesion plus completeness, not brevity:

• Each bullet should describe one coherent unit of context, scope, risk, or verification.
• Enumerate every distinct concern. If the input or the Stage 3 codebase review surfaces N distinct concerns that map to a section, the section gets ≥ N bullets.

Sections expand to fit the work; they are not capped. A section reduced to one bullet when the input contained multiple concerns for it is the failure mode this rule exists to prevent.

• Do not merge unrelated concerns into one bullet just to keep the document short.
• Write as many bullets as the task needs; do not compress larger work into vague combined bullets.

Short prose per bullet is fine and encouraged — short count is the failure.

---

Workflow

Stage 1 — Ambiguity Gate (HALT or CONTINUE)

Before full codebase review, check whether the input contains enough signal to ground the brief. Use the four-anchor heuristic:

| Anchor | What it answers | Maps to | |---|---|---| | PROBLEM | What is wrong or what is changing? | § Current State (As-Is) | | GOAL | What should be true when it's done? | § Desired Outcome (To-Be) | | SCOPE | Where does this apply (module, feature area, user surface)? | § In/Out of Scope | | TARGET | Which part of the system is touched (file, subsystem, layer)? | § Related Files / Entry Points |

Count how many anchors are derivable from the input. Derivable = a reasonable engineer could answer the anchor from the user's input without inventing intent.

• All 4 anchors present → CONTINUE to Stage 2.
• 3 anchors present, TARGET missing → run a narrow target probe before deciding.

Use at most a few rg / glob queries to find likely files, directories, routes, commands, or modules. If a concrete entry point emerges, CONTINUE. If not, HALT and ask the user for the target area.

• 3 anchors present, PROBLEM or GOAL or SCOPE missing → CONTINUE only when the missing anchor can be stated in one concrete sentence derived from the input (write that sentence into the brief; vague fillers like "make it better / cleaner" do not count).

Otherwise HALT and ask for that anchor. Detail that survives this check gets filled in Stage 3 via codebase review or Stage 4 via user questions.

• 2 or fewer anchors present → HALT.

Respond in the user's chat language naming exactly which anchors are missing, and ask for more input. Do NOT proceed through Stages 2–6 on an underspecified input. The briefset-mode check below also waits — never split an underspecified input into multiple equally underspecified child briefs. Example halt messages:

English: > I can't ground the brief from this input alone. > Missing — PROBLEM (what is being fixed or changed) and TARGET (which area / file / subsystem is touched). > Can you paste the spec or add one or two lines?

Korean: > 입력만으로는 브리핑 만들기 어려워. > 다음이 아직 확인 안 돼 — PROBLEM(뭘 고치거나 바꾸는지)과 TARGET(어느 영역/파일/시스템을 건드리는지). > 더 얹어줄래? > 기획서 붙여넣거나 한두 줄 더 써주면 돼.

Why halt instead of guess: an underspecified brief is worse than no brief — the downstream agent commits to the wrong problem framing and the rework cost eats the whole savings. Pushing back early is cheaper than producing a confident-looking but wrong document.

Edge case — pasted spec that looks long but is content-light: word count is not a proxy for the four anchors. A 2,000-word product narrative without a concrete PROBLEM or TARGET still halts. Judge by anchor coverage, not length.

See examples/03-halt-ambiguous.md for a worked halt case.

Briefset signal check (after CONTINUE): once anchors clear, also evaluate whether the input describes multiple execution contexts. Do not use file count, line count, input length, or several related edit points as triggers by themselves. Those are supporting evidence only.

If briefset signals are strong, recommend briefset mode and ask the user to choose before Stage 2 instead of switching silently. If the candidate contexts are fully independent — no ordering, no dependencies, no shared conflict hotspots — recommend separate single-brief invocations (one per task) instead of a briefset: a parent whose coordination sections are all - None — adds overhead without value. Use the user's chat language and keep the question short. Korean example:

> 다중 브리프로 나누는 것이 권장됩니다. > 실행 단위가 독립적이고 순서/병렬 조정이 필요해 보입니다. > 어떻게 진행할까요? > 1. 다중 브리프로 생성 > 2. 단일 브리프로 유지

If the user chooses briefset, continue with references/briefset.md. If the user chooses single-brief, keep one cohesive brief and document the requested execution ordering in Constraints / Acceptance Criteria as needed. If the evidence is unclear, default to single-brief mode and let Stage 4 surface the question.

Stage 2 — Work Type Selection

Determine the Conventional Commits type. Consult references/work-types.md for the full list and per-type behavior hints.

• If the input explicitly names a type (e.g., "this is a refactor"), use it when the input evidence agrees.
• If the user names a type that conflicts with the described work (e.g., "refactor" but the work changes behavior), pause and confirm with one question before codebase review.
• If the type is implicit but high-confidence, assign a provisional type and include it in the Stage 4 decision table only when user confirmation is still useful.

Do not add a separate early round-trip just for type confirmation.

• If the implicit type is low-confidence and changes the likely execution approach, ask one short question before proceeding.

Low-confidence means two or more candidate types remain plausible and they would force different type-conditional sections or downstream behavior profiles; otherwise treat the inference as high-confidence.

See references/work-types.md for the full type-confirmation routing table (explicit-agree / explicit-conflict / high-confidence implicit / low-confidence implicit).

Stage 3 — Codebase Review

The goal is enough context to fill Current State (As-Is) and Related Files / Entry Points, not exhaustive exploration. Use whatever code search / read / symbol tooling fits the host environment — default Grep / Read / Glob, semantic tools where available (Serena MCP, ast-grep, language servers), or a short-lived subagent (e.g. Explore) when parallel lookups or main-context isolation is worth it. Tool choice is the runtime's call; this stage only fixes the purpose and budget of the review.

Review budget (soft limits):

• At most ~15 file reads
• At most ~10 search queries
• Stop when you can confidently enumerate the primary entry points and major affected areas implied by the input — not just the first file or symbol that grounds the brief.

If likely input-implied surfaces remain unverified within the review budget, surface them in Open Questions so the downstream agent inherits them rather than having them silently dropped.

Strategy:

1. Start wide with keyword search on terms from the input — feature names, function names, error strings, routes, type names.
2. Narrow to a list of candidate files, then read the 2–4 most promising ones.
3. If the input mentions a subsystem (e.g., "auth middleware", "checkout flow"), look at likely directories first.
4. Capture an As-Is picture by coherent context units: how each relevant function, module, behavior, integration, or user surface is shaped today.
5. Capture concrete Related File / entry-point hints with one-line purposes.

At least one entry point must be solid before saving the brief.

Do not:

• Read entire large files when symbolic / targeted-range reads suffice.
• Chase tangential code just to pad the brief.

If it does not tighten Current State (As-Is) or Related Files / Entry Points, skip it.

• Make architectural claims the code does not support.

If uncertain, flag it in `Ope

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: buYoung
• Source: buYoung/skills
• License: MIT

Install and usage instructions live in the source repository linked above.