Jira brief intake

Skill: jira-brief-intake

This is choreography, not invention. It is the adapter between a tracker and the brief-intake pipeline, for teams that keep the what/why of a body of work in a Jira epic and its child issues rather than in a written brief. It composes two things that already exist:

• jira skill (sibling in this pack) — every Jira read. You never write a raw Jira REST call here, and this skill is read-only: it never transitions, comments, attaches, creates, updates, or deletes.
• receive-brief skill (shipped by the host repo's core pack; resolved by name through the harness) — the brief inbox: it elicits missing load-bearing fields conversationally, decomposes the brief into independently-shippable slices, and executes each through new-spec → work-loop. This skill does not re-explain or re-implement any of that — least of all elicitation. It assembles the brief from Jira and hands off.

The one thing this skill owns is the Jira → brief mapping that neither side can do alone: receive-brief knows nothing about Jira, and jira knows nothing about briefs. If you find yourself writing a Jira REST call, or interrogating the user for a missing Outcome, stop — the first belongs in jira, the second in receive-brief.

Cross-skill invocation — name, not path

This skill names sibling skills (jira, receive-brief, new-spec) by their name: field, never by path. Install locations vary by IDE and scope, and skills can be renamed at install time. Path coupling silently breaks every alternative layout.

The contract: when this skill says "via the jira skill: get-issue $KEY ...", the agent uses its native skill-dispatch mechanism to invoke the skill registered under that name with those arguments. In Claude Code that's the Skill tool (/<skill-name> or programmatic dispatch); in other IDEs it's the equivalent. If you find yourself writing ~/.claude/skills/jira/... or any other hardcoded path here, stop — look up the skill by name instead.

Install guidance for the named dependencies lives in manifest.json under deps.skills — that's a where to get them hint, not a runtime path.

Prerequisites

Before stage 1, confirm two things — they behave differently:

1. jira is installed and authenticated — a hard dependency. Invoke it: jira: check.

   • Exit 0 → proceed.
   • Exit 2 → the user must act. Tell them to run credential-setup themselves (it's interactive — do not run it for them), then stop. Do not dispatch any read into an auth failure.
   • There is no degraded path without jira — it performs every read this skill depends on.

2. receive-brief is installed — a soft dependency. Probe whether your harness can dispatch a skill registered under the name receive-brief.

   • Present → the normal flow (stage 3 hands off to it).
   • Absent → the graceful-degradation flow (stage 4). You still produce the brief; you just inline the decompose/execute instruction instead of handing off. Decide this now so stage 2 knows which shape to write.

Lifecycle

Stage 1 — Intake: pull the epic and its children

Fetch the epic with the fields a brief needs, via the jira skill:

get-issue $EPIC_KEY --fields "summary,description,labels,issuetype,status" --expand renderedFields

Then enumerate its children. Jira has no single "get children" verb, and the parent↔child relationship is named differently across flavors — so query both forms through the jira skill's search and use whichever returns issues:

# Cloud team-managed projects use `parent`:
search "parent = $EPIC_KEY ORDER BY created ASC" --fields "summary,description,issuetype,status"

# Server / Data Center and company-managed Cloud use the "Epic Link" field:
search '"Epic Link" = $EPIC_KEY ORDER BY created ASC' --fields "summary,description,issuetype,status"

"Epic Link" does not exist on team-managed Cloud and a JQL referencing it errors there; parent is empty for an epic on company-managed/Server. Try one, and fall back to the other when it errors on a missing field or returns zero rows. Never assume a single form — silently returning zero children is the failure this guards against.

Other intake shapes (kanban teams often have no epic):

• A board / sprint / JQL selection instead of an epic: the user gives you a JQL (or a saved-filter / board scope). The matched issues become the brief's stories. There is then no single parent to derive the Outcome from — record that as a gap for receive-brief to elicit (do not invent one).
• A single non-epic issue with no children: that is one feature, not a multi-feature brief. Stop and recommend new-spec (and, if it's a defect, jira-defect-flow). Ask before treating it as a brief — do not force a one-ticket scope into the intake pipeline.

Stage 2 — Map to a Shape B brief

Write a draft brief to docs/product/briefs/<slug>.md, where <slug> is kebab-case derived from the epic summary (it must match the filename and the Brief: back-link receive-brief later stamps on derived specs). If core is installed, copy its docs/product/briefs/_template.md; otherwise use the carried shape below.

The Jira → brief mapping is Shape B (story-list), because an epic with children is a story list:

Brief field	Jira source
Outcome	the epic's summary + description, in the user's terms (the problem and what changes for them)
Scope / Non-goals	the epic description / labels, where stated — never invented
Epic: pointer	the epic key (e.g. PROJ-100) — provenance back to the tracker, exactly what this field is for
User stories (US-n)	one per child issue (below)

Each child issue becomes one US-n line in this pinned format — the trace receive-brief will complete with Satisfies: US-n on derived spec acceptance criteria depends on it:

- **US-1.** (PROJ-101) As a <role>, I want <capability>, so that <benefit>.
- **US-2.** (PROJ-102) <child summary, carried verbatim when it isn't story-shaped>

The Jira key is a parenthetical immediately after the id — the slot the bare template line leaves undefined. Reshape the child's summary into the As a … I want … so that … grammar only when the source supports it; otherwise carry the summary verbatim and let receive-brief refine it during Elicit. Never invent a role or benefit the child issue does not state.

Leave Success metrics, Appetite, and any silent Scope to receive-brief — surfacing and filling those gaps is its Elicit stage, not yours. The Spec map's Status column is auto-derived downstream; leave it.

Stage 3 — Hand off to receive-brief (the normal flow)

Invoke the receive-brief skill by name, pointing it at the brief file you just wrote. From here, receive-brief owns everything:

• Elicit — it ingests the brief and asks the user for any missing load-bearing field (Outcome, Scope). A thin epic is normal input; it elicits rather than rejects. Do not pre-empt this by interrogating the user yourself.
• Decompose — it cuts the stories into independently-shippable slices and surfaces the cut for confirmation.
• Execute — it chains new-spec → work-loop per slice and stamps the Brief: / Satisfies: US-n back-links.

Your job ends at the handoff. Do not duplicate the Decompose/Execute stages.

Stage 4 — Graceful degradation (the receive-brief-absent flow)

When the Prerequisites probe found no receive-brief skill, do not stop — you have still produced a useful brief. Inline the following instruction for the agent to act on directly, and note that the downstream new-spec and work-loop skills may likewise be absent (if core isn't installed, none of them are) — fall back to the host repo's own spec/build process where they are:

Decompose & execute (inlined because receive-brief is not installed).

1. Elicit the gaps. The brief above may be missing its Outcome or Scope. Ask the user for those load-bearing fields — do not invent them. Offer defaults for Success metrics / Appetite; never block on them.
2. Decompose by shippability, not by component. Cut into slices each independently shippable and testable — one feature a build loop can carry end to end. Group the US-n stories into slices. Flag any epic-sized story for splitting; flag any Outcome no slice covers as a gap.
3. Surface the cut and wait for confirmation before authoring any spec.
4. Execute each confirmed slice through your repo's spec process (the new-spec skill if installed, else your repo's equivalent), then build it (the work-loop skill if installed, else your repo's loop). Stamp each derived spec with a Brief: back-link to this brief and a Satisfies: US-n marker on the acceptance criteria that satisfy a story.

Carried brief shape (used only when core's _template.md is absent)

Keep this minimal — headings + the US-n line format, not a full copy of the canonical template (which lives at docs/product/briefs/_template.md when core is installed):

# Brief: <one-line outcome>

- **Slug:** `<slug>`
- **Received:** <YYYY-MM-DD>
- **Owner:** <who owns this repo's slice>
- **Epic:** <JIRA-EPIC-KEY>

## Outcome
<the problem and the user-facing outcome — LOAD-BEARING; elicit if the epic is thin>

## Success metrics
<observable signals; offer a default if absent>

## Scope / Non-goals
**In scope:**
-
**Non-goals:**
-

## User stories
- **US-1.** (JIRA-KEY) As a <role>, I want <capability>, so that <benefit>.

## Spec map
| Spec | Status |
| --- | --- |
| `<feature-slug>` | <auto> |

Don't

• Don't write a raw Jira REST call, or re-implement a jira subcommand. If jira is missing a read verb you need, extend that skill — don't shim around it.
• Don't invoke any Jira write verb — create-issue, update-issue, delete-issue, transition, comment, attach. Intake is read-only. (The one example showing these is the banned list, not a usage.)
• Don't reimplement receive-brief's Elicit stage. Do not interrogate the user for a missing Outcome or Scope — produce the brief and hand off (or, in the degraded path, hand the eliciting instruction to the agent).
• Don't invent an Outcome, Scope, or story the Jira source doesn't state. A thin epic is fine — surface the gap; receive-brief elicits it.
• Don't force a single ticket into a brief. One issue is one feature → new-spec. A defect → jira-defect-flow.
• Don't become a cross-repo coordination hub. Carry the epic key as the Epic: pointer only; do not reimplement a tracker (own the slice).
• Don't hardcode a sibling skill or template path. Look skills up by name.

Edge cases

• No epic, just a JQL/board scope. The matched issues are the stories, but there's no parent for the Outcome. Record the missing Outcome as a gap and let receive-brief elicit it — don't fabricate one from the issue list.
• Epic with zero children found. Confirm you tried both child-query forms (stage 1). If genuinely empty, the epic is a one-liner with no decomposition — ask the user whether it's really a single feature (new-spec) or whether the children live under a different link type.
• Child issues that are themselves epics (a hierarchy deeper than one level). Flag them as epic-sized stories for splitting; don't silently flatten a sub-epic into a single US-n.
• Custom fields hold the real scope (some teams keep acceptance criteria in a custom field). Resolve names with jira's --expand names and map what's there; if the scope isn't in any field you can read, surface the gap.
• receive-brief present but new-spec/work-loop absent. receive-brief itself surfaces that gap when it tries to execute — you've done your job by handing off; don't pre-solve its downstream.

Examples

See references/examples.md for worked patterns: an epic-with-children happy path, a JQL/board selection, the single-non-epic-issue → new-spec case, and the receive-brief-absent degraded path.