docs(vision): add North Star — what to optimize for on product decisions - #14
Conversation
Adds docs/vision/BILLBUFFER_NORTH_STAR.md — an intentionally short compass answering one question: when a product decision is genuinely open, what do you optimize for? Answer: a person's confidence in the moment "Can I safely spend this right now?" — clearer, calmer, quicker to trust. Positioned as the objective function that sits alongside (not over) the Constitution's constraints and the Philosophy's beliefs, and references both rather than restating them, to avoid duplication. Indexed in docs/README.md and the root README Vision map. Planning-only: no application code, architecture, engineering, roadmap, or marketing. Product philosophy only. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Per review, three changes only: - North Star: add the operative line "When two valid product decisions compete, the North Star decides which one wins." - North Star: add a permanent principle — "BillBuffer never confidently answers with incomplete information." - READMEs: set the required reading order to Constitution → North Star → Philosophy → Architecture Guardrails → Engineering Doctrine (PR_VETTING_DOCTRINE.md). Constitution and Philosophy unchanged. North Star kept intentionally short. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The required reading order links the Engineering Doctrine (PR_VETTING_DOCTRINE.md), but the documentation map did not list it. Add it to the Engineering index in both READMEs (root map table, docs tier gloss, and full index) so the map and the reading order agree. No other changes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f9bfa2ec34
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 2. [`docs/vision/BILLBUFFER_NORTH_STAR.md`](./docs/vision/BILLBUFFER_NORTH_STAR.md) — what to optimize for when a product decision is open. | ||
| 3. [`docs/vision/BILLBUFFER_PHILOSOPHY.md`](./docs/vision/BILLBUFFER_PHILOSOPHY.md) — core beliefs, the "NOT list", and the banned-word dictionary. | ||
| 4. [`docs/architecture/ARCHITECTURE_GUARDRAILS.md`](./docs/architecture/ARCHITECTURE_GUARDRAILS.md) — the non-negotiable technical rules the Constitution implies. | ||
| 5. [`docs/engineering/PR_VETTING_DOCTRINE.md`](./docs/engineering/PR_VETTING_DOCTRINE.md) — how BillBuffer protects its promises, and how pull requests are vetted. |
There was a problem hiding this comment.
For production contributors who follow this README before touching code, this new five-doc list now stops at PR_VETTING_DOCTRINE.md and no longer points them to PRODUCTION_IMPLEMENTATION_BRIEF.md, CALCULATION_ENGINE_SPEC.md, or TEST_MATRIX.md, even though this README says the docs are the source of truth and that production starts from the implementation brief. That makes the onboarding path skip the product goal/data model/engine rules/test coverage that code changes must satisfy; docs/README.md mirrors the same omission, so either keep those engineering docs in the required list or scope this list to vision/PR-review decisions.
Useful? React with 👍 / 👎.
The single reading list stopped at the governance/PR docs and dropped the implementation docs contributors need before touching code. Split it into two ordered sections in both READMEs, keeping all five governance docs: - Before product/architecture decisions: Constitution, North Star, Philosophy, Architecture Guardrails, PR Vetting Doctrine. - Before implementation/code changes (everything above, plus): Production Implementation Brief, Calculation Engine Spec, Test Matrix, and any directly relevant screen/feature doc. Reading-order section only. Prettier clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
@codex review |
|
Codex Review: Didn't find any major issues. Keep it up! Reviewed commit: ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". |
1 participant
Planning-only — docs only. No application code, architecture, roadmap, or marketing.
Introduces a repository North Star: an intentionally short page answering one question —
Answer: a person's confidence in a single moment — "Can I safely spend this right now?" — made clearer, calmer, and quicker to trust.
Location
docs/vision/BILLBUFFER_NORTH_STAR.md— the Vision tier, beside the Constitution and Philosophy.Why a new doc (not a merge) and how it avoids duplication
The Vision tier already has two docs; this is a distinct third function, so it complements rather than repeats:
It references the Constitution and Philosophy instead of restating them, defers to the Constitution explicitly, and points architecture/engineering trade-offs at the Guardrails.
Wording
Synthesized to be consistent with existing canon — uses in-vocabulary terms ("safe to spend", "trust", "calm", "no false certainty") and stays clear of the Philosophy's banned dictionary (no "budget", "cash flow", etc.).
References added
docs/README.md— Vision index + tier description.README.md— Vision docs map.The task referenced an "attached draft" that did not reach the tooling, so this text is synthesized from the Constitution + Philosophy as a faithful starting point. Wording is explicitly not final — drop in your draft and I'll reconcile.
🤖 Generated with Claude Code