name	prd-done
description	Complete PRD implementation workflow - create branch, push changes, create PR, merge, and close issue
category	project-management
disable-model-invocation	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:

📋 **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:

✅ 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:

## 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

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.