Detailed implementation guide for recursively analyzing Jira features and generating comprehensive documentation
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
This skill provides detailed step-by-step implementation guidance for the /jira:generate-feature-doc command, which generates comprehensive feature documentation by recursively analyzing a Jira feature and all its related issues and GitHub pull requests.
IMPORTANT FOR AI: This is a procedural skill - when invoked, you should directly execute the implementation steps defined in this document. Do NOT look for or execute external scripts. Follow the step-by-step instructions below, starting with Step 1.
This skill is automatically invoked by the /jira:generate-feature-doc command and should not be called directly by users.
plugins/jira/README.md for setup)gh) installed and authenticated (for analyzing PRs).work/jira/feature-doc/ for output (will be created if needed)Objective: Set up environment and fetch main feature issue.
Actions:
Save initial directory: INITIAL_DIR=$(pwd) (save at start, before any cd commands)
Check prerequisites: Verify jq and gh CLI are installed and authenticated
Create output directory: WORK_DIR=$INITIAL_DIR/.work/jira/feature-doc/<feature-key> (use mkdir -p)
Fetch main feature: Use MCP Jira tool to get issue with all fields:
mcp__atlassian__jira_get_issue(issue_key=<feature-key>, fields="*all")
plugins/jira/README.mdParse response: Extract key, summary, description, issuetype, status
Display progress: Show feature summary and type
Important: This step expects PR data as input from the jira:extract-prs skill (invoked by the command file). The input is structured JSON containing all discovered PRs with their metadata.
Input Format:
{
"pull_requests": [
{
"url": "https://github.com/org/repo/pull/123",
"state": "MERGED",
"title": "PR title",
"isDraft": false,
"sources": ["remote_link", "description"],
"found_in_issues": ["ISSUE-123"]
}
]
}
Objective: Fetch and analyze PR details to extract implementation information.
Important: This command is for documenting completed features. Only analyze PRs that have been MERGED. Skip OPEN, DRAFT, WIP, or CLOSED (but not merged) PRs.
Actions:
Filter for MERGED PRs: Only analyze PRs with state == "MERGED" AND isDraft == false
isDraft == true (not ready for review)For each MERGED PR, fetch detailed data:
gh pr view {number} --repo {org}/{repo} --json title,body,mergedAt,author,commits,filesgh pr diff {number} --repo {org}/{repo}gh pr view {number} --repo {org}/{repo} --json commentsExtract key information:
Handle errors: If PR inaccessible (403, 404), log warning and continue
Save data: Store metadata, diff, and comments to ${WORK_DIR}/pr-{org}-{repo}-{number}.*
Objective: Organize information into structured outline.
Available sections (calling command specifies which to generate):
Objective: Fill in the outline with actual content based on command requirements.
Section generation guidelines:
Note: Only generate sections specified by the calling command. Check the command file for exact requirements.
Objective: Save documentation and display summary.
Actions:
Write documentation: Save to ${WORK_DIR}/feature-doc.md with footer:
---
*Generated by `/jira:generate-feature-doc` on <timestamp>*
*Source: <feature-key> and <count> related issues*
Save metadata: Store analysis log with timestamps, counts, output files, errors/warnings
Display summary:
Issue Not Found (404, 403, network error):
No PRs Found:
GitHub Rate Limit:
Large Feature (>50 PRs):
Malformed Issue Data:
Parallel PR Analysis:
xargs -P 5)Smart Diff Analysis:
--stat to identify key filesProgress feedback: Show progress after each major step (discovery, PR analysis, etc.)
Error resilience: Don't fail the entire process if one PR is inaccessible
Smart synthesis: Don't just concatenate PR descriptions - synthesize into coherent narrative
Context awareness: Understand the codebase domain (e.g., Kubernetes, OpenShift) to better interpret changes
Structured output: Use consistent markdown formatting with proper headers, code blocks, tables
Link preservation: Always provide clickable links to Jira issues and GitHub PRs
Timestamp tracking: Note when PRs were merged to understand timeline
Author attribution: Credit authors of PRs and issues where relevant
Code examples: Include actual code snippets from PRs to illustrate changes
Visual hierarchy: Use tables, lists, and headers to make documentation scannable
User runs: /jira:generate-feature-doc OCPSTRAT-1612
1. Initialize
- Fetch main feature issue (OCPSTRAT-1612)
- Create working directory (.work/jira/feature-doc/OCPSTRAT-1612/)
- Verify prerequisites (jq, gh CLI)
2. Extract PRs (via extract-prs skill)
- Discover descendants using childIssuesOf() JQL → 3 issues total
- Extract PRs from remote links (primary) + text (backup) → 7 PRs
- Fetch PR state from GitHub → 5 MERGED, 1 OPEN, 1 CLOSED
3. Analyze MERGED PRs
- Filter for MERGED PRs → 5 PRs to analyze
- For each: fetch metadata + diff + comments
- Extract implementation details, design decisions
4. Generate Documentation
- Synthesize sections: Overview, Architecture, Implementation, Usage, Testing
- Create tables for issues and PRs
- Write to feature-doc.md
5. Display Results
✅ Documentation generated successfully!
📄 File: .work/jira/feature-doc/OCPSTRAT-1612/feature-doc.md
📊 3 issues, 5 MERGED PRs, ~380 lines generated