Skip to content

Commit 4cccec8

Browse files
janwright73Jan Wrightclaude
authored
Add Jira quarterly-initiative-report skill to pf-workflow plugin (#48)
This skill generates comprehensive quarterly Jira status reports with: - Progress tracking across epics with completion metrics - RAG (Red/Amber/Green) status assessment - Cross-project duplicate link analysis (critical for multi-team initiatives) - Blocker identification and risk assessment - Q+1 priority recommendations based on incomplete work - Complete epic reference table with clickable Jira links Key Features: - Hybrid MCP/REST API support for maximum compatibility - Handles cross-project work via duplicate links (AAP, MTV, CONSOLE, SAT, etc.) - Prevents "invisible work" problem by checking ALL epics for linked work - Tool-agnostic: works in Claude Code, Cursor, and future AI tools - Uses standard tools: curl and jq (no special dependencies) Tested with: - PatternFly Q1 2026 initiative (35 epics, 549 issues) - Cross-project work spanning 6 different Jira projects - Both direct children and linked epic scenarios Benefits: - Automates tedious manual report generation - Ensures complete visibility of cross-project work - Provides data-driven status assessments - Saves hours per quarterly report File: plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md Lines: 320 (concise, under 500-line guideline) Standards: Meets all ai-helpers repository requirements <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a quarterly initiative report workflow that generates standardized Jira initiative status reports with per-epic completion metrics, linked-work aggregation, blocker detection, RAG status, and actionable recommendations. * **Documentation** * Added user-facing documentation covering invocation examples, report layout and filename conventions, methodology for metrics and dashboards. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Jan Wright <jawright@redhat.com> Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 16a2c19 commit 4cccec8

1 file changed

Lines changed: 320 additions & 0 deletions

File tree

  • plugins/pf-workflow/skills/quarterly-initiative-report

‎plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md‎

Lines changed: 320 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,320 @@
1+
---
2+
name: quarterly-initiative-report
3+
description: Generate comprehensive quarterly Jira status reports with progress tracking, RAG assessment, blocker identification, cross-project duplicate link analysis, and Q+1 recommendations. Use when generating quarterly reports, tracking initiative progress, or analyzing epic completion metrics across Jira projects with labels.
4+
disable-model-invocation: false
5+
---
6+
7+
# Quarterly Initiative Status Report
8+
9+
Generate comprehensive quarterly status reports for Jira initiatives with progress tracking, RAG (Red/Amber/Green) status assessment, blocker identification, and next-quarter priority recommendations.
10+
11+
## Requirements
12+
13+
| Tool | Purpose | Check |
14+
|---|---|---|
15+
| `curl` | Jira REST API calls | `command -v curl` |
16+
| `jq` | JSON parsing | `command -v jq` or `brew install jq` |
17+
18+
## Prerequisites
19+
20+
This skill requires Jira API credentials configured as environment variables:
21+
22+
| Variable | Description | Example |
23+
|---|---|---|
24+
| `ATLASSIAN_EMAIL` | Your Atlassian account email | `user@company.com` |
25+
| `ATLASSIAN_API_TOKEN` | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) | `ATATT3xFfGF0...` |
26+
| `JIRA_SITE_URL` | Your Jira instance URL | `https://company.atlassian.net` |
27+
28+
### Setting Environment Variables
29+
30+
**Option 1: In AI tool settings** (Claude Code settings.json, Cursor config):
31+
```json
32+
{
33+
"env": {
34+
"ATLASSIAN_EMAIL": "your-email@company.com",
35+
"ATLASSIAN_API_TOKEN": "your-token-here",
36+
"JIRA_SITE_URL": "https://your-company.atlassian.net"
37+
}
38+
}
39+
```
40+
41+
**Option 2: Shell environment**:
42+
```bash
43+
export ATLASSIAN_EMAIL="your-email@company.com"
44+
export ATLASSIAN_API_TOKEN="your-token-here"
45+
export JIRA_SITE_URL="https://your-company.atlassian.net"
46+
```
47+
48+
**Verify credentials:**
49+
```bash
50+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
51+
-H "Accept: application/json" \
52+
"$JIRA_SITE_URL/rest/api/3/myself" | jq '.displayName'
53+
```
54+
55+
## Usage
56+
57+
When invoked, gather from the user:
58+
1. **Jira Project Key** (e.g., "PF" for PatternFly)
59+
2. **Label** identifying the initiative (e.g., "Q1-2026" or "Q12026")
60+
61+
Then execute the workflow below to generate the comprehensive report.
62+
63+
## Workflow
64+
65+
### Step 1: Fetch All Epics with the Label
66+
67+
```bash
68+
# Search for all epics/initiatives with the label
69+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
70+
-H "Accept: application/json" \
71+
-X POST \
72+
-H "Content-Type: application/json" \
73+
-d '{"jql":"project=PROJECT AND labels=\"LABEL\" AND type IN (Epic, Initiative)","fields":["key","summary","status","assignee","duedate","issuetype","labels"],"maxResults":1000}' \
74+
"$JIRA_SITE_URL/rest/api/3/search/jql"
75+
```
76+
77+
### Step 2: For Each Epic, Gather Complete Metrics
78+
79+
**Process for EVERY epic (including closed):**
80+
81+
1. **Fetch direct sub-issues:**
82+
```bash
83+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
84+
-H "Accept: application/json" \
85+
-X POST \
86+
-H "Content-Type: application/json" \
87+
-d '{"jql":"parent=EPIC-KEY","fields":["key","summary","status","priority"],"maxResults":1000}' \
88+
"$JIRA_SITE_URL/rest/api/3/search/jql" | \
89+
jq '{
90+
total: (.issues | length),
91+
done: ([.issues[] | select(.fields.status.statusCategory.key == "done")] | length),
92+
in_progress: ([.issues[] | select(.fields.status.statusCategory.key == "indeterminate")] | length),
93+
todo: ([.issues[] | select(.fields.status.statusCategory.key == "new")] | length),
94+
completion_pct: (if (.issues | length) > 0 then (([.issues[] | select(.fields.status.statusCategory.key == "done")] | length) * 100 / (.issues | length) | floor) else 0 end)
95+
}'
96+
```
97+
98+
2. **Check for duplicate links (CRITICAL for all epics):**
99+
```bash
100+
# Check EVERY epic for cross-project duplicate links
101+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
102+
-H "Accept: application/json" \
103+
"$JIRA_SITE_URL/rest/api/3/issue/EPIC-KEY?fields=issuelinks" | \
104+
jq '{
105+
key: .key,
106+
duplicates: [.fields.issuelinks[] | select(.type.name == "Duplicate") | {
107+
linked_issue: (if .outwardIssue then .outwardIssue.key else .inwardIssue.key end),
108+
linked_type: (if .outwardIssue then .outwardIssue.fields.issuetype.name else .inwardIssue.fields.issuetype.name end)
109+
}]
110+
}'
111+
```
112+
113+
3. **For each linked epic, fetch its child issues:**
114+
```bash
115+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
116+
-H "Accept: application/json" \
117+
-X POST \
118+
-H "Content-Type: application/json" \
119+
-d '{"jql":"parent=LINKED-EPIC-KEY","fields":["key","summary","status"],"maxResults":1000}' \
120+
"$JIRA_SITE_URL/rest/api/3/search/jql" | \
121+
jq '{
122+
total: (.issues | length),
123+
done: ([.issues[] | select(.fields.status.statusCategory.key == "done")] | length),
124+
in_progress: ([.issues[] | select(.fields.status.statusCategory.key == "indeterminate")] | length),
125+
todo: ([.issues[] | select(.fields.status.statusCategory.key == "new")] | length)
126+
}'
127+
```
128+
129+
**IMPORTANT:** Combine direct children + linked epic children for total metrics. Many cross-project initiatives track significant work via duplicate links (e.g., AAP, MTV, CONSOLE, SAT projects).
130+
131+
### Step 3: Calculate Aggregate Metrics
132+
133+
- **Total Issues:** Sum all direct + linked issues across all epics
134+
- **Overall Completion:** (Total Done / Total Issues) × 100
135+
- **Epic Counts:** Closed, In Progress, New
136+
- **Cross-Project Work:** Issues tracked via duplicate links
137+
138+
### Step 4: Identify Blockers
139+
140+
```bash
141+
# Find high-priority or blocked issues
142+
curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \
143+
-H "Accept: application/json" \
144+
-X POST \
145+
-H "Content-Type: application/json" \
146+
-d '{"jql":"project=PROJECT AND labels=\"LABEL\" AND (status=Blocked OR priority=Highest)","fields":["key","summary","status","priority","assignee"],"maxResults":1000}' \
147+
"$JIRA_SITE_URL/rest/api/3/search/jql"
148+
```
149+
150+
### Step 5: Determine RAG Status
151+
152+
For each epic, evaluate in this order (first match wins):
153+
- **🔴 Red (Critical):** <40% complete OR critical blockers OR unassigned near deadline
154+
- **🟡 Amber (At Risk):** 40-74% complete OR 1-2 non-critical blockers
155+
- **🟢 Green (On Track):** ≥75% complete OR ≥50% with no blockers
156+
157+
### Step 6: Generate Report
158+
159+
Structure the output markdown report with these sections:
160+
161+
## Report Structure
162+
163+
```markdown
164+
# Quarterly Initiative Status Report: [Initiative Name]
165+
**Reporting Period:** [Quarter/Year]
166+
**Report Date:** [Current Date]
167+
**Overall Status:** 🟢/🟡/🔴 [RAG]
168+
169+
---
170+
171+
## Executive Summary
172+
173+
[2-3 paragraphs: overall health, key achievements, critical concerns]
174+
175+
**Key Metrics:**
176+
- Overall Completion: X% (Y/Z issues)
177+
- Epics Completed: A of B
178+
- Critical Blockers: C
179+
180+
---
181+
182+
## Initiative Overview
183+
184+
**Initiative:** [Label/Name]
185+
**Quarter:** Q# YYYY
186+
**Timeline:** [Start] - [End]
187+
**Days Remaining:** X days
188+
189+
**Goals:** [Extracted from initiative description or inferred]
190+
191+
---
192+
193+
## Epic Status Dashboard
194+
195+
| Epic | Owner | Status | Progress | RAG | Notes |
196+
|------|-------|--------|----------|-----|-------|
197+
| [KEY] [Summary] | [Owner] | In Progress | 75% (15/20) | 🟢 | |
198+
| [KEY] [Summary] | [Owner] | In Progress | 45% (9/20) | 🟡 | Has 1 blocker |
199+
| [KEY] [Summary] | [Owner] | New | 0% (0/10) | 🔴 | Unassigned |
200+
201+
---
202+
203+
## Detailed Metrics
204+
205+
### Overall Progress
206+
- **Total Issues:** X
207+
- **Completed:** Y (Z%)
208+
- **In Progress:** A (B%)
209+
- **To Do:** C (D%)
210+
211+
### Cross-Project Work
212+
- **Total Linked Issues:** N (via duplicate epics)
213+
- **Projects:** AAP, MTV, CONSOLE, SAT, etc.
214+
- **Linked Completion:** P%
215+
216+
### By Epic
217+
[For each epic with duplicate links, show:]
218+
- **[Epic Key]** - [Summary]: X direct children (Y% complete)
219+
- Linked via duplicates: [Linked Epic Key] (Z children, W% complete)
220+
- Combined: Total issues, overall %
221+
222+
---
223+
224+
## Blockers and Risks
225+
226+
### Critical Blockers (Immediate Action Required)
227+
1. **[Epic Key]:** [Description]
228+
- Impact: High/Medium/Low
229+
- Recommendation: [Action]
230+
231+
### Risks (Monitor Closely)
232+
1. **[Risk]:** [Description]
233+
- Likelihood: High/Medium/Low
234+
- Impact: High/Medium/Low
235+
- Mitigation: [Strategy]
236+
237+
---
238+
239+
## Q+1 Priority Recommendations
240+
241+
### Must Complete (Carryover)
242+
1. **[Epic/Task]** - [Reason why critical]
243+
244+
### High Priority (Next Phase)
245+
1. **[Suggested Work]** - [Builds on completed X]
246+
247+
---
248+
249+
## Appendix
250+
251+
### Methodology
252+
- Data source: Jira REST API v3
253+
- Reporting period: [Dates]
254+
- Status categories: "done", "indeterminate", "new"
255+
256+
### Complete Epic Reference Table
257+
258+
| Epic | Summary | Owner | Done | In Prog | To Do | Total | % | Link |
259+
|------|---------|-------|------|---------|-------|-------|---|------|
260+
| **[KEY]** | [Summary] | [Owner] | X | Y | Z | N | P% | [View]([url]) |
261+
262+
**Notes:**
263+
- * Indicates epic with cross-project duplicate links
264+
- Total includes direct + linked epic work
265+
- Sorted by completion % (descending)
266+
267+
**Summary Totals:**
268+
- Total Issues: X
269+
- Completed: Y (Z%)
270+
```
271+
272+
## Best Practices
273+
274+
1. **Check ALL epics for duplicate links** - Even closed epics may track work in other projects
275+
2. **Report cross-project work** - Many initiatives span multiple Jira projects (AAP, MTV, etc.)
276+
3. **Use data-driven RAG** - Don't guess; base status on actual completion %
277+
4. **Track trends** - Compare with previous reports to show velocity
278+
5. **Be concise in executive summary** - Decision-makers want key facts
279+
6. **Include appendix table** - Full epic reference with links for drill-down
280+
281+
## Common Patterns
282+
283+
**Epic with no direct children but has linked work:**
284+
```
285+
Epic PF-3227: Ansible Nexus Migration (Closed)
286+
Direct children: 0 issues
287+
Linked via duplicates:
288+
- AAP-58793: 16 issues (16 done, 100%)
289+
Combined: 16 issues, 100% complete ✅
290+
```
291+
292+
**Epic with both direct and linked work:**
293+
```
294+
Epic PF-3408: Ansible Q1 Features (In Progress)
295+
Direct children: 0 issues
296+
Linked via duplicates:
297+
- AAP-60038: 63 issues (55 done, 87%)
298+
- AAP-57961: 18 issues (18 done, 100%)
299+
- AAP-59349: 56 issues (22 done, 39%)
300+
Combined: 137 issues, 69% complete
301+
```
302+
303+
## Example Invocation
304+
305+
**User:** "Generate a quarterly report for PF project with label Q12026"
306+
307+
**Assistant actions:**
308+
1. Confirm project key and label with user
309+
2. Fetch all epics with label
310+
3. For each epic:
311+
- Fetch direct children
312+
- Check for duplicate links
313+
- Fetch linked epic children
314+
- Calculate combined metrics
315+
4. Calculate aggregate statistics
316+
5. Identify blockers and assign RAG status
317+
6. Generate comprehensive markdown report
318+
7. Save report to file with date in filename
319+
320+
**Output file:** `Q1-2026-Q12026-Quarterly-Report-[DATE].md`

0 commit comments

Comments
 (0)