From 009827dace2b493e29101dcafaace92e70452687 Mon Sep 17 00:00:00 2001 From: xavier Date: Fri, 26 Jun 2026 18:49:00 -0400 Subject: [PATCH] OLS-0000: Add make-jira-from-spec skill Skill that creates or updates Jira Epics and Stories from .ai/spec/ changes across all workspace repos. Uses brainstorming for decomposition, then runs story estimation, risk assessment, and epic sizing. Auto-splits stories exceeding 5 SP. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/make-jira-from-spec/SKILL.md | 363 ++++++++++++++++++++ 1 file changed, 363 insertions(+) create mode 100644 .claude/skills/make-jira-from-spec/SKILL.md diff --git a/.claude/skills/make-jira-from-spec/SKILL.md b/.claude/skills/make-jira-from-spec/SKILL.md new file mode 100644 index 0000000..aaad389 --- /dev/null +++ b/.claude/skills/make-jira-from-spec/SKILL.md @@ -0,0 +1,363 @@ +--- +name: make-jira-from-spec +description: >- + Create or update Jira Epics and Stories from spec changes. + Reads spec diffs from the current session or a PR, uses + brainstorming to design the work breakdown, creates/updates + issues in Jira, then estimates story points, risk levels, + and epic sizes. Splits stories that exceed 5 SP. Use when + the user says "make jira from spec", "make-jira-from-spec", + "create jira from spec", "update jira from spec", or wants + to turn spec changes into tracked Jira work. +argument-hint: "[PR-URL | OLS-XXXX]" +--- + +# make-jira-from-spec + +Turn spec changes into Jira work items. Reads the `.ai/spec/` +changes from the current session or a PR, brainstorms the +decomposition, creates or updates Epics and Stories, then +estimates and risk-assesses every item. + +## Defaults + +| Setting | Value | +|---------|-------| +| Project key | `OLS` | +| Cloud ID | `redhat.atlassian.net` | +| Content format | `markdown` | +| SP field | `customfield_10028` | +| Risk Score field | `customfield_10976` | +| Epic Size field | `customfield_10795` | +| Max story points | 5 (split if above) | + +## Invocation + +``` +/make-jira-from-spec +/make-jira-from-spec https://github.com/org/repo/pull/123 +/make-jira-from-spec OLS-1234 +``` + +Arguments (all optional): +- **PR URL** — fetch the spec diff from this pull request +- **Jira key** — existing Epic or Story to update + +## Step 1: Gather Spec Changes + +Resolve the spec changes using this priority: + +### 1a. PR URL provided + +Fetch the diff with `gh pr diff `. Filter to files +under `.ai/spec/` in any repo. Read the full content of each +changed spec file. + +### 1b. Session context (no PR URL) + +Find spec files changed in the current session across all +repos in the workspace: + +```bash +# From the workspace root +for repo in */; do + git -C "$repo" diff HEAD -- .ai/spec/ 2>/dev/null +done +``` + +Also check for untracked new spec files: + +```bash +for repo in */; do + git -C "$repo" diff --cached -- .ai/spec/ 2>/dev/null + git -C "$repo" ls-files --others --exclude-standard .ai/spec/ 2>/dev/null +done +``` + +### 1c. Neither is clear + +Ask the user: + +> I couldn't detect spec changes in this session. Can you +> point me to the PR or spec files that changed? + +Read the full content of every changed spec file — the diff +alone is not enough context for good decomposition. + +## Step 2: Brainstorm Decomposition + +Invoke `superpowers:brainstorming` with the spec changes as +context. The brainstorming session should produce: + +- What Epics are needed (if the scope warrants them) +- What Stories are needed under each Epic +- Summary and Acceptance Criteria for each item +- Which items map to existing Jira issues (if a parent was + provided) + +Feed the brainstorming session with: +- The full spec content (not just the diff) +- The diff showing what changed +- The existing Jira parent and its children (if known) + +The brainstorming output is the proposed work breakdown — +it is NOT yet approved for Jira creation. + +## Step 3: Resolve Parent + +If the user provided a Jira key as an argument, use it as +the parent. + +If no parent was provided, ask: + +> What Epic or Feature should these items live under? +> Provide a Jira key (e.g. OLS-1234) or say "new" to +> create a new Epic. + +Do NOT proceed without a parent. + +## Step 4: Search Existing Jira Items + +Query children of the user-provided parent only: + +``` +searchJiraIssuesUsingJql: + cloudId: redhat.atlassian.net + jql: > + parent = {PARENT_KEY} + OR "Epic Link" = {PARENT_KEY} + fields: ["summary", "description", "status", + "issuetype", "customfield_10028", + "customfield_10976"] + maxResults: 100 +``` + +Match existing items against the proposed work breakdown: +- Items that already cover proposed work → mark for update +- Proposed items with no match → mark for creation +- Existing items not in the proposal → leave untouched + +## Step 5: Propose Work Items + +Present the full plan to the user: + +``` +Spec changes: {list of changed spec files} +Parent: {PARENT_KEY} — {parent summary} + +## New Items + +| # | Type | Summary | AC count | +|---|-------|----------------------------|----------| +| 1 | Epic | {summary} | — | +| 2 | Story | {summary} | 4 | +| 3 | Story | {summary} | 3 | + +## Updates to Existing Items + +| Key | Change | +|----------|-------------------------------------| +| OLS-1234 | Update AC to reflect new constraint | +| OLS-1235 | Add scope from new spec section | + +Options: + approve — create/update all items in Jira + revise — tell me what to change + stop — cancel +``` + +**Wait for the user.** Do NOT touch Jira without explicit +approval. + +## Step 6: Execute in Jira + +Before the first Jira call, resolve the **cloudId** by +calling `getAccessibleAtlassianResources` and picking the +`redhat.atlassian.net` site. + +### Creating items + +Create Epics first, then Stories (so Stories can reference +their parent Epic). + +``` +createJiraIssue: + cloudId: {cloudId} + projectKey: OLS + issueTypeName: {Epic | Story} + summary: "{summary}" + description: "{markdown description with AC}" + contentFormat: "markdown" + parent: "{parent key}" +``` + +### Updating items + +Fetch the current description first, then merge changes: + +``` +editJiraIssue: + cloudId: {cloudId} + issueIdOrKey: "{issue key}" + fields: + description: "{updated markdown}" + contentFormat: "markdown" +``` + +Preserve any content in the existing description that is not +being replaced. Append new AC, update changed sections, do +not remove sections the spec didn't touch. + +### Description format + +Use markdown with this structure: + +```markdown +## User Story + +As a {persona}, I want {goal} so that {benefit}. + +## Description + +{Context, background, technical detail from the spec.} + +## Acceptance Criteria + +- {AC 1} +- {AC 2} + +## Spec Reference + +Source: {repo}/.ai/spec/{path} +``` + +For Epics, omit the User Story section and use: + +```markdown +## Overview + +{What this Epic covers and why.} + +## Scope + +- {Scope item 1} +- {Scope item 2} + +## Spec Reference + +Source: {repo}/.ai/spec/{path} +``` + +## Step 7: Estimate and Assess + +After all items are created/updated, run the estimation and +risk assessment skills on every item. Pass all keys at once +to each skill. + +### Stories + +Invoke `/estimate-story` with all story keys: +``` +/estimate-story OLS-1001 OLS-1002 OLS-1003 +``` + +Invoke `/estimate-risk` with all story keys: +``` +/estimate-risk OLS-1001 OLS-1002 OLS-1003 +``` + +### Epics + +Invoke `/estimate-epic` with all epic keys: +``` +/estimate-epic OLS-2001 +``` + +## Step 8: Auto-Split Oversized Stories + +After estimation, check every story. If any story was +estimated at more than 5 SP: + +### 8a. Brainstorm the split + +Use `superpowers:brainstorming` to break the oversized story +into smaller stories, each targeting ≤ 3 SP. + +Consider whether the split produces enough scope and +cohesion to warrant a **new sibling Epic**. If the original +parent is already an Epic and the split stories form a +distinct workstream, create a new Epic as a sibling. +Otherwise, keep the smaller stories under the same parent. + +### 8b. Present split for approval + +``` +Story OLS-1002 estimated at 8 SP — splitting: + +| # | Summary | Parent | +|---|----------------------------|----------| +| 1 | {sub-story 1} | OLS-2001 | +| 2 | {sub-story 2} | OLS-2001 | +| 3 | {sub-story 3} | OLS-2002 (new Epic) | + +Options: + approve — create the split + revise — tell me what to change +``` + +**Wait for user approval.** + +### 8c. Execute the split + +1. Create new Epic (if proposed) via `createJiraIssue` +2. Create the smaller stories via `createJiraIssue` +3. Close or update the original oversized story — add a + comment noting it was split, link to the new stories +4. Re-run `/estimate-story` and `/estimate-risk` on the new + stories +5. Re-run `/estimate-epic` on all affected Epics + +## Step 9: Report + +Print a summary table of everything created and updated: + +``` +## Summary + +| Key | Type | Summary | SP | Risk | Status | +|----------|-------|----------------------|----|------|---------| +| OLS-2001 | Epic | {summary} | — | — | Created | +| OLS-1001 | Story | {summary} | 3 | 2 | Created | +| OLS-1002 | Story | {summary} | 2 | 1 | Created | +| OLS-1234 | Story | {summary} | 3 | 2 | Updated | + +Epics sized: OLS-2001 → S (15 SP) + +Spec sources: +- lightspeed-service/.ai/spec/what/query-pipeline.md +- lightspeed-operator/.ai/spec/what/deployment.md +``` + +## Constraints + +- **Human gates are mandatory** — never create or update + Jira issues without explicit user approval (Step 5, Step + 8b). +- **Parent is required** — always ask if not provided. Do + not create orphan stories. +- **Scoped search only** — when searching for existing + items, only look at children of the user-provided parent. + Do not search the entire project. +- **Preserve existing content** — when updating an issue, + merge changes into the existing description. Do not + overwrite sections the spec didn't touch. +- **Max 5 SP per story** — any story estimated above 5 SP + must be split. This is not optional. +- **Spec reference required** — every created item must + include a Spec Reference section linking back to the + source spec file. +- **No invented requirements** — only create work items for + scope that exists in the spec. Do not expand scope. +- **Use markdown contentFormat** — all Jira descriptions use + `contentFormat: "markdown"`. The Jira MCP server converts + to ADF automatically.