Technical plan / Draft 03
Usage ledger migration
Rollout strategy
Dual-write for seven days, then switch reads after the reconciliation rate stays above 99.9%.1
events → ledger_v2 → audit
Technical design document review
Keep the plan in Git.
Review it like a document.
Stop copying an engineering plan into Google Docs or Notion just to get useful feedback. Bring the Markdown into Nativ Docs, discuss the exact passages that matter, then commit the decisions back to the repo.
feat/usage-ledger
docs/plans/usage-ledger.mdcommit 8f4c2a1SK
SamiraSecurity · 4m
What happens if reconciliation drops after the read switch?
Rollback threshold added
02 / The two-copy problem
The plan wants to stay in Git.
The review wants a margin.
Technical teams choose Markdown in the repo because it stays close to the code. They choose Docs or Notion because more people can read and comment there. The copy between them is where the plan splits.
Two drafts look authoritative
The committed plan changes. The pasted review copy does not—or the review copy changes without a matching commit.
Feedback loses its destination
A Slack answer, a Notion comment, and a PR note each explain part of the decision. The next draft has to reconstruct it.
The review audience gets smaller
PR diffs work for engineers. Product, design, security, and operations need the rendered proposal and its full context.
03 / One source, one review room
Keep the commit.
Lose the copy-paste loop.
Nativ sits beside your repository workflow. The file stays where engineers maintain it. The discussion gets a place built for the whole team.
- 01
Write the plan beside the code
Keep the RFC, ADR, implementation plan, or technical design as Markdown in the relevant repository.
- 02
Bring the draft into Nativ
Upload the Markdown file, or create the review copy from a connected MCP client. Nativ renders the plan as a readable document.
- 03
Review the actual proposal
Invite the people whose judgment matters. They can select exact text, reply in a thread, and resolve the discussion.
- 04
Commit the decision
Apply the resolved feedback to the next version of the plan and commit it back to the repository.
04 / Different jobs, same plan
A technical review everyone can enter.
GitHub stays the engineering system of record. Nativ gives every reviewer the view they need to participate before implementation starts.
05 / The division of labor
Don’t replace GitHub. Stop duplicating it.
| Need | GitHub | Docs / Notion copy | Nativ review |
|---|---|---|---|
| Canonical plan | Repository file | Competing copy | Review version |
| Reading experience | Markdown or diff | Rendered document | Rendered document |
| Contextual discussion | PR lines | Inline comments | Anchored threads |
| Review outcome | Merge state | Scattered resolutions | Resolved decisions |
06 / Questions
Technical design review, clarified.
How can a team review a technical design document in GitHub?
Keep the Markdown plan in the repository, bring the file into Nativ Docs, and invite reviewers to comment on exact passages in the rendered document. Fold the resolved feedback into the next commit so Git remains the source of truth.
Does Nativ Docs replace GitHub?
No. GitHub remains the home for the plan and its commit history. Nativ is the review room where engineers and cross-functional teammates can read the rendered plan, discuss it in context, and capture decisions.
Can non-engineers review a Markdown technical plan?
Yes. Nativ renders Markdown as a readable document, so product, design, security, and operations teammates can review the plan without navigating a diff or editing repository files.
Does Nativ Docs sync comments back to GitHub?
Not directly today. Reviewers discuss and resolve threads in Nativ, then the plan owner incorporates the decisions into the repository's next revision. A connected MCP client can create and update Nativ documents from an agent workflow.
The plan belongs in Git.
The team belongs in the review.
Bring your next Markdown plan into Nativ Docs.
Start a technical design review