The Complete PR Workflow

From implementation to pull request to teammate adoption—here is the full end-to-end workflow for sharing decisions through your PR process.

This page walks through every step using the snowflex CI pipeline work (nodes 57–61) as a running example. By the end, your PR will include a decision graph visualization, a structured writeup, and a patch file that teammates can apply after merge.

Step 1: Generate the Visualization

After your implementation work is complete and the decision graph has been populated, start by generating a branch-specific visualization:

Generate graph PNG
deciduous dot --auto --nodes 57-61 --png --title "CI Pipeline Decisions" Wrote docs/decision-graph-ci-pipelines.dot Wrote docs/decision-graph-ci-pipelines.png (5 nodes, 4 edges)

The --auto flag uses the current branch name in the filename. This is important: if you and a teammate both generate decision graphs on separate branches, the files will not conflict at merge time.

Step 2: Export the Patch

Export the decision nodes so teammates can import them into their local databases:

Export the patch
deciduous diff export --nodes 57-61 -o .deciduous/patches/ci-feature.json --author alice Success: Exported 5 nodes and 4 edges to .deciduous/patches/ci-feature.json

Step 3: Commit and Push

Stage the visualization, patch file, and any code changes, then push:

Commit and push
# Stage files explicitly - never use git add -A git add docs/decision-graph-ci-pipelines.dot docs/decision-graph-ci-pipelines.png git add .deciduous/patches/ci-feature.json git commit -m "docs: add decision graph and patch for CI pipelines" git push origin ci-pipelines

Step 4: Create the PR

Use deciduous writeup to generate the PR body, then create the PR with the GitHub CLI:

Create the PR
gh pr create --title "Add CI pipelines for snowflex" \ --body "$(deciduous writeup -t 'Add CI Pipelines' --nodes 57-61 --auto)" Creating pull request for ci-pipelines into main https://github.com/pepsico-ecommerce/snowflex/pull/97

The PR body generated by deciduous writeup includes:

Generated PR body
## Summary **Goal:** Add CI pipelines for snowflex ## Key Decisions ### Use separate workflow files - clearer separation, easier contributor onboarding ## Implementation - Implement unit test CI workflow ## Test Plan - [ ] Verify implementation - [ ] Run test suite ## Decision Graph Reference This PR corresponds to deciduous nodes: 57, 58, 59, 60, 61

When the --auto flag detects a branch-specific PNG file, it embeds an image link in the writeup so reviewers see the graph visualization directly in the PR.

Step 5: Update an Existing PR

If the decision graph evolves during code review, regenerate and update:

Update the PR
deciduous dot --auto --nodes 57-61 --png --title "CI Pipeline Decisions" deciduous diff export --nodes 57-61 -o .deciduous/patches/ci-feature.json --author alice git add docs/decision-graph-ci-pipelines.dot docs/decision-graph-ci-pipelines.png .deciduous/patches/ci-feature.json git commit -m "docs: update decision graph after review" git push origin ci-pipelines # Update the PR body gh pr edit 97 --body "$(deciduous writeup -t 'Add CI Pipelines' --nodes 57-61 --auto)"

Step 6: Teammate Applies the Patch

After the PR is merged, teammates pull the changes and apply the patch to get the decision nodes in their local database:

Teammate applies after merge
git pull origin main Updating abc123..def456 .deciduous/patches/ci-feature.json | 42 +++++++ ... deciduous diff apply .deciduous/patches/ci-feature.json Applied: 5 nodes (5 new, 0 updated), 4 edges (4 new)

Because patches are idempotent, teammates who already applied the patch during review will not get duplicates.

The Full Timeline

When Who Action
Day 1 Alice Creates nodes 57–61 while implementing CI pipelines
Day 2 Alice Exports patch, generates PNG, opens PR with writeup
Day 2 Bob Reviews PR, applies patch to understand decision context
Day 3 Alice Addresses review, updates patch and PR body
Day 3 Bob Re-applies patch (idempotent), approves PR
Day 3 — PR merges to main
Day 4 Carol Pulls main, applies all patches, has full context
Cleanup happens automatically

The GitHub Action created by deciduous init at .github/workflows/cleanup-decision-graphs.yml automatically removes branch-specific PNG and DOT files after a PR is merged, keeping your repository clean.

Always stage files explicitly

Never use git add -A or git add . when working with deciduous. The database file (.deciduous/deciduous.db) is gitignored, but broad staging commands can pick up other unintended files. Always name the specific files you are staging.