Add Jira quarterly-initiative-report skill to pf-workflow plugin#48
Open
janwright73 wants to merge 4 commits intopatternfly:mainfrom
Open
Add Jira quarterly-initiative-report skill to pf-workflow plugin#48janwright73 wants to merge 4 commits intopatternfly:mainfrom
janwright73 wants to merge 4 commits intopatternfly:mainfrom
Conversation
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
Collaborator
|
@coderabbitai full review |
Contributor
✅ Actions performedFull review triggered. |
Contributor
📝 WalkthroughWalkthroughAdded a new skill definition documentation file that describes a workflow for assembling quarterly initiative status reports. The workflow queries Jira for epics matching specified labels, computes completion metrics across direct and linked issues, identifies blockers, assigns RAG status, and generates a standardized Markdown report. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md (1)
30-30: Replace tool-specific setup wording with tool-agnostic phrasing.Line 30 calls out specific products (“Claude Code”, “Cursor”). Reword this to generic assistant/tool settings language to stay fully tool-agnostic.
As per coding guidelines in
CONTRIBUTING-SKILLS.md:116-129, skills must be tool-agnostic and avoid referencing a specific tool.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` at line 30, Update the wording in SKILL.md under the "Option 1: In AI tool settings" section to remove product names ("Claude Code", "Cursor") and replace them with tool-agnostic phrasing such as "your assistant or tool settings (e.g., settings.json or config file)"; locate the header "Option 1: In AI tool settings" and the sentence that currently lists “Claude Code settings.json, Cursor config” and reword it to a generic instruction about adjusting assistant/tool settings per CONTRIBUTING-SKILLS.md guidelines.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@SKILL-TEST-RESULTS.md`:
- Line 4: Replace the personal local path shown in the "Skill Location:" entry
(the string starting with "/Users/jawright/...") with a generic placeholder
(e.g., "/path/to/skill/skill.md" or "{SKILL_PATH}") and update the related
compliance assertion around the compliance claim (the statement referenced near
line 154) so it accurately reflects that only generic placeholders are used;
ensure the "Skill Location" header and the compliance line both use the same
non-identifying placeholder format.
---
Nitpick comments:
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md`:
- Line 30: Update the wording in SKILL.md under the "Option 1: In AI tool
settings" section to remove product names ("Claude Code", "Cursor") and replace
them with tool-agnostic phrasing such as "your assistant or tool settings (e.g.,
settings.json or config file)"; locate the header "Option 1: In AI tool
settings" and the sentence that currently lists “Claude Code settings.json,
Cursor config” and reword it to a generic instruction about adjusting
assistant/tool settings per CONTRIBUTING-SKILLS.md guidelines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: c905ec7b-302e-4dcd-a76e-021a8c109e16
📒 Files selected for processing (2)
SKILL-TEST-RESULTS.mdplugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md
SKILL-TEST-RESULTS.md
Outdated
| # Quarterly Initiative Report Skill - Test Results | ||
|
|
||
| **Test Date:** March 28, 2026 | ||
| **Skill Location:** `/Users/jawright/.claude/skills/quarterly-initiative-report-test/skill.md` |
Contributor
There was a problem hiding this comment.
Remove personal path details or update the compliance claim.
Line 4 includes a user-identifying local path (/Users/jawright/...), which conflicts with the Line 154 assertion that only generic placeholders are used and no personal information is present.
As per coding guidelines in CONTRIBUTING-SKILLS.md:116-129, skills/docs should meet repository standards, including safe and generic documentation patterns.
Also applies to: 154-154
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@SKILL-TEST-RESULTS.md` at line 4, Replace the personal local path shown in
the "Skill Location:" entry (the string starting with "/Users/jawright/...")
with a generic placeholder (e.g., "/path/to/skill/skill.md" or "{SKILL_PATH}")
and update the related compliance assertion around the compliance claim (the
statement referenced near line 154) so it accurately reflects that only generic
placeholders are used; ensure the "Skill Location" header and the compliance
line both use the same non-identifying placeholder format.
- Remove specific shell rc file references (~/.zshrc, ~/.bashrc) - Replace personal skill path with generic skill name - Addresses feedback from PR review
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (2)
plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md (1)
30-31: Use tool-neutral wording in setup instructions.Calling out “Claude Code settings.json, Cursor config” is tool-specific. Prefer neutral phrasing so the skill text remains portable.
Suggested fix
-**Option 1: In AI tool settings** (Claude Code settings.json, Cursor config): +**Option 1: In your AI assistant environment configuration**:As per coding guidelines in
CONTRIBUTING-SKILLS.md, “Skills must be tool-agnostic … Avoid referencing a specific tool.”🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` around lines 30 - 31, Replace the tool-specific phrase "Claude Code settings.json, Cursor config" under the "Option 1: In AI tool settings" section in SKILL.md with a tool-neutral instruction (e.g., "your AI/code tool's settings or configuration file") so the guidance is portable; update the surrounding text to avoid naming any specific products and ensure it follows the CONTRIBUTING-SKILLS.md rule that "Skills must be tool-agnostic."SKILL-TEST-RESULTS.md (1)
156-156: Use “Markdown” capitalization for consistency.Consider updating “Proper markdown formatting” → “Proper Markdown formatting”.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@SKILL-TEST-RESULTS.md` at line 156, Update the table cell text that currently reads "Proper markdown formatting" to use consistent capitalization "Proper Markdown formatting"; locate the string "Proper markdown formatting" in the SKILL-TEST-RESULTS.md table row and change only the word "markdown" to "Markdown" so the header/content uses Title-case for "Markdown".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md`:
- Around line 284-290: Update the two fenced code blocks that currently lack
language tags by adding a language identifier (use "text") to the opening fence
for the snippets containing "Epic PF-3227: Ansible Nexus Migration (Closed)" and
"Epic PF-3408: Ansible Q1 Features (In Progress)"; make the same change for the
other occurrence mentioned (lines 293-301) so all three code fences start with
```text to satisfy MD040 and improve rendering.
- Around line 146-147: Update the JQL used in the curl call in SKILL.md so the
query is scoped to the target project by adding a project filter (e.g., include
project=PROJECT) alongside the existing label and status/priority filters;
locate the JQL string containing labels="LABEL" AND (status=Blocked OR
priority=Highest) in the SKILL.md example and modify it to include
project=PROJECT so the exported query only returns issues for the selected
project.
In `@SKILL-TEST-RESULTS.md`:
- Line 150: The "Tool-agnostic language" compliance claim is too strong for the
quarterly-initiative-report skill; either update the SKILL-TEST-RESULTS.md table
row for "Tool-agnostic language" to reflect the current status (e.g., change ✅
PASS to ❌ FAIL or add a note) or remove tool-specific references from the
quarterly-initiative-report skill text so it truly is tool-agnostic; locate the
skill by name "quarterly-initiative-report" and edit the SKILL.md content to
eliminate any Claude/Cursor-specific wording, or update the
SKILL-TEST-RESULTS.md row to accurately describe the existing wording.
---
Nitpick comments:
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md`:
- Around line 30-31: Replace the tool-specific phrase "Claude Code
settings.json, Cursor config" under the "Option 1: In AI tool settings" section
in SKILL.md with a tool-neutral instruction (e.g., "your AI/code tool's settings
or configuration file") so the guidance is portable; update the surrounding text
to avoid naming any specific products and ensure it follows the
CONTRIBUTING-SKILLS.md rule that "Skills must be tool-agnostic."
In `@SKILL-TEST-RESULTS.md`:
- Line 156: Update the table cell text that currently reads "Proper markdown
formatting" to use consistent capitalization "Proper Markdown formatting";
locate the string "Proper markdown formatting" in the SKILL-TEST-RESULTS.md
table row and change only the word "markdown" to "Markdown" so the
header/content uses Title-case for "Markdown".
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e057f4c1-f305-418a-90a6-651086a706d9
📒 Files selected for processing (2)
SKILL-TEST-RESULTS.mdplugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md
plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md
Outdated
Show resolved
Hide resolved
Comment on lines
+284
to
+290
| ``` | ||
| Epic PF-3227: Ansible Nexus Migration (Closed) | ||
| Direct children: 0 issues | ||
| Linked via duplicates: | ||
| - AAP-58793: 16 issues (16 done, 100%) | ||
| Combined: 16 issues, 100% complete ✅ | ||
| ``` |
Contributor
There was a problem hiding this comment.
Add language identifiers to fenced code blocks.
Two fenced examples are missing language tags, which triggers MD040 and reduces readability in renderers.
Suggested fix
-```
+```text
Epic PF-3227: Ansible Nexus Migration (Closed)
Direct children: 0 issues
Linked via duplicates:
- AAP-58793: 16 issues (16 done, 100%)
Combined: 16 issues, 100% complete ✅- +text
Epic PF-3408: Ansible Q1 Features (In Progress)
Direct children: 0 issues
Linked via duplicates:
- AAP-60038: 63 issues (55 done, 87%)
- AAP-57961: 18 issues (18 done, 100%)
- AAP-59349: 56 issues (22 done, 39%)
Combined: 137 issues, 69% complete
Also applies to: 293-301
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 284-284: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` around lines
284 - 290, Update the two fenced code blocks that currently lack language tags
by adding a language identifier (use "text") to the opening fence for the
snippets containing "Epic PF-3227: Ansible Nexus Migration (Closed)" and "Epic
PF-3408: Ansible Q1 Features (In Progress)"; make the same change for the other
occurrence mentioned (lines 293-301) so all three code fences start with ```text
to satisfy MD040 and improve rendering.
jpuzz0
reviewed
Apr 1, 2026
Test results file is specific to local test run and should not be committed to repository root. Addresses PR review feedback.
Addresses code review feedback to scope the blocker JQL query to the specific project, preventing unrelated issues from other projects from being included in the blocker search results. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md`:
- Around line 30-39: The README currently names specific tools ("Claude Code
settings.json, Cursor config") in the Option 1 heading and JSON comments; make
this tool-agnostic by removing those tool names and replacing them with generic
phrasing like "AI tool settings" or "assistant configuration" in the SKILL.md
Option 1 section, and keep the JSON example but strip any tool-specific labels
so it reads as generic environment-variable configuration; update the heading
"Option 1: In AI tool settings" and any nearby explanatory text to avoid
mentioning Claude, Cursor, or other vendors.
- Around line 64-148: Replace the prescriptive curl/JQL/jq command blocks under
"Step 1: Fetch All Epics with the Label" and "Step 2: For Each Epic, Gather
Complete Metrics" with outcome-driven descriptions: state the goal (e.g., "Fetch
all epics with the given label", "For each epic, retrieve direct child issues
and compute total, done, in_progress, todo and completion_pct", "Detect
duplicate/linked cross-project issues and include their child work in totals"),
remove the exact command examples and pipelines, and keep the "Step 3: Calculate
Aggregate Metrics" and "Step 4: Identify Blockers" sections as high-level
objectives (e.g., how to aggregate totals and what counts to report) so the
skill describes WHAT to accomplish rather than HOW; target the specific
headings/blocks named in the file to locate and replace the detailed
implementation sections.
- Around line 22-27: The env var names in SKILL.md are inconsistent with other
pf-workflow skills; replace ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN with the
established JIRA_USER_EMAIL and JIRA_API_TOKEN names and update every reference
in this file (examples, description, and any shell/templated usages like
$ATLASSIAN_EMAIL/$ATLASSIAN_API_TOKEN) to $JIRA_USER_EMAIL and $JIRA_API_TOKEN
so the naming aligns with the duplicate-epic skill and avoids duplicate env
vars.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 9bfcd1e1-fe16-4c1b-9e6e-ff6d3f9772cd
📒 Files selected for processing (1)
plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md
Comment on lines
+22
to
+27
| | Variable | Description | Example | | ||
| |---|---|---| | ||
| | `ATLASSIAN_EMAIL` | Your Atlassian account email | `user@company.com` | | ||
| | `ATLASSIAN_API_TOKEN` | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) | `ATATT3xFfGF0...` | | ||
| | `JIRA_SITE_URL` | Your Jira instance URL | `https://company.atlassian.net` | | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify environment variable naming patterns across pf-workflow skills
echo "=== Checking env var patterns in pf-workflow skills ==="
fd -e sh -e md . plugins/pf-workflow/skills/ --exec rg -n 'JIRA_USER_EMAIL|ATLASSIAN_EMAIL|JIRA_API_TOKEN|ATLASSIAN_API_TOKEN|JIRA_BASE_URL|JIRA_SITE_URL' {} \;Repository: patternfly/ai-helpers
Length of output: 2403
🏁 Script executed:
#!/bin/bash
# Verify exact file structure and which skill uses JIRA_USER_EMAIL pattern
find plugins/pf-workflow/skills -type d -name "*" | sortRepository: patternfly/ai-helpers
Length of output: 488
🏁 Script executed:
#!/bin/bash
# Verify the duplicate-epic skill uses JIRA_USER_EMAIL pattern and get full context
echo "=== duplicate-epic SKILL.md env vars ==="
head -40 plugins/pf-workflow/skills/duplicate-epic/SKILL.md | grep -A 10 "Variable"
echo -e "\n=== duplicate-epic script env vars ==="
head -20 plugins/pf-workflow/skills/duplicate-epic/scripts/duplicate-epic.sh | grep -E "JIRA_|EMAIL|TOKEN|URL"
echo -e "\n=== quarterly-initiative-report env vars (snippet) ==="
head -30 plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md | grep -E "ATLASSIAN|JIRA"Repository: patternfly/ai-helpers
Length of output: 1027
🏁 Script executed:
#!/bin/bash
# Check if duplicate-epic SKILL.md mentions JIRA_BASE_URL and any defaults
echo "=== Full duplicate-epic SKILL.md env var section ==="
grep -A 15 "| Variable | Description" plugins/pf-workflow/skills/duplicate-epic/SKILL.md
echo -e "\n=== Check for JIRA_BASE_URL mention anywhere in duplicate-epic ==="
grep -n "JIRA_BASE_URL" plugins/pf-workflow/skills/duplicate-epic/SKILL.md || echo "Not found in SKILL.md"
echo -e "\n=== Check quarterly-initiative-report for any mention of JIRA_BASE_URL or similar ==="
grep -n "JIRA_BASE_URL\|base.*url\|instance.*url" plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.mdRepository: patternfly/ai-helpers
Length of output: 785
🏁 Script executed:
#!/bin/bash
# Check what env vars quarterly-initiative-report actually uses in its code
echo "=== quarterly-initiative-report variable assignments and usage ==="
head -80 plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md | tail -60 | grep -E "ATLASSIAN|JIRA|export|curl"
echo -e "\n=== Check if quarterly-initiative-report has optional/default URL handling ==="
grep -n ":-" plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md | head -5Repository: patternfly/ai-helpers
Length of output: 1050
Environment variable naming must align with other pf-workflow skills to avoid user confusion and script failures.
This skill uses ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN, but the duplicate-epic skill in the same plugin uses JIRA_USER_EMAIL and JIRA_API_TOKEN. Users will need to maintain duplicate environment variables for different skills in the same plugin, leading to confusion and integration issues.
♻️ Update to match duplicate-epic naming convention
Replace environment variable names with the established pattern:
| Variable | Description | Example |
|---|---|---|
-| `ATLASSIAN_EMAIL` | Your Atlassian account email | `user@company.com` |
-| `ATLASSIAN_API_TOKEN` | API token from [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) | `ATATT3xFfGF0...` |
+| `JIRA_USER_EMAIL` | Your Atlassian account email | `user@company.com` |
+| `JIRA_API_TOKEN` | API token from [id.atlassian.com/manage/api-tokens](https://id.atlassian.com/manage/api-tokens) | `ATATT3xFfGF0...` |
| `JIRA_SITE_URL` | Your Jira instance URL | `https://company.atlassian.net` |Then update all usages throughout the file to reference $JIRA_USER_EMAIL, $JIRA_API_TOKEN instead of $ATLASSIAN_EMAIL, $ATLASSIAN_API_TOKEN.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` around lines
22 - 27, The env var names in SKILL.md are inconsistent with other pf-workflow
skills; replace ATLASSIAN_EMAIL and ATLASSIAN_API_TOKEN with the established
JIRA_USER_EMAIL and JIRA_API_TOKEN names and update every reference in this file
(examples, description, and any shell/templated usages like
$ATLASSIAN_EMAIL/$ATLASSIAN_API_TOKEN) to $JIRA_USER_EMAIL and $JIRA_API_TOKEN
so the naming aligns with the duplicate-epic skill and avoids duplicate env
vars.
Comment on lines
+30
to
+39
| **Option 1: In AI tool settings** (Claude Code settings.json, Cursor config): | ||
| ```json | ||
| { | ||
| "env": { | ||
| "ATLASSIAN_EMAIL": "your-email@company.com", | ||
| "ATLASSIAN_API_TOKEN": "your-token-here", | ||
| "JIRA_SITE_URL": "https://your-company.atlassian.net" | ||
| } | ||
| } | ||
| ``` |
Contributor
There was a problem hiding this comment.
Remove tool-specific references to maintain tool-agnostic design.
Line 30 explicitly mentions "Claude Code settings.json, Cursor config," which violates the tool-agnostic requirement for skills.
♻️ Make the guidance tool-agnostic
-**Option 1: In AI tool settings** (Claude Code settings.json, Cursor config):
+**Option 1: In your AI tool's settings** (environment configuration):As per coding guidelines, "Skills must be tool-agnostic — they run in both Claude Code and Cursor. Avoid referencing a specific tool."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` around lines
30 - 39, The README currently names specific tools ("Claude Code settings.json,
Cursor config") in the Option 1 heading and JSON comments; make this
tool-agnostic by removing those tool names and replacing them with generic
phrasing like "AI tool settings" or "assistant configuration" in the SKILL.md
Option 1 section, and keep the JSON example but strip any tool-specific labels
so it reads as generic environment-variable configuration; update the heading
"Option 1: In AI tool settings" and any nearby explanatory text to avoid
mentioning Claude, Cursor, or other vendors.
Comment on lines
+64
to
+148
|
|
||
| ### Step 1: Fetch All Epics with the Label | ||
|
|
||
| ```bash | ||
| # Search for all epics/initiatives with the label | ||
| curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \ | ||
| -H "Accept: application/json" \ | ||
| -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jql":"project=PROJECT AND labels=\"LABEL\" AND type IN (Epic, Initiative)","fields":["key","summary","status","assignee","duedate","issuetype","labels"],"maxResults":1000}' \ | ||
| "$JIRA_SITE_URL/rest/api/3/search/jql" | ||
| ``` | ||
|
|
||
| ### Step 2: For Each Epic, Gather Complete Metrics | ||
|
|
||
| **Process for EVERY epic (including closed):** | ||
|
|
||
| 1. **Fetch direct sub-issues:** | ||
| ```bash | ||
| curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \ | ||
| -H "Accept: application/json" \ | ||
| -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jql":"parent=EPIC-KEY","fields":["key","summary","status","priority"],"maxResults":1000}' \ | ||
| "$JIRA_SITE_URL/rest/api/3/search/jql" | \ | ||
| jq '{ | ||
| total: (.issues | length), | ||
| done: ([.issues[] | select(.fields.status.statusCategory.key == "done")] | length), | ||
| in_progress: ([.issues[] | select(.fields.status.statusCategory.key == "indeterminate")] | length), | ||
| todo: ([.issues[] | select(.fields.status.statusCategory.key == "new")] | length), | ||
| completion_pct: (if (.issues | length) > 0 then (([.issues[] | select(.fields.status.statusCategory.key == "done")] | length) * 100 / (.issues | length) | floor) else 0 end) | ||
| }' | ||
| ``` | ||
|
|
||
| 2. **Check for duplicate links (CRITICAL for all epics):** | ||
| ```bash | ||
| # Check EVERY epic for cross-project duplicate links | ||
| curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \ | ||
| -H "Accept: application/json" \ | ||
| "$JIRA_SITE_URL/rest/api/3/issue/EPIC-KEY?fields=issuelinks" | \ | ||
| jq '{ | ||
| key: .key, | ||
| duplicates: [.fields.issuelinks[] | select(.type.name == "Duplicate") | { | ||
| linked_issue: (if .outwardIssue then .outwardIssue.key else .inwardIssue.key end), | ||
| linked_type: (if .outwardIssue then .outwardIssue.fields.issuetype.name else .inwardIssue.fields.issuetype.name end) | ||
| }] | ||
| }' | ||
| ``` | ||
|
|
||
| 3. **For each linked epic, fetch its child issues:** | ||
| ```bash | ||
| curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \ | ||
| -H "Accept: application/json" \ | ||
| -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jql":"parent=LINKED-EPIC-KEY","fields":["key","summary","status"],"maxResults":1000}' \ | ||
| "$JIRA_SITE_URL/rest/api/3/search/jql" | \ | ||
| jq '{ | ||
| total: (.issues | length), | ||
| done: ([.issues[] | select(.fields.status.statusCategory.key == "done")] | length), | ||
| in_progress: ([.issues[] | select(.fields.status.statusCategory.key == "indeterminate")] | length), | ||
| todo: ([.issues[] | select(.fields.status.statusCategory.key == "new")] | length) | ||
| }' | ||
| ``` | ||
|
|
||
| **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). | ||
|
|
||
| ### Step 3: Calculate Aggregate Metrics | ||
|
|
||
| - **Total Issues:** Sum all direct + linked issues across all epics | ||
| - **Overall Completion:** (Total Done / Total Issues) × 100 | ||
| - **Epic Counts:** Closed, In Progress, New | ||
| - **Cross-Project Work:** Issues tracked via duplicate links | ||
|
|
||
| ### Step 4: Identify Blockers | ||
|
|
||
| ```bash | ||
| # Find high-priority or blocked issues | ||
| curl -s -u "$ATLASSIAN_EMAIL:$ATLASSIAN_API_TOKEN" \ | ||
| -H "Accept: application/json" \ | ||
| -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '{"jql":"project=PROJECT AND labels=\"LABEL\" AND (status=Blocked OR priority=Highest)","fields":["key","summary","status","priority","assignee"],"maxResults":100}' \ | ||
| "$JIRA_SITE_URL/rest/api/3/search/jql" | ||
| ``` |
Contributor
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Refactor to describe outcomes rather than implementation steps.
The skill provides very detailed curl commands, exact JQL syntax, and specific jq pipelines. This level of prescriptive implementation violates the "describe outcomes, not implementation" principle—the AI already knows how to make API calls and parse JSON.
Consider refactoring to state what to accomplish at each step:
- "Fetch all epics with the label from the Jira project"
- "For each epic, retrieve direct child issues and calculate completion percentage based on status categories"
- "Check each epic for duplicate links and aggregate linked work"
The current approach (320 lines of detailed commands) reduces the skill's flexibility and makes it harder to maintain. Let the AI determine the best way to interact with Jira's REST API.
As per coding guidelines, "Describe outcomes, not implementation in skills — tell the AI what to accomplish, not how to do it. The AI already knows how to use git, gh, grep, etc."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md` around lines
64 - 148, Replace the prescriptive curl/JQL/jq command blocks under "Step 1:
Fetch All Epics with the Label" and "Step 2: For Each Epic, Gather Complete
Metrics" with outcome-driven descriptions: state the goal (e.g., "Fetch all
epics with the given label", "For each epic, retrieve direct child issues and
compute total, done, in_progress, todo and completion_pct", "Detect
duplicate/linked cross-project issues and include their child work in totals"),
remove the exact command examples and pipelines, and keep the "Step 3: Calculate
Aggregate Metrics" and "Step 4: Identify Blockers" sections as high-level
objectives (e.g., how to aggregate totals and what counts to report) so the
skill describes WHAT to accomplish rather than HOW; target the specific
headings/blocks named in the file to locate and replace the detailed
implementation sections.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This skill generates comprehensive quarterly Jira status reports with:
Key Features:
Tested with:
Benefits:
File: plugins/pf-workflow/skills/quarterly-initiative-report/SKILL.md
Lines: 320 (concise, under 500-line guideline)
Standards: Meets all ai-helpers repository requirements
Summary by CodeRabbit
New Features
Documentation