/pr

Generate pull request description from story

/pr

Generate complete, ready-to-paste pull request descriptions directly from your user stories and test evidence. The PR command ensures your pull requests are well-documented, link to relevant work, and include all necessary details for reviewers.

Quick Start

# Generate PR from story with title
/agileflow:pr STORY=US-0042 TITLE="Add user profile"
 
# Generate PR with test evidence
/agileflow:pr STORY=US-0042 TITLE="Add user profile" TEST_EVIDENCE="All unit tests pass, E2E tested login→profile flow"

The command will:

Load the story from docs/06-stories/US-0042.md
Extract acceptance criteria, dependencies, and context
Build a complete PR description with all sections
Output paste-ready markdown for GitHub/GitLab
Suggest a conventional commit message for squash merges

Key Features

Automatic Story Context

PR description automatically includes:

Epic reference - Which feature this belongs to
Story summary - What was implemented
Dependencies - Other stories this depends on
Acceptance criteria - All AC with checkbox states
Test evidence - Your test results and verification
Risk assessment - Potential impacts and rollback plan
Code owners - From CODEOWNERS file

Checklist Management

Acceptance criteria become a PR checklist:

## Checklist
 
- [x] AC1: User can login with email and password
- [x] AC2: Login errors show validation feedback
- [ ] AC3: 2FA support (scope creep - skipped)
- [x] AC4: Session persists across page reloads

Test Evidence Integration

Include test results and verification directly:

## Test Evidence
 
### Unit Tests
- ✅ 42 tests passing, 0 failing
- Coverage: 87% (auth module)
 
### Integration Tests
- ✅ Login flow end-to-end verified
- ✅ Session persistence confirmed
- ✅ Tested with Chrome, Firefox, Safari
 
### Manual Testing
- ✅ Tested on desktop and mobile
- ✅ Accessibility check passed (WCAG AA)

Conventional Commits

Suggests proper commit messages for squash merges:

feat(auth): implement user login with JWT tokens
 
Implements US-0042: User Login API
- Email/password authentication
- JWT token generation and validation
- Session persistence across reloads
- Comprehensive test coverage
 
Closes #42

Usage

Basic PR description

/agileflow:pr STORY=US-0042 TITLE="Add user login API"

Generates PR with:

Story summary from US-0042.md
All acceptance criteria
Linked issues (story + dependencies)
Risk assessment
Code owners

PR with test evidence

/agileflow:pr STORY=US-0042 TITLE="Add user login" TEST_EVIDENCE="All tests passing (42/42), E2E verified"

Adds test results section to PR.

PR with acceptance criteria status

/agileflow:pr STORY=US-0042 TITLE="Login API" AC_CHECKED="✓ Email auth, ✓ JWT generation, ✗ 2FA"

Shows which AC were completed vs skipped.

PR with additional notes

/agileflow:pr STORY=US-0042 TITLE="Login API" NOTES="Coordinated with frontend team on API contract"

Adds custom notes to the description.

Parameters

Parameter	Required	Default	Description
`STORY`	Yes	-	Story ID (e.g., US-0042)
`TITLE`	Yes	-	Short PR title (1-5 words)
`TEST_EVIDENCE`	No	""	Test results, coverage, manual testing notes
`AC_CHECKED`	No	-	Acceptance criteria status (✓/✗ for each)
`NOTES`	No	""	Additional context or coordination notes

Examples

Simple PR from story

/agileflow:pr STORY=US-0042 TITLE="Implement login API"
 
# Output:
# ## Summary
# Implements JWT-based user authentication with email and password login...
#
# ## Linked Issues
# - Implements #US-0042
# - Depends on #US-0039 (User schema)
#
# ## Checklist
# - [x] AC1: Users can login with email/password
# - [x] AC2: Invalid credentials show error
# ...

PR with full test evidence

/agileflow:pr STORY=US-0042 TITLE="User authentication" TEST_EVIDENCE="
- Unit Tests: 42 passing, 0 failing
- Integration Tests: Login flow verified
- E2E Tests: Desktop and mobile tested
- Coverage: 89%
- Manual: Tested with 2FA, session timeout, etc.
"
 
# Output includes comprehensive test section

PR with partial AC completion

/agileflow:pr STORY=US-0042 TITLE="Login API" AC_CHECKED="
✓ Email/password login
✓ Session persistence
✗ 2FA (out of scope - separate story)
✓ Error handling
"
 
# Checklist shows what was done vs deferred

Team coordination notes

/agileflow:pr STORY=US-0051 TITLE="Payment processing" NOTES="
Coordinated with backend team on webhook signature validation.
Frontend team reviewed API contract and approves.
DevOps confirmed payment processor credentials are configured.
"

PR Description Structure

Header Section

## Summary
 
[Generated from story summary + optional NOTES]
Explains what was built and why at a high level.
 
### Linked Issues
 
- Implements #US-0042
- Depends on #US-0039 (User schema)
- Relates to #EP-0005 (Authentication epic)
 
### Checklist
 
- [x] AC1: Users can login with email/password
- [x] AC2: Invalid credentials show error
- [x] AC3: Sessions persist across page reloads
- [x] AC4: Logout clears session and token

Test Section

### Test Evidence
 
[Formatted TEST_EVIDENCE input or auto-detected from test run]
 
### Screenshots/GIFs
 
[Placeholder for visual evidence if needed]
- Login page
- Success flow
- Error handling
- Session persistence across reloads
 
