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:

• If any breaking changes → use breaking-change or breaking

• If primarily new functionality → use feat , feature , or enhancement

• If primarily fixing bugs → use fix , bug , or bugfix

• If primarily documentation → use documentation or docs

• If primarily dependencies → use dependencies , deps , or dependency

• 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

• 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.