Open Contribution — The Bigger Picture

[lfnovo]

Open Contribution — The Bigger Picture

Status: essay / request for feedback. This describes the contribution system we want to build for Open Notebook — not a finished framework, and not (yet) normative documentation. We are publishing it so the community can shape it before it hardens.

The first piece of this system is already live: Current Bet #1 — Ideas in Discussions, executable work in Issues. This essay is the direction those bets are heading.

The thesis

As AI coding tools make execution cheaper, the scarce resources in an open-source project shift. They are no longer "hands to write code." They are:

• shared context;
• decision quality;
• the ability to decompose a vision without fragmenting it;
• the ability to prove that the result delivers the promise that motivated it.

The goal is not just to receive more code. It is to let the community participate in problem discovery, vision, design, architecture, building, and validation of the product.

AI works as a layer of coordination, memory, synthesis, and quality control. It does not replace human authority or human responsibility.

How to read this document

Two honesty notes before the details:

1. Most of this does not exist yet as automation. Wherever this essay says "AI does X," read it as the destination. Today that work is done by maintainers — assisted by AI tools, manually and unevenly. Each piece of the system will go live the way Bet #1 did: as a numbered, observable experiment with explicit criteria for keeping, modifying, or reverting it.

2. Authority is currently concentrated, by necessity. Today the maintainers are the decision owners for everything. The role structure described below (decision owners, stewards, validators) exists so that responsibility can be progressively delegated as the community grows — it is not a claim that this governance already operates.

Operating principle

The workflow is two connected funnels:

flowchart LR
    subgraph discovery["Discovery funnel — Discussions"]
        direction LR
        A[Signal] --> B[Problem] --> C[Exploration] --> D[Decision]
    end
    subgraph delivery["Delivery funnel — GitHub Issues"]
        direction LR
        E[Specification] --> F[Issues] --> G[PRs] --> H[Validation]
    end
    D --> E

Loading

The central boundary is:

While we are discussing whether to do something and which direction to take, we are in Discussions. When there is a verifiable commitment to execute, an Issue is born.

This boundary is already live as Bet #1.

One more principle: shipped product does not mean merged code. It means behavior validated against the promise that originated the initiative.

The workflow at a glance

Stage	Main artifact	Role of AI	Human gate
1. Signal	Discussion	Classifies, finds duplicates, connects conversations	Is the problem worth exploring?
2. Qualification	Problem brief	Extracts use cases, impact, open questions	Does it align with the vision?
3. Exploration	Structured Discussion	Organizes opinions, alternatives, conflicts	Do we understand the problem well enough?
4. Synthesis	Synthesis post	Summarizes with provenance, records disagreements	Does the synthesis represent the conversation?
5. Decision	Decision note, PDR or ADR	Checks coherence and consequences	Do, don't do, or park?
6. Specification	Initiative brief or RFC	Maintains contracts, risks, validation criteria	Ready to decompose?
7. Delivery	Umbrella, sub-issues, PRs	Prepares context, detects drift	Is each unit ready and correct?
8. Validation	Validation dossier	Analyzes tests, evals, scenarios	Was the promise delivered?
9. Learning	Release outcome	Compares hypothesis and result	What do we fold back into the system?

1. Entry: anyone can bring a signal

Entry happens in an Ideas Discussion. The form does not demand a sophisticated solution. It asks:

• What were you trying to do?
• What happened, or what was hard?
• Who does this matter to?
• How do you work around it today?
• What outcome would you like?
• Would you be available to test or collaborate?

