Create QA Step issues as sub-issues of a QA Issue
/plugin marketplace add el-feo/ai-context/plugin install ghpm@jebs-dev-tools<qa_step_issue_template>
# QA Step: <Brief Description>
## Scenario
As a <role>,
Given <precondition>,
When <action>,
Then <expected outcome>
## Parent QA Issue
- QA: #<QA_NUMBER>
## Test Details
- **URL/Page:** <starting URL or page>
- **Prerequisites:** <any setup needed>
- **Test Data:** <if applicable>
## Execution Log
- [ ] Pass / Fail
- **Executed by:** (not yet executed)
- **Timestamp:** (pending)
- **Notes:** (none)
## Bugs Found
(None)
| Field | Description |
|---|---|
<Brief Description> | Concise 3-8 word summary of what is being tested |
<role> | User role or persona (e.g., "logged-in user", "admin", "guest") |
<precondition> | Starting state before action (e.g., "I am on the dashboard page") |
<action> | Single user action being tested (e.g., "I click the Submit button") |
<expected outcome> | Observable result (e.g., "I should see a success message") |
<QA_NUMBER> | Parent QA Issue number |
<URL/Page> | Starting URL or page name |
<Prerequisites> | Any setup required before testing |
<Test Data> | Specific test data needed (if any) |
</qa_step_issue_template>
<objective> You are GHPM (GitHub Project Manager). Generate QA Step issues for systematic acceptance testing and link them as sub-issues of the specified QA Issue. Each QA Step follows the Given/When/Then format for consistent, machine-parseable test scenarios. </objective> <prerequisites> - `gh` CLI installed and authenticated (`gh auth status`) - Working directory is a git repository with GitHub remote - Target QA Issue exists and is accessible - QA Issue should have a linked PRD for context </prerequisites> <arguments> **Optional arguments:** - `qa=#123` - QA issue numberResolution order if omitted:
gh issue list -l QA -s open --limit 1 --json number -q '.[0].number'
</arguments>
<usage_examples> With QA number:
/ghpm:qa-create-steps qa=#42
Auto-resolve most recent QA issue:
/ghpm:qa-create-steps
</usage_examples>
<workflow># If qa=#N provided, use N
QA={provided_qa_number}
# Else pick most recent open QA issue
QA=$(gh issue list -l QA -s open --limit 1 --json number -q '.[0].number')
if [ -z "$QA" ]; then
echo "Error: No open QA issue found. Specify qa=#N or create a QA issue first."
exit 1
fi
# Validate QA number is positive integer
if ! [[ "$QA" =~ ^[0-9]+$ ]]; then
echo "Error: Invalid QA number. Use format: qa=#123"
exit 1
fi
# Fetch QA Issue details
QA_DATA=$(gh issue view "$QA" --json title,body,url -q '.')
QA_TITLE=$(echo "$QA_DATA" | jq -r '.title')
QA_BODY=$(echo "$QA_DATA" | jq -r '.body')
QA_URL=$(echo "$QA_DATA" | jq -r '.url')
if [ -z "$QA_TITLE" ]; then
echo "Error: Could not fetch QA Issue #$QA. Check if it exists and is accessible."
exit 1
fi
echo "QA Issue #$QA: $QA_TITLE"
echo "URL: $QA_URL"
# Extract PRD reference from QA Issue body (look for "PRD: #123" pattern)
PRD=$(echo "$QA_BODY" | grep -oE 'PRD: #[0-9]+' | head -1 | grep -oE '[0-9]+')
if [ -n "$PRD" ]; then
# Fetch PRD details for additional context
PRD_DATA=$(gh issue view "$PRD" --json title,body -q '.')
PRD_TITLE=$(echo "$PRD_DATA" | jq -r '.title')
PRD_BODY=$(echo "$PRD_DATA" | jq -r '.body')
echo "Parent PRD #$PRD: $PRD_TITLE"
else
echo "Warning: No PRD reference found in QA Issue. Generating steps from QA Issue context only."
fi
Analyze the QA Issue and PRD context to generate 5-20 QA Steps that:
For each acceptance criterion in the PRD:
1. Identify the user role performing the action
2. Determine the precondition (starting state)
3. Extract the specific user action
4. Define the expected observable outcome
5. Note any test data or prerequisites needed
| Category | Examples |
|---|---|
| Happy Path | Core user flows work as expected |
| Validation | Required fields, format validation |
| Edge Cases | Empty states, boundary values |
| Error Handling | Invalid input, network errors |
| Permissions | Access control, role-based behavior |
Given a PRD for "User Login Feature", generate steps like:
QA Step: Valid login with correct credentials
QA Step: Login with invalid password
QA Step: Login form validation
# Get repository owner and name
OWNER=$(gh repo view --json owner -q '.owner.login')
REPO=$(gh repo view --json name -q '.name')
# Ensure QA-Step label exists (create if not)
gh label create QA-Step --description "QA Step for acceptance testing" --color 9B59B6 2>/dev/null || true
For each generated QA Step, create a GitHub issue:
# For each step, create issue with populated template
STEP_TITLE="QA Step: <Brief Description>"
STEP_BODY=$(cat <<BODY
# QA Step: <Brief Description>
## Scenario
As a <role>,
Given <precondition>,
When <action>,
Then <expected outcome>
## Parent QA Issue
- QA: #$QA
## Test Details
- **URL/Page:** <starting URL or page>
- **Prerequisites:** <any setup needed>
- **Test Data:** <if applicable>
## Execution Log
- [ ] Pass / Fail
- **Executed by:** (not yet executed)
- **Timestamp:** (pending)
- **Notes:** (none)
## Bugs Found
(None)
BODY
)
# Create the QA Step issue
STEP_URL=$(gh issue create \
--title "$STEP_TITLE" \
--label "QA-Step" \
--body "$STEP_BODY")
# Extract step number from URL
STEP_NUM=$(echo "$STEP_URL" | grep -oE '[0-9]+$')
echo "Created QA Step #$STEP_NUM: $STEP_URL"
# Store step number and title for later use
STEP_NUMBERS+=("$STEP_NUM")
STEP_TITLES["$STEP_NUM"]="$STEP_TITLE"
IMPORTANT: QA Steps MUST be linked as sub-issues of the QA Issue, not just listed in a comment.
For each created QA Step, link it as a sub-issue:
# Get the QA Step's internal issue ID
STEP_ID=$(gh api repos/$OWNER/$REPO/issues/$STEP_NUM --jq .id)
# Add QA Step as sub-issue of QA Issue
gh api repos/$OWNER/$REPO/issues/$QA/sub_issues \
-X POST \
-F sub_issue_id=$STEP_ID \
--silent && echo "Linked QA Step #$STEP_NUM as sub-issue of QA #$QA" \
|| echo "Warning: Could not link QA Step #$STEP_NUM as sub-issue"
gh api repos/$OWNER/$REPO/issues/$QA/sub_issues --jq '.[] | [.number, .title] | @tsv'For each created QA Step, add it to the GitHub Project if GHPM_PROJECT is set:
# If GHPM_PROJECT is set, add QA Step to project (best-effort)
if [ -n "$GHPM_PROJECT" ]; then
gh project item-add "$GHPM_PROJECT" --owner "$OWNER" --url "$STEP_URL" \
&& echo "Added QA Step #$STEP_NUM to project: $GHPM_PROJECT" \
|| echo "Warning: Could not add QA Step #$STEP_NUM to project"
fi
If the sub-issues API is not available (older GitHub Enterprise, etc.):
Post a comment on the QA Issue with a checklist of all created QA Steps for tracking:
# Build checklist from created steps
CHECKLIST=""
for step_num in "${STEP_NUMBERS[@]}"; do
step_title="${STEP_TITLES[$step_num]}"
CHECKLIST="$CHECKLIST
- [ ] #$step_num $step_title"
done
# Post comment on QA Issue
gh issue comment "$QA" --body "$(cat <<COMMENT
## QA Steps
The following QA Steps have been created for acceptance testing:
$CHECKLIST
### Execution Instructions
1. Execute each step in order
2. Mark the checkbox when the step passes
3. If a step fails, create a Bug issue and link it in the step's "Bugs Found" section
4. Update each step's Execution Log with results
COMMENT
)"
echo "Posted QA Steps checklist comment on QA Issue #$QA"
The checklist follows this format for consistent tracking:
## QA Steps
The following QA Steps have been created for acceptance testing:
- [ ] #101 QA Step: Valid login with correct credentials
- [ ] #102 QA Step: Login with invalid password
- [ ] #103 QA Step: Login form validation
...
### Execution Instructions
1. Execute each step in order
2. Mark the checkbox when the step passes
3. If a step fails, create a Bug issue and link it in the step's "Bugs Found" section
4. Update each step's Execution Log with results
</workflow>
<operating_rules>
</operating_rules>
<input_validation>
Before proceeding, validate:
# 1. Check gh CLI authentication
gh auth status || { echo "ERROR: Not authenticated. Run 'gh auth login'"; exit 1; }
# 2. Validate QA issue number format (if provided)
# QA number must be a positive integer
if [[ -n "$QA" && ! "$QA" =~ ^[0-9]+$ ]]; then
echo "ERROR: Invalid QA number. Use format: qa=#123"
exit 1
fi
# 3. Verify QA issue exists and is accessible
gh issue view "$QA" > /dev/null 2>&1 || { echo "ERROR: Cannot access QA issue #$QA"; exit 1; }
</input_validation>
<error_handling>
If gh CLI not authenticated:
gh auth statusgh auth loginIf QA Issue not found:
If no open QA Issue found (auto-resolve):
/ghpm:qa-createqa=#NIf PRD reference not found in QA Issue:
If QA Step creation fails:
gh api rate_limitIf sub-issue linking fails:
If project add fails:
</error_handling>
<success_criteria>
Command completes successfully when:
QA-Step labelGHPM_PROJECT when set (best-effort)Verification:
# List created QA Steps
gh issue list -l QA-Step -s open --limit 50 --json number,title
# Verify sub-issues are linked to QA Issue
gh api repos/{owner}/{repo}/issues/$QA/sub_issues --jq '.[] | [.number, .title] | @tsv'
# View QA Issue to confirm (sub-issues and checklist appear)
gh issue view "$QA"
</success_criteria>
<output>After completion, report:
Proceed now.