prd-done

name	prd-done
description	Complete PRD implementation workflow - create branch, push changes, create PR, merge, and close issue
category	project-management

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]

2.5. Pre-PR Verification

• Launch verification agent with the following task:

  Read the full PRD document from top to bottom — all milestones, objectives, and acceptance criteria. For each milestone:

  1. List every success criterion or objective stated for that milestone.
  2. For each criterion, locate observable evidence in the codebase: the specific file that exists, the function that is wired to the main code path, the test that covers it.
  3. Apply the three-level check — Exists (artifact is present) → Substantive (real content, not a stub or placeholder) → Wired (connected and reachable from the running system).
  4. If any level fails, mark the criterion as a gap.

  Report a criterion-by-criterion table: one row per criterion, with a column for the evidence found. Rows with no evidence must say "GAP — no evidence found" with a specific description of what is missing. Do not summarize at a milestone level. Every criterion must map to a specific, observable artifact.

• Surface gaps to the user: Present the verification report. If any gaps are found, stop and ask the user how to proceed before creating the PR. If no gaps, proceed to Step 3.

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
• Run /code-review: Immediately after PR creation, invoke /code-review using the Skill tool. Review all findings at or above the 80-confidence threshold and fix them before merging. The CodeRabbit timer and Anki capture (steps 4.0–4.1) proceed in parallel — only the merge is gated on /code-review findings being addressed. /code-review and CodeRabbit find different issue classes — /code-review catches CLAUDE.md compliance, bugs, and historical context issues; CodeRabbit catches security and correctness issues. If CodeRabbit is rate-limited and never posts, /code-review provides full coverage; do not block indefinitely waiting for CodeRabbit.

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

4.0. Knowledge Capture During Review Wait

After creating the PR and starting the CodeRabbit review timer, use the wait time productively by capturing what was built as Anki cards.

Scope: Cover the ENTIRE PRD, not just recent work. Cards should be sourced from all milestones, the full decision log, and the complete git diff — not limited to the current conversation or the most recent milestone.

• Scan for existing cards: Read files in the Anki finished directory (defined as ANKI_FINISHED_DIR in the /anki skill) to check for cards already covering this PRD's topics. Do not create duplicates of concepts already captured.
• Read the PRD document: Review ALL milestones, the full decision log, architecture choices, and requirements — not just the most recent milestone
• Read key source files: Scan the main files created or modified during implementation (use git diff against main to identify them)
• Invoke the /anki skill: Create flashcards sourced from the PRD and the code — not from conversation context. Focus on:
  • Architectural decisions and why they were made
  • New concepts, patterns, or technologies introduced
  • How components fit together at a high-level
  • Surprising or non-obvious design choices from the decision log
  • Do NOT create cards for implementation minutiae, boilerplate, or things the user already knows

4.1. Check Review Status

• 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:
    • Always fetch all three CodeRabbit channels — CodeRabbit posts to all three and missing any one means missing findings:

      gh api repos/OWNER/REPO/pulls/PR_NUMBER/reviews --jq '[.[] | {user: .user.login, state, body}]'
      gh api repos/OWNER/REPO/pulls/PR_NUMBER/comments --jq '[.[] | {user: .user.login, path, line, body}]'
      gh api repos/OWNER/REPO/issues/PR_NUMBER/comments --jq '[.[] | {user: .user.login, body}]'
      

      • /pulls/{n}/reviews — full review bodies including "outside diff range" findings (most content lives here)
      • /pulls/{n}/comments — inline comments attached to specific diff lines
      • /issues/{n}/comments — conversation-level notices (rate-limit notices, "reviews paused")
    • MCP servers (supplemental when available): Code review MCPs for additional coverage
    • 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)
  • Triage rubric for non-critical findings:
    • Skip if the suggestion is genuinely not helpful or misunderstands the code
    • Skip if the complexity or maintenance cost of the fix outweighs its benefit
    • Fix if the only reason to skip is that it takes time to write — effort alone is not a reason to skip
• 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
• Re-review after pushing fixes: Start another 7-minute timer. Re-run all three gh api calls from above. Repeat the triage loop until no new Fix findings remain (Defer and Skip findings do not block merge). If CodeRabbit is rate-limited, post @coderabbitai review as a PR comment to trigger a re-review.
• 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.