Git Workflow for Product Docs

MOMENTUM treats product documentation as a first-class asset that lives in Git alongside code. This guide explains how to version, review, and collaborate on product strategy, epics, and stories.

Core Principle: Intentionality

Strategy changes should be intentional and reviewable.

Use Git to preserve history and make decisions visible – but don't create bureaucracy. The workflow differs based on what you're changing.

Fast Lane vs. Review Lane

Two tiers of review based on impact and reversibility:

Fast Lane (Direct Commits)

Who: Individual contributor or small team
When: Low-risk, easily reversible changes
Where: Commit directly to main

Use cases:

Raw meeting notes in /meetings/
Raw discovery inputs in /discovery/inputs/
New story files (draft status) under /delivery/
Minor copy edits or link fixes in epics and non-shipped stories
Updates to /discovery/insights.md (curated, not strategy-bearing)

Commit message style:

Add meeting notes from 2025-02-08 design review

Decisions: deprecate in-app password reset, create EP-004 for 3DS recovery.
Extracted from meetings/2025-02-08-design-review.md

Review Lane (Branch + Pull Request)

Who: Team lead or PM + reviewers
When: High-impact changes that shape product direction
Where: Feature branch, open PR, request review

Use cases:

Changes to product-strategy.md (any scope, goal, or positioning change)
Significant updates to product-evidence.md (changes that justify new strategy decisions)
Epic scope changes (modified "Functional Scope" or "Out of Scope" sections)
Changes to .llm/ files or agent.md (affects how LLM behaves)
New or updated writing conventions in writing-instructions.md

Branch naming:

feat/epic-003-checkout-shaping

PR description:

# Update Checkout Epic Scope

From design review (meetings/2025-02-08-design-review.md):

- Deprecate in-app password reset
- Add 3-D Secure error recovery flow
- Update EP-003 scope and risks

Decision made by: [PM name] + [design lead name]
Reviewed with: [other stakeholders]

Approval: At minimum, one other person (PM lead, design, or engineering) reviews and approves.

Practical Workflow Example

Scenario 1: New Meeting Happens

1. Take meeting notes
2. Commit directly to main:
   git add meetings/2025-02-08-design-review.md
   git commit -m "Add design review notes (2025-02-08)"
   git push origin main

✅ Fast, visible in Git history, easy to reference.

Scenario 2: Meeting Decisions Change Epic Scope

1. Capture meeting in /meetings/ (direct commit)
2. Create a feature branch for strategy/epic updates:
   git checkout -b feat/ep003-scope-update
3. Update:
   - product-strategy.md (if applicable)
   - /delivery/epic-003-*/epic-003-*.md
4. Create pull request with link to meeting:
   - References meetings/2025-02-08-design-review.md
   - Explains what changed and why
5. Request review from PM lead + design
6. Once approved, merge to main

✅ Big decisions are visible, reviewable, and traceable.

Scenario 3: New Discovery Insight

1. Raw notes: Commit directly
   git add discovery/inputs/2025-02-05-customer-call-raw.md
   git commit -m "Add customer call notes (ACME Corp)"

2. Curate into insights: Commit directly
   git add discovery/insights.md  
   git commit -m "Extract 2 new insights from Feb calls (INS-012, INS-013)"

3. Proposed epic from insight: Use review lane if it changes strategy
   git checkout -b feat/ep004-3ds-recovery
   git add /delivery/epic-004-3ds-recovery/ product-strategy.md
   git commit -m "Create EP-004 from INS-012 (3-D Secure recovery)"
   git push origin feat/ep004-3ds-recovery
   # (create PR, request review)

✅ Raw research moves fast; strategic decisions get reviewed.

Frequency & Rhythm

Daily / As-Needed

Commit raw notes and inputs (meetings, discovery calls, feedback)
Commit new draft stories
Minor edits to non-shipped artifacts

Weekly

Curate insights from inputs
Review and propose strategy/epic updates (create PRs)
Merge approved changes

Monthly (or per release)

Archive old meeting notes and research
Update context files and summary docs
Refresh /ops/status.md if you're using it

Handling Merge Conflicts

If two people edit the same epic or strategy file:

Check who changed what:

git log -p product-strategy.md | head -50

Decide the truth:
Is one version clearly newer/better?
Do both changes apply together?
Should we talk through this?
Resolve manually (texts in Markdown are usually easy to merge)
Verify coherence:
If strategy changed, did epic scope stay aligned?
If epic changed, do stories still match?

Prevention: Keep .pdf or detailed changes to one person per week, or stagger who edits strategy vs. epics.

Protection Rules (Optional, Advanced)

If you're using GitHub/GitLab, consider branch protection:

# Protect 'main' branch

Require pull request reviews:
  - Require at least 1 approval
  - Dismiss stale reviews when new commits are pushed

Require status checks:
  - Lint (front-matter, Markdown syntax)
  - Link validation (internal anchors, external URLs)

Require branches to be up to date before merging

This ensures strategy changes always have a second set of eyes.

Squashing, Rewriting, and Amending

When working on a feature branch:

✅ Do: Squash commits before merging to main

git rebase -i main  # squash related commits
git push origin feat/epic-003-scope-update -f

❌ Don't: Rewrite history on main once merged (it breaks everyone's local branches)

Why? Squashing keeps main clean and readable while you're iterating. Once merged, main's history is the source of truth – don't change it.

Reading Git History for Context

After a few weeks, your repo tells a story through commits:

# See recent changes to strategy
git log --oneline product-strategy.md

# See when an epic was created
git log --oneline /delivery/epic-003-*/

# Trace all changes related to a design decision
git log --all --grep="3DS recovery" --oneline

# See who's been active
git shortlog -sn --all --since="2 weeks"

This is powerful for onboarding, audits, and retrospectives: "When did we decide that? Who was involved?"

Collaboration Norms

Before Committing / Opening a PR

Read recent PRs and commits to understand current direction
Mention in Slack or planning doc that you're working on X
Ask for async feedback before creating a PR if you're uncertain

In the PR

Link to source meetings, insights, data, or decisions
Explain not just what changed, but why
Tag reviewers explicitly (don't rely on auto-notification)
Be ready to iterate; feedback is collaborative refinement, not rejection

After Merge

Close any related tickets or issues
If it was a big change, drop a note in the team channel: "Updated EP-003 scope based on design review – see PR #456"
Mark old artifacts as deprecated if superseded (don't delete)

Over Time: Keeping History Clean

As your repo grows:

Compress context – Old meeting notes move to /meetings/archive/; current decisions live in delivery-context.md
Archive epics – Once shipped, move to /delivery/archive/ if no longer active
Reference, don't duplicate – Link to old decisions rather than copying them into new docs

See Context Compression & Archiving for guidance on keeping the working set manageable.

Tl;dr Checklist

Change	Commit Type	Approval?	Notes
Raw meeting notes	Direct	No	Fast; visible history
New story (draft)	Direct	No	Can iterate later if needed
Minor copy fix	Direct	No	Easily reversible
Insight synthesis	Direct	No	Curation, not strategy
Strategy change	PR	Yes	High impact; must review
Epic scope change	PR	Yes	Affects delivery roadmap
`.llm/` or `agent.md` change	PR	Yes	Affects LLM behavior
Archive old files	Direct or PR	Maybe	Direct if < 5 files; PR if refactoring large areas