### Risk Assessment
 
**Potential Impact**:
- Changes authentication flow (affects all users)
- Modifies session handling (potential breakage in existing integrations)
 
**Rollback Plan**:
- Simple revert to previous commit (no database migrations)
- Sessions will remain valid for 24 hours after rollback
- Users may need to log back in if cache cleared
 
### Code Owners
 
@backend-team
@security-team

Conventional Commit Format

PR command suggests a commit message following Conventional Commits:

<type>(<scope>): <subject>
 
<body>
 
<footer>

Examples

Feature:

feat(auth): implement JWT-based user authentication
 
Implements user login with email and password, JWT token
generation, and session persistence.
 
Closes #US-0042

Fix:

fix(auth): prevent session fixation vulnerability
 
Use secure token generation and add CSRF protection
to login endpoint.
 
Closes #US-0043

Docs:

docs(api): add authentication API documentation
 
Documents JWT token generation, validation, and
refresh token flow.
 
Related to #US-0042

Template Sections

Every PR description includes:

Summary - What was built
Linked Issues - Story + dependencies
Checklist - Acceptance criteria status
Test Evidence - How it was verified
Screenshots/GIFs - Visual proof (if applicable)
Risk Assessment - Potential impacts + rollback plan
Code Owners - Who should review

When to Use

After completing a story

# Story implemented and tested
/agileflow:pr STORY=US-0042 TITLE="User authentication"
 
# Copy output, paste into GitHub PR

Submitting to review

# All tests passing, ready for review
/agileflow:pr STORY=US-0042 TITLE="..." TEST_EVIDENCE="42/42 tests passing"
 
# Generate and include in PR body

Multiple dependent stories

# Story with several dependencies
/agileflow:pr STORY=US-0044 TITLE="..."
 
# PR will show all linked stories
# Reviewers can see dependency chain

Tips

Generate PR first, then submit

1. Complete implementation and testing
2. Run /agileflow:pr to generate description
3. Review the output
4. Create PR on GitHub/GitLab
5. Paste the generated description
6. Submit PR

Include comprehensive test evidence

Better test evidence = faster review:

TEST_EVIDENCE="
- Unit Tests: 45/45 passing
- Integration Tests: Login flow, session management
- E2E: Desktop and mobile browsers
- Coverage: 89%
- Manual: Accessibility audit, performance check
"

PR will automatically find:

Story being implemented
Dependencies (other stories)
Related epic
Code owners for review

Use for documentation

Keep PR descriptions as documentation:

Future devs understand the feature
Can reference in architecture docs
Shows testing strategy
Documents risk decisions

Integration with Other Commands

Command	Integration
`/babysit`	Babysit generates PR at end of implementation
`/review`	Run review before PR to catch issues
`/impact`	Include impact analysis notes
`/verify`	Include test results in test evidence section
`/baseline`	PR marks feature ready for baseline/release

Workflow Example

# 1. Work on story with babysit
/agileflow:babysit
# → Choose US-0042
# → Implement with guidance
# → Tests passing
 
# 2. Verify tests before PR
/agileflow:verify US-0042
# → Confirms: test_status: passing
 
# 3. Generate PR description
/agileflow:pr STORY=US-0042 TITLE="User authentication" TEST_EVIDENCE="42/42 tests passing, E2E verified"
# → Copy output
 
# 4. Review code quality
/agileflow:review
# → Fix any issues
 
# 5. Submit PR with generated description
# → Paste PR output to GitHub
# → Submit for review
 
# 6. After merge, mark as done
# → Update status.json: status=completed

Troubleshooting

"Story not found"

Error: Story file does not exist

Fix: Verify story ID is correct:

/agileflow:pr STORY=US-0042 TITLE="..."
# Check that docs/06-stories/US-0042.md exists

"Acceptance criteria formatting issue"

Fix: Ensure AC_CHECKED format matches AC count:

# BAD - Wrong number of items
AC_CHECKED="✓ AC1, ✓ AC2"
 
# GOOD - One per AC in story
AC_CHECKED="✓ AC1, ✓ AC2, ✓ AC3, ✗ AC4"

"Test evidence too long"

Fix: Summarize test evidence:

# Instead of full test output, provide summary
TEST_EVIDENCE="
- Unit tests: 45/45 passing
- Integration: Login flow verified
- E2E: Chrome, Firefox tested
- Coverage: 89%
"

/babysit - Implementation mentor (uses pr at end)
/story - Create stories with AC that pr references
/review - Code review before PR
/verify - Run tests for evidence
/impact - Analyze PR impact
/baseline - Mark feature complete after merge

/review /setup-tests

/pr

/pr

Quick Start

Key Features

Automatic Story Context

Checklist Management

Test Evidence Integration

Conventional Commits

Usage

Basic PR description

PR with test evidence

PR with acceptance criteria status

PR with additional notes

Parameters

Examples

Simple PR from story

PR with full test evidence

PR with partial AC completion

Team coordination notes

PR Description Structure

Header Section

Test Section

Conventional Commit Format

Examples

Template Sections

When to Use

After completing a story

Submitting to review

Multiple dependent stories

Tips

Generate PR first, then submit

Include comprehensive test evidence

Link all related work

Use for documentation

Integration with Other Commands

Workflow Example

Troubleshooting

"Story not found"

"Acceptance criteria formatting issue"

"Test evidence too long"

Related Commands