shared/north-star-methodology
North-star methodology
Section titled “North-star methodology”How to write and maintain a north-star doc. The how, never the
what — project intent never lives in shared/. Each consumer repo
owns its own docs/north-star/intent.md (or equivalent).
Constraints
Section titled “Constraints”1. Cap of ≤3 docs in docs/north-star/.
Section titled “1. Cap of ≤3 docs in docs/north-star/.”intent.md (or a domain-specific name like agent-fleet.md) is
mandatory. realignment-criteria.md is mandatory once the project has
a measurable convergence target. A third doc is allowed when one is
clearly load-bearing. A fourth landing means retire one — split
attention is drift.
2. North-star outranks the backlog (MR-1).
Section titled “2. North-star outranks the backlog (MR-1).”Every PR and planning conversation opens with: does this serve the
north-star? If no, and it isn’t load-bearing infrastructure (auth,
storage, deploy, schema, contract), it goes to docs/backlog/frozen/.
This is the cheapest decision rule the system has — invoke it early.
3. Realignment criteria are objective.
Section titled “3. Realignment criteria are objective.”realignment-criteria.md defines a measurable gate — a set of claims
each verifiable by a script, a metric, or a fixture. Subjective gates
(“when it feels ready”) are not realignment criteria; they are wishes.
A realignment-met decision doc cites evidence per criterion.
4. North-star changes are decision-doc events.
Section titled “4. North-star changes are decision-doc events.”A north-star edit is the highest-stakes doc change in the repo. It
opens a dated decision doc
(YYYY-MM-DD-north-star-amendment-<slug>.md) citing the trigger (a
finding, a phase-close, a verification round). The amendment includes:
- the diff to
intent.mdor successor doc - which existing decisions / milestones the amendment retires or modifies
- the new realignment criteria, if changed
- explicit human sign-off
Silent edits to north-star content are forbidden by MR-7. A
north-star doc without a paper trail is unanchored.
5. North-star is grounded.
Section titled “5. North-star is grounded.”Every claim in a north-star doc grounds in either (a) the repo’s spec
(docs/spec/) or (b) explicit human input recorded in a decision doc.
Ungrounded ambition (“we want to be the X for Y”) is rejected — the
bootstrap prompt’s anti-invention rule applies recursively.
Anti-patterns
Section titled “Anti-patterns”- Marketing copy. A north-star doc is operational, not aspirational. It is read every PR. If it doesn’t change planning behaviour, it’s the wrong doc.
- Multiple sources of intent. The repo has one north-star doc set.
Other places that look like intent (
README.md,PRODUCT.md,DESIGN.md) project from north-star, never compete with it. - Stale north-star. A north-star that no longer reflects the project’s actual focus is worse than no north-star — it actively misroutes work. The realignment process exists for this. Use it.