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

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.