jira-align-brief-intake v1.0B

Immutable. This exact content is served forever at /api/v1/blob/504487c1d2d829ea.

---
name: jira-align-brief-intake
description: Use this skill when the user points at a Jira Align Feature and asks you to turn it into a product brief or shippable specs — "intake Feature 1234", "turn JA feature 789 into specs", "pull this Jira Align feature into a brief". The skill fetches the Feature and its child stories/tasks/defects via the `jira-align` skill, maps them onto a Shape B product brief (Feature title/description → Outcome, children → `US-n` user stories tagged with their Jira Align IDs, Feature ID → `Epic:` provenance pointer), writes it to `docs/product/briefs/<slug>.md`, and hands off to `receive-brief` to elicit gaps, decompose, and build. 1-way intake only — never writes back to Jira Align. Use the field mapping in `references/field-mapping.md` (customize for your org before first use). Do NOT use for defects (use `jira-defect-flow` for Jira defects) or for individual Jira issues (use `jira-brief-intake` for Jira epics).
metadata:
  version: "1.0"
---

# Skill: jira-align-brief-intake

This is choreography, not invention. It composes two things that already exist:

- **`jira-align` skill** (sibling in this pack) — all Jira Align reads.
  You never write a raw Jira Align REST call here and never invoke a write
  verb.
- **`receive-brief` skill** (shipped by the host repo; resolved by name
  through the harness) — owns Elicit (fill missing Outcome/Scope
  conversationally), Decompose (cut into shippable slices), and Execute
  (chain `new-spec` → `work-loop`). This skill does **not** reimplement
  elicitation; it hands off the assembled brief and steps back.

If you find yourself writing a Jira Align REST call or interrogating the
user for missing Outcome/Scope fields, stop — the right place is one of
the two above.

## One-time setup: customise the field mapping

Before first use on a new Jira Align instance, open
`references/field-mapping.md` and fill in:

1. **Workflow state vocabulary** — your instance's state names in the
   "Customize for your org" table. Standard names (`Planned`, `In Progress`,
   `Completed`) are pre-filled; replace or extend them.
2. **PI naming pattern** — the cadence label format your org uses (e.g.,
   `PI 2026-Q1`, `PI 24`).

This is a one-time step per instance. The brief this skill produces will be
wrong in the State context sentence if the state names don't match.

## Cross-skill invocation — name, not path

This skill names sibling skills (`jira-align`) and host skills
(`receive-brief`) **by their `name:` field, never by path**. Install
locations vary by IDE and scope. The contract: when this skill says *"via
the `jira-align` skill: `get features <ID> …`"*, the agent uses its native
skill-dispatch mechanism to invoke the skill registered under that name
with those arguments.

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:

1. The `jira-align` skill is installed and reachable. Invoke it:
   `jira-align: check`. Exit 0 → proceed. Exit 2 → tell the user to run
   `credential-setup` themselves (interactive — they run it, not you) and
   stop. `jira-align` is a hard dependency; there is no degraded path
   without it.
2. The `receive-brief` skill is installed (from `agent-ready-repo` or
   wherever the consumer keeps it). If not, note the absence — **do not
   stop**. The core-absent branch in Stage 4 handles this gracefully.

## Lifecycle

### Stage 1 — Intake

Fetch the Feature with all fields needed to populate the brief, via the
`jira-align` skill:

```
jira-align: get features <ID> --expand ownerUser,milestones
```

Check for the **three intake requirements** of a Feature:

| Requirement | Where it lives in Jira Align |
|---|---|
| Title (what this feature delivers) | `title` field |
| Description or scope notes | `description` and/or `notes` fields |
| Owner / program context | `ownerUser` (expanded), `programID` |

When any requirement is missing or empty, note the gap — don't stop.
`receive-brief` elicits what's missing in Stage 4.

### Stage 2 — Enumerate children

Fetch the Feature's child items by resource type:

```
jira-align: list stories --filter "featureID eq <ID>"
jira-align: list tasks --filter "featureID eq <ID>"
jira-align: list defects --filter "featureID eq <ID>"
```

Collect whichever resource types return results. A Feature with no children
is valid but thin — ask the user before proceeding (see Boundaries: Ask
first).

For each child item, record:
- Resource type: `stories`, `tasks`, or `defects`
- `id`
- `title` (the story text)

### Stage 3 — Map fields to brief

Using `references/field-mapping.md` as your guide, map the fetched data
onto the Shape B brief template.

**Heading and provenance:**

```
# Brief: <Feature title>

- **Slug:** `<kebab-case-slug>` (derive from the Feature title)
- **Received:** <today's date>
- **Owner:** <owner from ownerUser, or ask>
- **Status:** Draft
- **Epic:** <JIRAALIGN_BASE_URL>/features/<ID>
```