A maintainer idea, a feature request, and a user pain all enter through the same door. This intake is already live (Bet #1).

Where we want to go next: on arrival, AI immediately

• finds related Discussions, Issues, and PRs;
• suggests whether the proposal is a duplicate or part of a larger initiative;
• pulls the relevant parts of VISION.md and the decision records;
• produces a small context sheet;
• asks clarifying questions.

That lowers the cost of participating without requiring the person to already know the project's architecture.

2. Qualification: problem before solution

At this stage we decide whether there is something worth understanding — not whether we will build.

Possible outcomes:

• Explore: there is an aligned, still-open problem.
• Combine: the signal joins an existing canonical Discussion.
• Answer: a solution or documentation already exists.
• Park: interesting, but does not fit the current posture.
• Decline: conflicts with principles or scope.
• Bug: the problem is reproducible and goes straight to an Issue.

Every outcome comes with an explanation. Parked is not limbo: it must say what condition would bring the proposal back.

3. Exploration: the community helps shape the direction

A qualified proposal enters a discovery round. The Discussion gains four blocks, kept up to date (eventually by AI, today by maintainers):

• what we know;
• what we don't know yet;
• alternatives under consideration;
• decisions made and open questions.

The community can contribute in many currencies: use cases, counterexamples, technical constraints, references from other products, prototypes, performance data, accessibility reviews, interest in building or testing.

For large topics, exploration can run in rounds:

1. Problem: are we solving the right thing?
2. Directions: which approaches exist?
3. Challenge round: what could go wrong?
4. Validation: how will we know it worked?

Each round ends with a synthesis, so nobody has to read the whole thread before joining.

4. Synthesis: compress without erasing

A synthesis post captures:

• the validated problem;
• recurring use cases;
• alternatives and trade-offs;
• points of convergence;
• disagreements;
• remaining questions;
• people interested in building or validating.

Every important conclusion links back to the comments that originated it. The synthesis does not decide. The proposer and the community can correct it before the human gate.

5. Decision: explicit authority

Every relevant Discussion has a decision owner. That owner can decide:

• Accepted: the project takes on the problem.
• Experiment: worth testing before committing.
• Parked: valid, but not now.
• Declined: does not fit the product.
• Superseded: absorbed by another initiative.
• Needs more evidence: one specific piece of information is missing.

Accepting a problem does not automatically accept the proposed implementation.

The decision records: what we are committing to, why now, what we are not committing to, which principles are invariant, what remains delegable, and who decides the next questions. Structural decisions produce an ADR or PDR.

6. Specification: turning direction into a contract

Small changes can go straight to an Issue. Large ones produce a versioned Initiative Brief or RFC containing: the promise to the user, scope and non-goals, principles and invariants, the conceptual model, relevant technical contracts, UX journeys and states, risks, migration strategy, validation criteria, open decisions, and a split into vertical slices.

The most important requirement:

The specification must say how to invalidate it.

Before writing code, we need to know which results would make the solution insufficient.

7. Decomposition: only now are Issues born

The initiative becomes an umbrella with sub-issues. Each Issue must be independently assignable and contain: the minimum necessary context, expected outcome, contracts it must not break, out-of-scope list, dependencies, acceptance criteria, required evidence, and links to the Discussion, RFC, and decisions. At that moment it gets ready.

A contributor should not have to rebuild the whole architecture in their head. AI prepares a context pack for that specific unit of work.

Three roles are distinct:

• Builder: implements.
• Reviewer: evaluates quality and coherence.
• Validator: tries to prove the solution does not work.

In higher-risk changes, builder and validator should ideally be different people. In small contributions, one person can hold multiple roles.

8. PR: implementation accompanied by proof

A PR answers four questions:

1. Which contract is it implementing?
2. Which risks does it introduce?
3. How was it tested?
4. What evidence demonstrates the result?

The system compares Discussion → decision → RFC → Issue → diff → tests and flags: scope that appeared without being decided, uncovered acceptance criteria, violated invariants, missing documentation or migration, changes that should produce an ADR/PDR, and tests that assert something different from the original promise.

9. Validation: product, not just code

Four validation gates:

• Engineering: tests, types, security, migration, deploy.
• System: performance, cost, providers, installation, degradation.
• Experience: UX, mobile, accessibility, error states.
• Outcome: can the person achieve the promised result?

For AI and retrieval features there are also evals: retrieval quality, citation correctness, behavior when there is no evidence, cross-source comparison, latency and cost, the provider/local-model matrix, and regressions on already-validated questions.

The validation dossier is attached to the initiative and evolves during implementation.

10. Closing the loop: return the result to the community

When the initiative reaches users, the original Discussion receives: what was delivered, what changed versus the proposal, what was left out, how to test it, which release it shipped in, and which questions remain open.

After real usage, an outcome review asks: did the hypothesis hold? what feedback appeared? which bugs escaped? which manual test should become automated? which principle or document needs updating?

The product feeds the next cycle of ideas.

Migrating the historical backlog

The existing backlog should be treated as a knowledge migration, not a mechanical cleanup. Existing Issues and Discussions can have different destinies:

Situation found	Destination
Reproducible bug	Stays an Issue
Work already decided and executable	Stays an Issue, gets ready
Single idea still open	Converted to a Discussion
Several proposals on the same theme	One canonical Discussion; the rest become evidence
Pending product or architecture decision	Initiative Discussion or RFC
Usage or support question	Q&A, documentation, or closure
Already implemented	Closed with a link to the PR or release
Superseded by the current vision	Closed explaining what replaced it
Interesting, but outside the current posture	Preserved as a Discussion with explicit status

The goal is to recover real reported problems, the people behind them, arguments and alternatives, demand signals, implicit decisions, and proposals that now fit a more mature vision. Migration should group items into initiatives and publish canonical syntheses — not convert dozens of Issues into dozens of isolated Discussions.

Example: how a large initiative would flow

1. Several signals about the same recurring theme are grouped together.
2. The community discusses use cases, current failures, and expectations.
3. A synthesis captures the underlying thesis.
4. The decision owner establishes the invariants the solution must respect.
5. A named initiative is born, with a brief.
6. The first vertical slice is chosen: the smallest piece that delivers the core promise.
7. The slice generates Issues for contracts, backend, UI, mobile, accessibility, and evals.
8. Builders implement in parallel against the same contracts.
9. Validators run the evaluation corpus and the UX scenarios.
10. The community receives the slice to test, and the learning feeds the next slice.

Distribution of authority

The process must distribute not just work, but responsibility. Possible roles:

• Proposer: presents the problem and helps clarify context.
• Community contributors: bring use cases, constraints, alternatives.
• AI facilitator: connects, synthesizes, maintains traceability, finds drift.
• Initiative steward: keeps the initiative moving and the context current.
• Decision owner: holds explicit authority to decide.
• Builder: implements a unit of work.
• Reviewer: evaluates architecture and quality.
• Validator: produces evidence and tries to invalidate the solution.
• Release owner: makes the final publication call.

The governance rule is:

Anyone can propose; many can deliberate; decision owners decide; all decisions are legible.

Today, the maintainers hold all of these roles. The point of naming them is to make delegation possible — one role at a time, to people who have earned context — without ambiguity about who decides what.

The fundamental property

The workflow must be progressively more demanding:

• suggesting is cheap;
• exploring requires a bit more involvement;
• deciding requires evidence and accountability;
• becoming an Issue requires clarity;
• becoming a PR requires implementation and proof;
• becoming product requires validation.

This allows radical openness at the idea stage without turning every suggestion into debt or obligation. When the project takes on a commitment, anyone can see where it came from, who decided, how to participate, and what "done" means.

Open questions

These are genuinely open — input welcome:

• Which Discussion categories do we want to keep?
• Which labels represent Discussion stages, and which belong only to Issues?
• How do we choose and make visible the decision owner?
• How often should syntheses be produced?
• Which decisions need a public comment window?
• What is the minimum graduation contract for a Discussion to become an Issue?
• How does a contributor volunteer as builder, reviewer, or validator?
• Where do Initiative Briefs, RFCs, and validation dossiers live in the repository?
• How do we measure the health of the system without optimizing only for PR volume?
• Which initiative should be the first full pilot of the workflow?

What happens next

This essay is direction, not decree. Concretely:

• Pieces of the system will go live as numbered, observable bets — like Bet #1 — each with explicit observation criteria and a decision date.
• As bets are kept, the corresponding parts of this essay harden into normative docs (contributing.md, decision records).
• Feedback in this Discussion shapes both the essay and the order of the bets.

If you maintain or contribute to other open-source projects: where have you seen community processes like this work — and where did they become bureaucracy, limbo, or lost signal? That experience is exactly what we want to hear before we harden any of this.

[lfnovo]

Bet #2 is live: every idea gets a qualified response — the first exercise of the facilitation stages (qualification, exploration, routing) described in this essay. Decision date: September 15, 2026.