343 lines
18 KiB
Markdown
343 lines
18 KiB
Markdown
---
|
|
name: dot-ai-prd-done
|
|
description: Complete PRD implementation workflow - create branch, push changes, create PR, merge, and close issue
|
|
user-invocable: true
|
|
---
|
|
|
|
# Complete PRD Implementation
|
|
|
|
Complete the PRD implementation workflow including branch management, pull request creation, and issue closure.
|
|
|
|
**Note**: If any `gh` command fails with "command not found", inform the user that GitHub CLI is required and provide the installation link: https://cli.github.com/
|
|
|
|
## Workflow Steps
|
|
|
|
### 0. Implementation Type Detection
|
|
**FIRST: Determine the type of PRD completion to choose the appropriate workflow**
|
|
|
|
**Documentation-Only Completion** (Skip PR workflow):
|
|
- ✅ Changes are only to PRD files or project management documents
|
|
- ✅ No source code changes
|
|
- ✅ No configuration changes
|
|
- ✅ Feature was already implemented in previous work
|
|
- → **Use Simplified Workflow** (Steps 1, 2-simplified, 5 only)
|
|
|
|
**Code Implementation Completion** (Full PR workflow):
|
|
- ✅ Contains source code changes
|
|
- ✅ Contains configuration changes
|
|
- ✅ Contains new functionality or modifications
|
|
- ✅ Requires testing and integration
|
|
- → **Use Full Workflow** (Steps 1-6)
|
|
|
|
### 1. Pre-Completion Validation
|
|
- [ ] **All PRD checkboxes completed**: Verify every requirement is implemented and tested
|
|
- [ ] **Documentation updated**: All user-facing docs reflect implemented functionality
|
|
- [ ] **No outstanding blockers**: All dependencies resolved and technical debt addressed
|
|
- [ ] **Update PRD status**: Mark PRD as "Complete" with completion date
|
|
- [ ] **Archive PRD file**: Move completed PRD to `./prds/done/` directory to maintain project organization
|
|
- [ ] **Update ROADMAP.md (if it exists)**: Remove the completed feature from `docs/ROADMAP.md` roadmap if the file exists
|
|
|
|
**Note**: Tests will run automatically in the CI/CD pipeline when the PR is created. Do not run tests locally during the completion workflow.
|
|
|
|
### 2. Branch and Commit Management
|
|
|
|
**For Documentation-Only Completions:**
|
|
- [ ] **Commit directly to main**: `git add [prd-files]` and commit with skip CI flag
|
|
- [ ] **Use skip CI commit message**: Include CI skip pattern in commit message to avoid unnecessary CI runs
|
|
- Common patterns: `[skip ci]`, `[ci skip]`, `***NO_CI***`, `[skip actions]`
|
|
- Check project's CI configuration for the correct pattern
|
|
- [ ] **Push to remote**: `git pull --rebase origin main && git push origin main` to sync changes
|
|
|
|
**For Code Implementation Completions:**
|
|
- [ ] **Create feature branch**: `git checkout -b feature/prd-[issue-id]-[feature-name]`
|
|
- [ ] **Commit all changes**: Ensure all implementation work is committed
|
|
- [ ] **Clean commit history**: Squash or organize commits for clear history
|
|
- [ ] **Push to remote**: `git push -u origin feature/prd-[issue-id]-[feature-name]`
|
|
|
|
### 3. Pull Request Creation
|
|
|
|
**IMPORTANT: Always check for and use PR template if available**
|
|
|
|
#### 3.1. PR Template Detection and Parsing
|
|
- [ ] **Check for PR template** in common locations:
|
|
- `.github/PULL_REQUEST_TEMPLATE.md`
|
|
- `.github/pull_request_template.md`
|
|
- `.github/PULL_REQUEST_TEMPLATE/` (directory with multiple templates)
|
|
- `docs/pull_request_template.md`
|
|
|
|
- [ ] **Read and parse template comprehensively**: If found, analyze the template to extract:
|
|
- **Structural elements**: Required sections, checklists, format requirements
|
|
- **Content requirements**: What information needs to be provided in each section
|
|
- **Process instructions**: Any workflow enhancements or prerequisites specified in the template
|
|
- **Validation requirements**: Any checks, sign-offs, or verifications mentioned
|
|
|
|
- [ ] **Extract actionable instructions from template**:
|
|
- **Commit requirements**: Look for DCO sign-off, commit message format, commit signing requirements
|
|
- **Pre-submission actions**: Build commands, test commands, linting, format checks
|
|
- **Documentation requirements**: Which docs must be updated, links that must be added
|
|
- **Review requirements**: Required reviewers, approval processes, special considerations
|
|
|
|
**Examples of template instructions to identify and execute:**
|
|
- "All commits must include a `Signed-off-by` line" → Validate commits have DCO sign-off, amend if missing
|
|
- "Run `npm test` before submitting" → Execute test command
|
|
- "PR title follows Conventional Commits format" → Validate title format
|
|
- "Update CHANGELOG.md" → Check if changelog was updated
|
|
- Any bash commands shown in code blocks → Consider if they should be executed
|
|
|
|
#### 3.2. Analyze Changes for PR Content
|
|
- [ ] **Review git diff**: Analyze `git diff main...HEAD` to understand scope of changes
|
|
- [ ] **Review commit history**: Use `git log main..HEAD` to understand implementation progression
|
|
- [ ] **Identify change types**: Determine if changes include:
|
|
- New features, bug fixes, refactoring, documentation, tests, configuration, dependencies
|
|
- Breaking changes or backward-compatible changes
|
|
- Performance improvements or security fixes
|
|
- [ ] **Check modified files**: Identify which areas of codebase were affected
|
|
- Source code files
|
|
- Test files
|
|
- Documentation files
|
|
- Configuration files
|
|
|
|
#### 3.3. Auto-Fill PR Information
|
|
Automatically populate what can be deduced from analysis:
|
|
|
|
- [ ] **PR Title**:
|
|
- Follow template title format if specified (e.g., Conventional Commits: `feat(scope): description`)
|
|
- Extract from PRD title/description and commit messages
|
|
- Include issue reference if required by template
|
|
|
|
- [ ] **Description sections**:
|
|
- **What/Why**: Extract from PRD objectives and implementation details
|
|
- **Related issues**: Automatically link using `Closes #[issue-id]` or `Fixes #[issue-id]`
|
|
- **Type of change**: Check appropriate boxes based on file analysis
|
|
|
|
- [ ] **Testing checklist**:
|
|
- Mark "Tests added/updated" if test files were modified
|
|
- Note: Tests run in CI/CD automatically
|
|
|
|
- [ ] **Documentation checklist**:
|
|
- Mark items based on which docs were updated (README, API docs, code comments)
|
|
- Check if CONTRIBUTING.md guidelines followed
|
|
|
|
- [ ] **Security checklist**:
|
|
- Scan commits for potential secrets or credentials
|
|
- Flag if authentication/authorization code changed
|
|
- Note any dependency updates
|
|
|
|
#### 3.4. Prompt User for Information That Cannot Be Deduced
|
|
**IMPORTANT: Don't just ask - analyze and propose answers, then let user confirm or correct**
|
|
|
|
For each item, use available context to propose an answer, then present it to the user for confirmation:
|
|
|
|
- [ ] **Manual testing results**:
|
|
- **Analyze PRD testing strategy section** to understand what testing was planned
|
|
- **Check git commits** for testing-related messages
|
|
- **Propose testing approach** based on change type (e.g., "Documentation reviewed for accuracy and clarity, cross-references validated")
|
|
- Present proposal and ask: "Is this accurate, or would you like to modify?"
|
|
|
|
- [ ] **Breaking changes**:
|
|
- **Scan commits and PRD** for breaking change indicators
|
|
- If detected, **propose migration guidance** based on PRD content
|
|
- If not detected, **confirm**: "No breaking changes detected. Correct?"
|
|
|
|
- [ ] **Performance implications**:
|
|
- **Analyze change type**: Documentation/config changes typically have no performance impact
|
|
- **Propose answer** based on analysis (e.g., "No performance impact - documentation only")
|
|
- Ask: "Correct, or are there performance considerations?"
|
|
|
|
- [ ] **Security considerations**:
|
|
- **Check if security-sensitive files** were modified (auth, credentials, API keys)
|
|
- **Scan commits** for security-related keywords
|
|
- **Propose security status** (e.g., "No security implications - documentation changes only")
|
|
- Ask: "Accurate, or are there security considerations to document?"
|
|
|
|
- [ ] **Reviewer focus areas**:
|
|
- **Analyze PRD objectives** and **git changes** to identify key areas
|
|
- **Propose specific focus areas** (e.g., "Verify documentation accuracy, check cross-reference links, confirm workflow examples match implementation")
|
|
- Present list and ask: "Are these the right focus areas, or should I adjust?"
|
|
|
|
- [ ] **Follow-up work**:
|
|
- **Check PRD for "Future Enhancements" or "Out of Scope" sections**
|
|
- **Analyze other PRDs** in `prds/` directory for related work
|
|
- **Propose follow-up items** if any (e.g., "Future enhancements listed in PRD: template validation, AI-powered descriptions")
|
|
- Ask: "Should I list these, or is there other follow-up work?"
|
|
|
|
- [ ] **Additional context**:
|
|
- **Review PRD for special considerations**
|
|
- **Check if this is a dogfooding/testing PR**
|
|
- **Propose any relevant context** (e.g., "This PR itself tests the enhanced workflow it documents")
|
|
- Ask: "Anything else reviewers should know?"
|
|
|
|
**Presentation Format:**
|
|
Present all proposed answers together in a summary format:
|
|
```markdown
|
|
📋 **Proposed PR Information** (based on analysis)
|
|
|
|
**Manual Testing:** [proposed answer]
|
|
**Breaking Changes:** [proposed answer]
|
|
**Performance Impact:** [proposed answer]
|
|
**Security Considerations:** [proposed answer]
|
|
**Reviewer Focus:** [proposed list]
|
|
**Follow-up Work:** [proposed items or "None"]
|
|
**Additional Context:** [proposed context or "None"]
|
|
|
|
Please review and respond:
|
|
- Type "yes" or "confirm" to accept all
|
|
- Specify corrections for any items that need changes
|
|
```
|
|
|
|
#### 3.5. Execute Template Requirements
|
|
**IMPORTANT: Before creating the PR, identify and execute any actionable requirements from the template**
|
|
|
|
- [ ] **Analyze template for actionable instructions**:
|
|
- Scan template content for imperative statements, requirements, or commands
|
|
- Look for patterns like "must", "should", "run", "execute", "ensure", "verify"
|
|
- Identify bash commands in code blocks that appear to be prerequisites
|
|
- Extract any validation requirements mentioned in checklists
|
|
|
|
- [ ] **Categorize identified requirements**:
|
|
- **Commit-level actions**: Sign-offs, formatting, validation
|
|
- **Pre-submission commands**: Tests, builds, lints, format checks
|
|
- **Validation checks**: File existence, format compliance, content requirements
|
|
- **Documentation actions**: Required updates, links to add
|
|
|
|
- [ ] **Propose and execute requirements**:
|
|
- Present identified requirements to user: "Template specifies these actions: [list]"
|
|
- For each requirement, determine if it can be automated
|
|
- Propose execution: "Should I execute these now?"
|
|
- Execute confirmed actions and report results
|
|
- Handle failures gracefully and ask user how to proceed
|
|
|
|
- [ ] **Summary before PR creation**:
|
|
```markdown
|
|
✅ Template Requirements Status:
|
|
[List each requirement with status: executed/validated/skipped/failed]
|
|
|
|
Ready to create PR? (yes/no)
|
|
```
|
|
|
|
#### 3.6. Detect and Apply PR Label (if release.yml exists)
|
|
|
|
**IMPORTANT: Only apply labels if `.github/release.yml` exists - fully dynamic based on that file**
|
|
|
|
- [ ] **Check for `.github/release.yml`**:
|
|
- If file exists → Proceed with label detection
|
|
- If file doesn't exist → Skip label detection, proceed to create PR without labels
|
|
|
|
- [ ] **If release.yml exists, parse it to understand available categories and labels**:
|
|
- Read the YAML file
|
|
- Extract all category definitions with their associated labels
|
|
- Build a mapping of: category → list of labels
|
|
- Note the category order (categories listed first are typically more important)
|
|
|
|
- [ ] **Analyze PR characteristics**:
|
|
- **Primary change type**: What is the MAIN purpose of this PR?
|
|
- **File changes**: Types of files modified (extensions, paths, purposes)
|
|
- **Change scope**: Which areas of codebase affected
|
|
- **Commit messages**: Keywords, patterns, prefixes
|
|
- **PR title and description**: Keywords indicating change type
|
|
- **PRD context**: Original problem/solution description
|
|
|
|
- [ ] **Select the SINGLE best-matching label**:
|
|
- For each category in release.yml, score how well it matches the PR's PRIMARY purpose
|
|
- Consider the importance hierarchy from release.yml:
|
|
- Breaking changes > New features > Bug fixes > Documentation > Dependencies > Other
|
|
- Select ONE label from the category that BEST represents the main change
|
|
- **Why single label?**: Prevents PRs from appearing in multiple release note categories
|
|
- **Selection priority**:
|
|
1. If any breaking changes → use `breaking-change` or `breaking`
|
|
2. If primarily new functionality → use `feat`, `feature`, or `enhancement`
|
|
3. If primarily fixing bugs → use `fix`, `bug`, or `bugfix`
|
|
4. If primarily documentation → use `documentation` or `docs`
|
|
5. If primarily dependencies → use `dependencies`, `deps`, or `dependency`
|
|
6. Otherwise → no specific label needed (will appear in "Other Changes")
|
|
|
|
- [ ] **Apply detected label**: Add the single best-matching label to the PR creation command
|
|
- Example: `gh pr create --title "..." --body "..." --label "fix"`
|
|
|
|
#### 3.7. Create Pull Request
|
|
- [ ] **Construct PR body**: Combine auto-filled and user-provided information following template structure
|
|
- [ ] **Create PR**:
|
|
- If label detected: `gh pr create --title "[title]" --body "[body]" --label "[single-label]"`
|
|
- If no release.yml or no matching label: `gh pr create --title "[title]" --body "[body]"`
|
|
- [ ] **Verify PR created**: Confirm PR was created successfully, template populated correctly, and label applied (if applicable)
|
|
- [ ] **Request reviews**: Assign appropriate team members for code review if specified
|
|
|
|
#### 3.8. Fallback for Projects Without Templates
|
|
If no PR template is found, create a sensible default structure:
|
|
|
|
```markdown
|
|
## Description
|
|
[What this PR does and why]
|
|
|
|
## Related Issues
|
|
Closes #[issue-id]
|
|
|
|
## Changes Made
|
|
- [List key changes]
|
|
|
|
## Testing
|
|
- [Testing approach and results]
|
|
|
|
## Documentation
|
|
- [Documentation updates made]
|
|
```
|
|
|
|
### 4. Review and Merge Process
|
|
- [ ] **Check ongoing processes**: Use `gh pr checks [pr-number]` to check for any ongoing CI/CD, security analysis, or automated reviews (CodeRabbit, CodeQL, etc.)
|
|
- [ ] **Check PR details**: Use `gh pr view [pr-number]` to check for human review comments and PR metadata
|
|
- [ ] **Review all automated feedback**: Check PR comments section for automated code review feedback (bots, linters, analyzers)
|
|
- **Use multiple methods to capture all feedback**:
|
|
- **MCP servers** (preferred when available): Use any available MCP servers for comprehensive review data
|
|
- Code review MCPs (e.g., CodeRabbit, custom review servers) for detailed AI code reviews
|
|
- Check available MCP tools/functions related to code reviews, pull requests, or automated feedback
|
|
- CLI commands: `gh pr view [pr-number]`, `gh pr checks [pr-number]`, `gh api repos/owner/repo/pulls/[pr-number]/comments`
|
|
- **Web interface inspection**: Fetch the PR URL directly to capture all comments, including inline code suggestions that CLI tools may miss
|
|
- Look for comments from automated tools (usernames ending in 'ai', 'bot', or known review tools)
|
|
- [ ] **Present ALL code review findings**: ALWAYS present every review comment to the user, regardless of severity
|
|
- **Show ALL comments**: Present every suggestion, nitpick, and recommendation - do not filter or omit any
|
|
- **Categorize findings**: Critical, Important, Optional/Nitpick based on impact
|
|
- **Provide specific examples**: Quote actual suggestions and their locations
|
|
- **Explain assessment**: Why each category was assigned
|
|
- **User decision**: Let user decide which improvements to implement before merge (critical items must be addressed, others are user's choice)
|
|
- [ ] **Assess feedback priority**: Categorize review feedback
|
|
- **Critical**: Security issues, breaking changes, test failures - MUST address before merge
|
|
- **Important**: Code quality, maintainability, performance - SHOULD address for production readiness
|
|
- **Optional**: Style preferences, minor optimizations - MAY address based on project standards
|
|
- [ ] **Wait for ALL reviews to complete**: Do NOT merge if any reviews are pending or in progress, including:
|
|
- **Automated code reviews** (CodeRabbit, CodeQL, etc.) - Must wait until complete even if CI passes
|
|
- **Security analysis** - Must complete and pass
|
|
- **CI/CD processes** - All builds and tests must pass
|
|
- **Human reviews** - If requested reviewers haven't approved
|
|
- **CRITICAL**: Never skip automated code reviews - they provide valuable feedback even when CI passes
|
|
- [ ] **Address review feedback**: Make required changes from code review (both automated and human)
|
|
- Create additional commits on the feature branch to address feedback
|
|
- Update tests if needed to cover suggested improvements
|
|
- Document any feedback that was intentionally not addressed and why
|
|
- [ ] **Verify all checks pass**: Ensure all CI/CD, tests, security analysis, and automated processes are complete and passing
|
|
- [ ] **Final review**: Confirm the PR addresses the original PRD requirements and maintains code quality
|
|
- [ ] **Merge to main**: Complete the pull request merge only after all feedback addressed and processes complete
|
|
- [ ] **Verify deployment**: Ensure feature works in production environment
|
|
- [ ] **Monitor for issues**: Watch for any post-deployment problems
|
|
|
|
### 5. Issue Closure
|
|
- [ ] **Update issue PRD link**: Update the GitHub issue description to reference the new PRD path in `./prds/done/` directory
|
|
- [ ] **Close GitHub issue**: Add final completion comment and close
|
|
- [ ] **Archive artifacts**: Save any temporary files or testing data if needed
|
|
- [ ] **Team notification**: Announce feature completion to relevant stakeholders
|
|
|
|
### 6. Branch Cleanup
|
|
- [ ] **Switch to main branch**: `git checkout main`
|
|
- [ ] **Pull latest changes**: `git pull origin main` to ensure local main is up to date
|
|
- [ ] **Delete local feature branch**: `git branch -d feature/prd-[issue-id]-[feature-name]`
|
|
- [ ] **Delete remote feature branch**: `git push origin --delete feature/prd-[issue-id]-[feature-name]`
|
|
|
|
## Success Criteria
|
|
✅ **Feature is live and functional**
|
|
✅ **All tests passing in production**
|
|
✅ **Documentation is accurate and complete**
|
|
✅ **PRD issue is closed with completion summary**
|
|
✅ **Team is notified of feature availability**
|
|
|
|
The PRD implementation is only considered done when users can successfully use the feature as documented.
|
|
|