**Outcome** (load-bearing — do not leave empty):

Combine `description` and `notes` into one paragraph. When both are present,
lead with the description and append notes as context. When only one is
present, use it. When neither is present, write `[Outcome not provided —
receive-brief will elicit]` as a placeholder; do not invent.

Then append a one-line state context sentence using the mapping in
`references/field-mapping.md`'s state vocabulary table:

```
*(Current state: <state value> — <Brief handling from your org's mapping>)*
```

Example: `*(Current state: In Progress — active delivery)*`. When `state`
is absent from the Feature response, omit the line.

**Scope / In scope:**

When `acceptanceCriteria` is present on the Feature, use it as the In scope
prose. Otherwise leave the heading with an empty placeholder; `receive-brief`
elicits it.

**User stories (Shape B):**

Map each child to a `US-n` story line. The format is pinned:

```
- **US-n.** (stories/<id>) <story text>
```

Substitute `tasks/` or `defects/` for the resource type. For `<story text>`:
- Reshape the child's `title` into the *As a … / I want … / so that …*
  grammar **when the title itself contains a role and benefit** (e.g. "As a
  PM, track sprint velocity…"). Do not invent a role that isn't in the title.
- Carry the title verbatim when a role/benefit cannot be inferred — do not
  invent. `receive-brief` refines during Elicit.

The `US-n` index is sequential across all resource types, ordered by:
stories first, then tasks, then defects.

**Program Increment context (optional):**

When `milestones` expands to a PI record, add a one-line note in the brief's
`## Context` section (add the heading if absent):

```
> **Program Increment:** <PI name from milestones> — carry forward as
> appetite signal; confirm with `receive-brief`.
```

### Stage 4 — Write brief and hand off

Write the assembled brief to `docs/product/briefs/<slug>.md`. If the file
already exists, ask the user whether to merge or replace before writing.

**Core-present path (receive-brief installed):**

Hand off to `receive-brief` by name:

```
receive-brief: docs/product/briefs/<slug>.md
```

`receive-brief` elicits missing fields (Outcome gaps, Scope, Success
metrics, Appetite), runs DoR, decomposes, and chains into `new-spec` →
`work-loop`. Your role ends at the hand-off.

**Core-absent path (receive-brief not installed):**

When `receive-brief` is unavailable, inline the following instruction and
act on it directly:

> **Core-absent brief — act on this directly:**
>
> The brief at `docs/product/briefs/<slug>.md` is assembled from Jira Align
> data. Proceed as follows:
>
> 1. **Elicit missing fields.** Ask the user to fill in any empty headings
>    in the brief (Outcome gaps, Success metrics, Scope, Appetite).
> 2. **Decompose.** For each `US-n` story that warrants its own spec,
>    open `docs/specs/<feature-slug>/spec.md` and ask the user to confirm
>    the decomposition before proceeding.
> 3. **Execute.** For each confirmed spec, invoke `new-spec` by name (if
>    installed), then `work-loop`. If neither is installed, tell the user
>    which packs to install and stop.

## Don't

- Don't read `~/.agentbundle/credentials.env` from the skill body.
- Don't write a raw Jira Align REST call — use the `jira-align` skill.
- Don't invoke `create`, `update`, `delete`, or `raw` with a mutating
  method on the `jira-align` skill. Intake is read-only.
- Don't re-run `credential-setup` for the user or pipe the token into it.
- Don't reimplement `receive-brief`'s elicitation — hand off and step back.
- Don't invent Outcome, Scope, or story text the Jira Align source doesn't
  support. Surface the gap; let `receive-brief` elicit it.
- Don't reference this skill, `jira-align`, or `receive-brief` by path —
  always by name.
- Don't claim portability across all Jira Align instances without asking the
  adopter to customise `references/field-mapping.md` first.

## Edge cases

- **Feature not found (404):** the `jira-align` CLI exits 3 and prints the
  server message. Surface it to the user and stop — do not guess or
  substitute.
- **Credentials missing / expired (exit 2):** tell the user to re-run
  `credential-setup` and regenerate their API token on the Jira Align
  Profile page.
- **Feature with no children:** confirm with the user before assembling a
  brief from title + description alone — a Feature with no stories is
  unusual and may indicate the wrong ID or incomplete Jira Align data.
- **Custom fields:** Jira Align instances expose org-specific fields in
  responses. When a field named in `references/field-mapping.md`'s
  "Customize for your org" section is present in the Feature response, use
  it. When it is absent, skip it and note the gap in the brief.
- **Large child sets (> 100):** the `jira-align` CLI paginates transparently
  up to `--limit`. For features with many children, consider scoping the
  intake to a representative subset and noting the total count in the brief;
  confirm with the user.