docs: route feature ideas through Discussions (#1205)

* docs: route feature ideas through discussions * docs: normalize Issue terminology
2026-10-19 09:13:16 +00:00 · 2026-07-22 08:53:51 -03:00 · 2026-07-22 08:53:51 -03:00 · 206d77cab3
commit 206d77cab3
parent ee0ea5ebaa
13 changed files with 241 additions and 147 deletions
--- a/.github/DISCUSSION_TEMPLATE/ideas.yml
+++ b/.github/DISCUSSION_TEMPLATE/ideas.yml
@ -0,0 +1,73 @@
+title: "[Idea]: "
+labels: ["needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping shape Open Notebook.
+
+        Ideas, feature requests, behavior changes, product/design/architecture proposals, and contribution proposals start here so the community can explore the problem before it becomes an implementation commitment. Reproducible bugs belong in [Issues](https://github.com/lfnovo/open-notebook/issues/new/choose).
+
+        You do not need to know how to implement the idea. Start with the outcome you need and the context behind it.
+
+  - type: textarea
+    id: goal
+    attributes:
+      label: What are you trying to do?
+      description: Describe the goal or workflow in your own words.
+      placeholder: "I am trying to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What feels difficult or missing today?
+      description: Tell us what happens now and where the current experience falls short.
+      placeholder: "Today I have to... which makes it difficult to..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: outcome
+    attributes:
+      label: What outcome would help?
+      description: Describe what success would look like without needing to prescribe the implementation.
+      placeholder: "A good outcome would let me..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: How do you handle this today?
+      description: Share any workaround, alternative tool, or process you currently use.
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context, examples, or possible directions
+      description: Screenshots, references, constraints, and implementation ideas are welcome, but optional.
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: participation
+    attributes:
+      label: How would you like to participate?
+      description: This is not a commitment; it helps us know whom to involve if the idea moves forward.
+      options:
+        - label: I can add use cases or join the product/design discussion.
+        - label: I can help explore the technical approach.
+        - label: I can help implement an approved work item.
+        - label: I can test or validate a proposed solution.
+
+  - type: checkboxes
+    id: searched
+    attributes:
+      label: Before posting
+      options:
+        - label: I searched existing Discussions and Issues for related proposals.
+          required: true
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@ -8,7 +8,18 @@ body:
      value: |
        Thanks for reporting a bug! Please fill out the information below to help us understand and fix the issue.

-        **Note**: If you're having installation or setup issues, please use the "Installation Issue" template instead.
+        Issues are for **reproducible bugs** and maintainer-created work items. Feature requests, ideas, behavior changes, product/design/architecture proposals, and contribution proposals belong in [Discussions](https://github.com/lfnovo/open-notebook/discussions/new?category=ideas).
+
+        **Installation or setup problem?** Use the "Installation Issue" template instead.
+
+  - type: checkboxes
+    id: bug-confirmation
+    attributes:
+      label: Is this a reproducible bug?
+      description: Ideas and feature requests belong in Discussions and may be converted there if opened as Issues.
+      options:
+        - label: I confirm this is a reproducible bug, not a feature request, idea, question, or contribution proposal.
+          required: true

  - type: textarea
    id: what-happened
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@ -1,8 +1,14 @@
 blank_issues_enabled: false
 contact_links:
+  - name: 💡 Feature Requests and Ideas
+    url: https://github.com/lfnovo/open-notebook/discussions/new?category=ideas
+    about: Discuss features, product direction, design, architecture, and contribution proposals before they become work items
+  - name: ❓ Questions and Community Support
+    url: https://github.com/lfnovo/open-notebook/discussions/new?category=q-a
+    about: Ask questions and get help from maintainers and the community
  - name: 💬 Discord Community
    url: https://discord.gg/37XJPXfz2w
-    about: Get help from the community and share ideas
+    about: Get real-time help and talk with the community
  - name: 🤖 Installation Assistant (ChatGPT)
    url: https://chatgpt.com/g/g-68776e2765b48191bd1bae3f30212631-open-notebook-installation-assistant
    about: CustomGPT that knows all our docs. Really useful. Try it.
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@ -1,65 +0,0 @@
-name: ✨ Feature Suggestion
-description: Suggest a new feature or improvement for Open Notebook
-title: "[Feature]: "
-labels: ["enhancement", "needs-triage"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for taking the time to suggest a feature! Your ideas help make Open Notebook better for everyone.
-
-  - type: textarea
-    id: feature-description
-    attributes:
-      label: Feature Description
-      description: What feature would you like to see added or improved?
-      placeholder: "I would like to be able to..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: why-helpful
-    attributes:
-      label: Why would this be helpful?
-      description: Explain how this feature would benefit you and other users
-      placeholder: "This would help because..."
-    validations:
-      required: true
-
-  - type: textarea
-    id: proposed-solution
-    attributes:
-      label: Proposed Solution (Optional)
-      description: If you have ideas on how to implement this feature, please share them
-      placeholder: "This could be implemented by..."
-    validations:
-      required: false
-
-  - type: textarea
-    id: additional-context
-    attributes:
-      label: Additional Context
-      description: Any other context, screenshots, or examples that might be helpful
-      placeholder: "For example, other tools do this by..."
-    validations:
-      required: false
-
-  - type: checkboxes
-    id: willing-to-contribute
-    attributes:
-      label: Contribution
-      description: Would you like to work on implementing this feature?
-      options:
-        - label: I am a developer and would like to work on implementing this feature (pending maintainer approval)
-          required: false
-
-  - type: markdown
-    attributes:
-      value: |
-        ---
-        **Next Steps:**
-        1. A maintainer will review your feature request
-        2. If approved and you checked the box above, the issue will be assigned to you
-        3. Please wait for assignment before starting development
-        4. See our [Contributing Guide](https://github.com/lfnovo/open-notebook/blob/main/CONTRIBUTING.md) for more details
-
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@ -4,9 +4,10 @@

 ## Related Issue

-<!-- Non-trivial PRs (features, architecture changes) must link an approved issue.
+<!-- Non-trivial PRs (features, architecture changes) must link an approved Issue.
     Small obvious fixes (typo, docs, tiny bug) don't need one — write "N/A (small fix)" below.
-     Sizeable change without an issue? Mark this PR as draft and create the issue first. -->
+     Sizeable change without an approved Issue? Mark this PR as draft. Start a Discussion for an
+     idea/feature or open an Issue for a reproducible bug, then wait for the work to be approved. -->

 Fixes #<!-- issue number, or "N/A (small fix)" -->

@ -100,7 +101,7 @@ Before submitting, please verify:

 - [ ] I have read [CONTRIBUTING.md](https://github.com/lfnovo/open-notebook/blob/main/docs/7-DEVELOPMENT/contributing.md)
 - [ ] I have read [VISION.md](https://github.com/lfnovo/open-notebook/blob/main/VISION.md)
- [ ] This PR addresses an approved issue assigned to me, **or** it's a small obvious fix (typo, docs, tiny bug) that doesn't need one — for anything bigger without an issue, mark this PR as draft and open the issue (triage takes 1–2 days)
+- [ ] This PR addresses an approved Issue assigned to me, **or** it's a small obvious fix (typo, docs, tiny bug) that doesn't need one — ideas and features begin in Discussions; reproducible bugs begin in Issues
 - [ ] I have not included unrelated changes in this PR
 - [ ] My PR title follows conventional commits format (e.g., "feat: add user authentication")

--- a/AGENTS.md
+++ b/AGENTS.md
@ -41,5 +41,5 @@ Or all at once: `make start-all` (status: `make status`, stop: `make stop-all`).
 | Code standards & testing | [docs/7-DEVELOPMENT/code-standards.md](docs/7-DEVELOPMENT/code-standards.md) · [testing.md](docs/7-DEVELOPMENT/testing.md) |
 | Product identity & current posture | [VISION.md](VISION.md) |
 | Decision log (ADRs/PDRs) | [docs/7-DEVELOPMENT/decisions/](docs/7-DEVELOPMENT/decisions/) |
-| Contribution process (issue-first, PRs) | [docs/7-DEVELOPMENT/contributing.md](docs/7-DEVELOPMENT/contributing.md) |
+| Contribution process (Discussions → Issues → PRs) | [docs/7-DEVELOPMENT/contributing.md](docs/7-DEVELOPMENT/contributing.md) |
 | User/operator docs (install, configure, troubleshoot) | [docs/](docs/index.md) |
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]

 ### Changed
+- Community contribution intake now separates exploration from execution: feature requests, product/design/architecture ideas and contribution proposals start in GitHub Discussions, while Issues are reserved for reproducible bugs and maintainer-approved work items. The Issue chooser routes contributors accordingly, a structured Ideas Discussion form starts from user goals and outcomes, and the contributor/maintainer docs plus PR template now describe the Discussion → Issue → PR graduation path (#1204).
 - Release image gate gained a `probe` scenario (`make release-test` runs it as part of `all`): container-level checks that a Python test suite can't cover because they depend on the shipped image's process supervision — `OPEN_NOTEBOOK_WORKER_MAX_TASKS` reaching the in-image worker (the supervisord `sh -c` expansion), and the worker surviving startup with `HTTP_PROXY` set while a user's `NO_PROXY` value is preserved (the internal SurrealDB websocket not being tunneled). Both were manual probes during the v1.14.0 release; they now run automatically. Release-process docs gained the post-tag re-cut sequence and a note on never leaving the version bump uncommitted (v1.14.0 retro)

 ## [1.14.0] - 2026-07-20
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -19,11 +19,12 @@ All contribution guidelines have been consolidated into the new development docu

 ---

-## The Issue-First Workflow
+## The Contribution Workflow

-**TL;DR**: For anything non-trivial — features, architecture changes — create an issue first, get
-it assigned, THEN code. Small obvious fixes (typos, docs, tiny bugs) can go straight to a PR.
-Already coded something bigger? Mark the PR as draft and open the issue — triage takes 1–2 days.
+**TL;DR**: Feature requests, product/design/architecture proposals, and other non-trivial ideas
+start in [GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions/new?category=ideas).
+Reproducible bugs start in Issues. Coding starts from an approved and assigned Issue. Small obvious
+fixes (typos, docs, tiny bugs) can still go straight to a PR.

 This prevents wasted effort and ensures your work aligns with the project. [See details →](docs/7-DEVELOPMENT/contributing.md)

--- a/README.md
+++ b/README.md
@ -319,7 +319,7 @@ Thanks to the [Esperanto](https://github.com/lfnovo/esperanto) library, we suppo
 - **Enhanced Citations**: Improved layout and finer control for source citations
 - **Multiple Chat Sessions**: Manage different conversations within notebooks

-See the [open issues](https://github.com/lfnovo/open-notebook/issues) for a full list of proposed features and known issues.
+Explore [GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions/categories/ideas) for proposed features and product ideas, and [open Issues](https://github.com/lfnovo/open-notebook/issues) for known bugs and approved work.

 <p align="right">(<a href="#readme-top">back to top</a>)</p>

@ -335,7 +335,8 @@ See the [open issues](https://github.com/lfnovo/open-notebook/issues) for a full
 ### Join the Community
 - 💬 **[Discord Server](https://discord.gg/37XJPXfz2w)** - Get help, share ideas, and connect with other users
 - 𝕏 **[Follow @lfnovo on X](https://x.com/lfnovo)** - Project updates and news from the maintainer
- 🐛 **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Report bugs and request features
+- 💡 **[GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions)** - Ask questions and shape features, product direction, design, and architecture
+- 🐛 **[GitHub Issues](https://github.com/lfnovo/open-notebook/issues)** - Report reproducible bugs and find approved work
 - ⭐ **Star this repo** - Show your support and help others discover Open Notebook

 ### Contributing
@ -361,7 +362,8 @@ Open Notebook is MIT licensed. See the [LICENSE](LICENSE) file for details.
 **Community Support**:
 - 💬 [Discord Server](https://discord.gg/37XJPXfz2w) - Get help, share ideas, and connect with users
 - 𝕏 [Follow @lfnovo on X](https://x.com/lfnovo) - Project updates and news from the maintainer
- 🐛 [GitHub Issues](https://github.com/lfnovo/open-notebook/issues) - Report bugs and request features
+- 💡 [GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions) - Ask questions and shape ideas
+- 🐛 [GitHub Issues](https://github.com/lfnovo/open-notebook/issues) - Report reproducible bugs and find approved work
 - 🌐 [Website](https://www.open-notebook.ai) - Learn more about the project

 <p align="right">(<a href="#readme-top">back to top</a>)</p>
--- a/docs/6-TROUBLESHOOTING/faq.md
+++ b/docs/6-TROUBLESHOOTING/faq.md
@ -229,8 +229,8 @@ ESPERANTO_LLM_TIMEOUT=180  # 3 minutes for model inference

 1. Check the troubleshooting guides in this section
 2. Search existing GitHub issues
-3. Ask in the Discord community
-4. Create a GitHub issue with detailed information
+3. Ask in [GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions/categories/q-a) or the Discord community
+4. If you found a reproducible bug, create a GitHub Issue with detailed information

 ### How do I report a bug?

@ -246,7 +246,8 @@ Submit to: [GitHub Issues](https://github.com/lfnovo/open-notebook/issues)
 ### Where can I get help?

 - **Discord**: https://discord.gg/37XJPXfz2w (fastest)
- **GitHub Issues**: Bug reports and feature requests
+- **GitHub Discussions**: Questions, ideas, and feature requests
+- **GitHub Issues**: Reproducible bug reports
 - **Documentation**: This docs site

 ---
--- a/docs/7-DEVELOPMENT/contributing.md
+++ b/docs/7-DEVELOPMENT/contributing.md
@ -2,27 +2,34 @@

 Thank you for your interest in contributing to Open Notebook! We welcome contributions from developers of all skill levels. This guide will help you understand our contribution workflow and what makes a good contribution.

-## 🚦 Issue-First Workflow (for anything non-trivial)
+## 🚦 Discussions for Ideas, Issues for Work

-**To maintain project coherence and avoid wasted effort, non-trivial work starts with an issue:**
+Open Notebook separates **exploration** from **execution**:

-1. **Create an issue first** - Before writing any code, create an issue describing the bug or feature
-2. **Propose your solution** - Explain how you plan to implement the fix or feature
-3. **Wait for assignment** - A maintainer will review and assign the issue to you if approved
-4. **Only then start coding** - This ensures your work aligns with the project's vision and architecture
+- **Feature requests, ideas, behavior changes, product/design/architecture proposals, and contribution proposals start in [GitHub Discussions](https://github.com/lfnovo/open-notebook/discussions/new?category=ideas).** This is where the community explores the problem and maintainers make the product or design decision.
+- **Reproducible bugs start in [GitHub Issues](https://github.com/lfnovo/open-notebook/issues/new/choose).**
+- **Implementation starts from an approved Issue.** Once an idea is sufficiently clear and accepted, a maintainer creates an Issue from the Discussion, scopes it, and assigns it before coding begins.

-**When you can skip the issue and just open a PR:**
+This means non-trivial contributions follow one of two paths:
+
+```text
+Idea or feature → Discussion → decision → approved Issue → code → PR
+Reproducible bug               → triaged Issue  → code → PR
+```
+
+**When you can skip both and just open a PR:**
 - Typos, broken links, and small documentation clarifications
 - Small, obvious bug fixes — a few lines, one clear right answer, no design decisions
 - Translation fixes or completing missing i18n keys

-**When an issue is definitely required first:**
+**When a Discussion is definitely required first:**
 - New features, of any size
 - Architecture or structural changes
 - Breaking changes
+- Product, UX, or behavior changes
 - Anything where the *how* has more than one reasonable answer

-**Already coded something sizeable without an issue?** Don't throw it away: mark the PR as **draft**, open an issue describing the problem and your approach, and link it from the PR. Our triage is fast — expect a call within 1–2 days.
+**Already coded something sizeable without prior discussion or an approved Issue?** Don't throw it away: mark the PR as **draft**. Open a Discussion for a feature or design proposal, or an Issue for a reproducible bug, and link it from the PR. A maintainer will help route the work.

 **Why this process?**
 - Prevents duplicate work
@ -30,7 +37,7 @@ Thank you for your interest in contributing to Open Notebook! We welcome contrib
 - Saves your time by getting feedback before coding
 - Helps maintainers manage the project direction

-> ⚠️ **Non-trivial pull requests without an issue may be closed**, even if the code is good. We want to respect your time by making sure work is aligned before it starts.
+> ⚠️ **Non-trivial pull requests without an approved Issue may be closed**, even if the code is good. A Discussion is where an idea is explored; an Issue is the project's commitment to execute it.

 ## Code of Conduct

@ -51,15 +58,16 @@ By participating in this project, you are expected to uphold our [Code of Conduc

 ### Suggesting Features

-1. **Search existing issues** - Check if the feature was already suggested
-2. **Create a feature request** - Use the [Feature Request template](https://github.com/lfnovo/open-notebook/issues/new?template=feature_request.yml)
-3. **Explain the value** - Describe why this feature would be helpful
-4. **Propose implementation** - If you have ideas on how to implement it, share them
-5. **Indicate if you want to build it** - Check the "I would like to work on this" box if you're interested
+1. **Search existing Discussions and Issues** - Check whether the problem is already being explored or worked on
+2. **Start an Idea Discussion** - Use the [Ideas form](https://github.com/lfnovo/open-notebook/discussions/new?category=ideas)
+3. **Start with the problem and outcome** - Explain what you are trying to do, what is difficult today, and what success would look like
+4. **Add possible directions if useful** - Implementation ideas and references are welcome, but not required
+5. **Join the exploration** - Help answer questions, evaluate trade-offs, or test prototypes
+6. **Wait for graduation before coding** - If accepted, the proposal becomes one or more approved Issues that can be assigned

 ### Contributing Code (Pull Requests)

-**IMPORTANT: Follow the issue-first workflow above before starting any PR**
+**IMPORTANT: For non-trivial work, start from an approved and assigned Issue before coding. Ideas reach that point through Discussions; reproducible bugs reach it through Issue triage.**

 Once your issue is assigned:

@ -85,7 +93,7 @@ Once your issue is assigned:
 - Have clear commit messages

 ❌ **We may close PRs that:**
- Are non-trivial and don't have an associated approved issue (small obvious fixes are exempt — see the issue-first workflow above)
+- Are non-trivial and don't have an associated approved Issue (small obvious fixes are exempt — see the workflow above)
 - Introduce breaking changes without discussion
 - Conflict with our architectural vision
 - Lack tests or documentation
@ -96,7 +104,7 @@ Once your issue is assigned:
 A large share of contributions — including our own — are written with coding agents (Claude Code, Cursor, Copilot, etc.). That's welcome. The tool doesn't change the contract; **the operator does not stop being the author**:

 1. **You own the PR.** You must have read, understood, and be able to explain every line of the diff. "The agent wrote it" is never an answer in review.
-2. **Issue-first still applies to anything non-trivial.** Agents make it cheap to produce large unsolicited PRs — those get closed like any other unassigned PR, regardless of code quality. (Small obvious fixes are exempt, same as for humans; a sizeable PR without an issue can be converted to draft while its issue goes through triage.)
+2. **Discussion before commitment; approved Issue before implementation.** Agents make it cheap to produce large unsolicited PRs — those get closed like any other unassigned PR, regardless of code quality. Small obvious fixes are exempt. For larger work, use a Discussion to shape an idea or an Issue to report a reproducible bug, then wait for an approved work item.
 3. **Tests must have actually run.** Paste real output. An agent *claiming* tests pass is not test evidence.
 4. **Point your agent at the right context.** The repo ships `AGENTS.md` files (root, `open_notebook/`, `frontend/`) with the normative rules, and [change-playbooks.md](change-playbooks.md) with step-by-step recipes — agents that read them produce PRs that pass review faster.
 5. **Keep it scoped.** Agents tend to "improve" surrounding code along the way. Unrelated refactors belong in separate issues/PRs.
@ -200,8 +208,8 @@ We're actively looking for contributions in these areas:
 ### Community Support

 - **Discord**: [Join our Discord server](https://discord.gg/37XJPXfz2w) for real-time help
- **GitHub Discussions**: For longer-form questions and ideas
- **GitHub Issues**: For bug reports and feature requests
+- **GitHub Discussions**: For questions, ideas, features, product direction, design, and architecture
+- **GitHub Issues**: For reproducible bugs and approved work items

 ### Documentation References

--- a/docs/7-DEVELOPMENT/index.md
+++ b/docs/7-DEVELOPMENT/index.md
@ -12,7 +12,7 @@ Start with **[Contributing Guide](contributing.md)** for the workflow, then chec
 - **[Code Standards](code-standards.md)** - How to write code that fits our style
 - **[Testing](testing.md)** - How to write and run tests

-**First time?** Check out our [Contributing Guide](contributing.md) for the issue-first workflow.
+**First time?** Check out our [Contributing Guide](contributing.md) for the Discussions → Issues → PRs workflow.

 ### 🔒 I Want to Understand Security Practices

@ -66,7 +66,7 @@ repo root, `open_notebook/`, and `frontend/`.
 |---|---|---|
 | [Quick Start](quick-start.md) | New developers | Clone, install, and verify setup (5 min) |
 | [Development Setup](development-setup.md) | Local development | Complete environment setup guide |
-| [Contributing](contributing.md) | Code contributors | Workflow: issue → code → PR |
+| [Contributing](contributing.md) | Community & code contributors | Workflow: Discussion → Issue → PR |
 | [Code Standards](code-standards.md) | Writing code | Style guides for Python, FastAPI, DB |
 | [Testing](testing.md) | Testing code | How to write and run tests |
 | [Architecture](architecture.md) | Understanding system | System design, tech stack, workflows |
@ -102,8 +102,8 @@ See GitHub Issues labeled `good first issue` or `help wanted`.
 ## 💬 Getting Help

 - **Discord**: [Join our server](https://discord.gg/37XJPXfz2w) for real-time discussions
- **GitHub Discussions**: For architecture questions
- **GitHub Issues**: For bugs and features
+- **GitHub Discussions**: For questions, ideas, features, product direction, design, and architecture
+- **GitHub Issues**: For reproducible bugs and approved work items

 Don't be shy! We're here to help new contributors succeed.

--- a/docs/7-DEVELOPMENT/maintainer-guide.md
+++ b/docs/7-DEVELOPMENT/maintainer-guide.md
@ -4,51 +4,97 @@ This guide is for project maintainers to help manage contributions effectively w

 ## Table of Contents

+- [Discussion Management](#discussion-management)
 - [Issue Management](#issue-management)
 - [Pull Request Review](#pull-request-review)
 - [Merging PR Batches](#merging-pr-batches)
 - [Common Scenarios](#common-scenarios)
 - [Communication Templates](#communication-templates)

+## Discussion Management
+
+Discussions are the intake and deliberation space for feature requests, ideas,
+behavior changes, product direction, design, architecture, and contribution
+proposals. An accepted idea becomes an Issue only when it is sufficiently clear
+to track and execute.
+
+### When a New Idea Discussion Is Created
+
+**1. Initial triage** (within 24-48 hours when possible)
+
+- Confirm that it is an idea or open-ended proposal rather than a reproducible bug.
+- Search Discussions, Issues, PRs, `VISION.md`, and decision records for related context.
+- Merge the signal into a canonical Discussion when the topic already exists; preserve links to the original author and contribution.
+- Replace `needs-triage` with `needs-vision` when the question is *whether/why* the project should pursue it, or `needs-design` when the problem is wanted but the *how* remains open.
+
+**2. Shape the conversation**
+
+Ask for missing evidence rather than an implementation plan by default:
+
+- What is the user trying to accomplish?
+- What is difficult today, and how do they work around it?
+- Who else has the same use case?
+- Which constraints, alternatives, or failure modes matter?
+- How would we validate that the outcome is better?
+
+For larger proposals, keep a synthesis in the Discussion body or a maintainer
+comment: what is known, what remains open, alternatives, and the decision owner.
+
+**3. Close the loop**
+
+Every mature Discussion ends with an explicit outcome:
+
+- **Accepted:** create one or more scoped Issues from the Discussion, replace inherited discovery labels with `ready`, link them in both directions, and close the Discussion as resolved.
+- **Experiment:** describe the bounded experiment and the evidence needed before a commitment.
+- **Parked:** state why it is not timely and what condition would reopen it.
+- **Declined:** explain the conflict with vision, scope, or maintenance cost.
+- **Superseded/duplicate:** link the canonical Discussion or initiative.
+
+Creating an Issue is the graduation event: it means the project has committed to
+track executable work, not merely that the idea received positive reactions.
+
 ## Issue Management

-### When a New Issue is Created
+### When a New Issue Is Created

-**1. Initial Triage** (within 24-48 hours)
+**1. Initial triage** (within 24-48 hours when possible)

- Issues arrive with the intake label `needs-triage` (applied by the issue templates). Triage replaces it with exactly **one state label** from the funnel below (or closes the issue).
+- Public Issues arrive through the bug or installation forms with `needs-triage`.
+- Maintainers also create Issues when accepted Discussions graduate into executable work.
 - Add one **type** and one **area** label where they apply (see [Labels](#labels)).

- Quick assessment:
-  - Is it clear and well-described?
-  - Is it aligned with the product vision? (See [VISION.md](../../VISION.md))
-  - Does it duplicate an existing issue?
+Quick assessment:

-**2. Initial Response**
+- Is it a reproducible bug or an already approved work item?
+- Does it duplicate an existing Issue?
+- Does it need more reproduction details or environment information?
+- If it is an idea, feature request, or open-ended proposal, convert it to a Discussion and explain the workflow.
+
+**2. Initial response**

 ```markdown
 Thanks for opening this issue! We'll review it and get back to you soon.

 [If it's a bug] In the meantime, have you checked our troubleshooting guide?
-
-[If it's a feature] You might find our [vision](https://github.com/lfnovo/open-notebook/blob/main/VISION.md) helpful for understanding what we're building toward.
 ```

-**3. Decision Making**
+**3. Bug triage**

 Ask yourself:
- Does this align with our [vision and principles](../../VISION.md)?
- Is this something we want in the core project, or better as a plugin/extension?
- Do we have the capacity to support this feature long-term?
- Will this benefit most users, or just a specific use case?

-**4. Issue Assignment**
+- Can it be reproduced from the supplied steps and environment?
+- Is more information required from the reporter?
+- Is it already fixed, a duplicate, or rooted in an upstream dependency?
+- Is the expected behavior actually a product/design decision? If so, open or link a Discussion before defining the fix.
+
+**4. Issue assignment**

 If the contributor checked "I am a developer and would like to work on this":

-**For Accepted Issues:**
+**For triaged Issues:**
+
 ```markdown
-Great idea! This aligns well with our goals, particularly [specific design principle].
+Thanks for the clear report. We've confirmed this as work the project should track.

 I see you'd like to work on this. Before you start:

@ -59,7 +105,8 @@ I see you'd like to work on this. Before you start:
 Looking forward to your thoughts!
 ```

-**For Issues Needing Clarification:**
+**For Issues needing clarification:**
+
 ```markdown
 Thanks for offering to work on this! Before we proceed, we need to clarify a few things:

@ -69,30 +116,37 @@ Thanks for offering to work on this! Before we proceed, we need to clarify a few
 Once we have these details, we can discuss the best approach.
 ```

-**For Issues Not Aligned with Vision:**
+**For an idea opened as an Issue:**
+
 ```markdown
-Thank you for the suggestion and for offering to work on this!
+Thank you for the proposal! We use GitHub Discussions for feature requests,
+product/design/architecture ideas, and contribution proposals so the community
+can explore them before they become implementation commitments.

-After reviewing against our [vision and principles](https://github.com/lfnovo/open-notebook/blob/main/VISION.md), we've decided not to pursue this in the core project because [specific reason].
-
-However, you might be able to achieve this through [alternative approach, if applicable].
-
-We appreciate your interest in contributing! Feel free to check out our [open issues](https://github.com/lfnovo/open-notebook/issues) for other ways to contribute.
+I'm converting this Issue to a Discussion. If the direction is accepted and
+sufficiently scoped, we'll create an approved Issue from it before implementation.
 ```

 ### Labels

 The label set is curated — **don't invent labels**. If something doesn't fit, raise it instead of adding one. Assign **one state**, **one type**, and **one area** where each applies; multiple bundling/ecosystem labels are fine.

-**State funnel** — every open issue lands in exactly one state:
+**Discovery states** — primarily used on Discussions. Historical Issues may retain
+these while the backlog is migrated; do not newly route feature proposals into Issues:

 | Label | Meaning |
 |---|---|
-| `needs-triage` | Intake — applied by the issue templates, means "not triaged yet" |
+| `needs-triage` | New signal not yet classified |
 | `needs-vision` | Unsure if/how this fits — strategic call for the maintainers (against [VISION.md](../../VISION.md)) |
 | `needs-design` | Wanted, but the *how* isn't resolved — needs design/spec before it's ready |
+
+**Issue delivery states:**
+
+| Label | Meaning |
+|---|---|
+| `needs-triage` | New bug or installation report not yet triaged |
 | `needs-info` | Waiting on the reporter to confirm or provide more information |
-| `ready` | Fully specified — the dev loop can pick it up |
+| `ready` | Approved and sufficiently specified — the dev loop can pick it up |
 | **Close** | Use GitHub's native close reasons (duplicate / not planned); link the canonical issue when duplicate/superseded |

 **Type** — what kind of work it is (apply one when clear):
@ -129,14 +183,14 @@ The label set is curated — **don't invent labels**. If something doesn't fit,
 - `good first issue` — small, well-scoped, newcomer-friendly
 - `help wanted` — we'd welcome a contributor to take this

-### Consolidation: one issue vs. umbrella
+### Consolidation: Discussion vs. umbrella

 When several open issues circle the same topic, pick the model by **how decided the work is** — not just by shared theme:

- **Pre-vision / pre-design topic** → collapse into **one** issue (`needs-vision` or `needs-design`), capture each request's signal (👍 counts, interested contributors) in its body, and close the rest as duplicates pointing to it. A topic isn't N issues — it's one thinking space.
+- **Pre-vision / pre-design topic** → create or select **one canonical Discussion**, capture each request's signal (👍 counts, interested contributors) in its synthesis, and convert/link the related Issues or Discussions to it. A topic isn't N work items — it's one thinking space.
 - **Already decomposed into real parallel tasks** → use `umbrella` + `tracked-in-umbrella`. Children stay open because each is independently pickable (e.g. the multi-user umbrella #712).

-Rule of thumb: if the issues can't be worked until *we* make a call, they're one issue. If the call is made and the work splits into things a contributor could pick up today, they're an umbrella with children. **Never close an issue that has an active assignee/contributor or open PR** — link it as a phase instead.
+Rule of thumb: if work cannot start until *we* make a call, it belongs in a Discussion. If the call is made and the work splits into things a contributor could pick up today, it belongs in an umbrella with child Issues. **Never convert or close an Issue that has an active assignee/contributor or open PR without coordinating with them** — link it as a phase instead.

 ## Pull Request Review

@ -144,14 +198,14 @@ Rule of thumb: if the issues can't be worked until *we* make a call, they're one

 **Before diving into code:**

- [ ] Is there an associated approved issue?
+- [ ] Is there an associated approved Issue?
 - [ ] Does the PR reference the issue number?
 - [ ] Is the PR description clear about what changed and why?
 - [ ] Did the contributor check the relevant boxes in the PR template?
 - [ ] Are there tests? Screenshots (for UI changes)?

 **Red Flags** (may require closing PR):
- No associated issue on a non-trivial change (small obvious fixes are exempt; sizeable PRs can be converted to draft while their issue goes through triage)
+- No associated approved Issue on a non-trivial change (small obvious fixes are exempt; sizeable PRs should become drafts while an idea goes through Discussion or a bug goes through Issue triage)
 - Issue was not assigned to contributor
 - PR tries to solve multiple unrelated problems
 - Breaking changes without discussion
@ -256,13 +310,13 @@ Let me know what you prefer!

 ### Scenario 2: PR Without Assigned Issue

-**Situation**: Contributor submitted PR without going through issue approval process.
+**Situation**: Contributor submitted a non-trivial PR without an approved and assigned Issue.

 **Response:**
 ```markdown
 Thanks for the PR! I appreciate you taking the time to contribute.

-However, to maintain project coherence, we require all PRs to be linked to an approved issue that was assigned to the contributor. This is explained in our [Contributing Guide](contributing.md).
+However, to maintain project coherence, we require non-trivial PRs to be linked to an approved Issue that was assigned to the contributor. Small obvious fixes remain exempt. This is explained in our [Contributing Guide](contributing.md).

 This helps us:
 - Ensure work aligns with project vision
@ -270,14 +324,15 @@ This helps us:
 - Discuss approach before implementation

 Could you please:
-1. Create an issue describing this change
-2. Wait for it to be reviewed and assigned to you
-3. We can then reopen this PR or you can create a new one
+1. Mark this PR as draft
+2. Start a Discussion if this is a feature/design proposal, or an Issue if it fixes a reproducible bug
+3. Wait for an approved Issue to be scoped and assigned
+4. We can then continue with this PR

 Sorry for the inconvenience - this process helps us manage the project effectively.
 ```

-### Scenario 3: Feature Request Not Aligned with Vision
+### Scenario 3: Idea Discussion Not Aligned with Vision

 **Situation**: Well-intentioned feature that doesn't fit project goals.

@ -422,7 +477,7 @@ This will be included in the next release.

 ### Be Responsive

- Respond to issues within 48 hours (even just to acknowledge)
+- Respond to new Discussions and Issues within 48 hours when possible (even just to acknowledge)
 - Review PRs within a week when possible
 - Keep contributors updated on status
 - Close stale issues/PRs to keep things tidy
@ -438,7 +493,7 @@ Ask yourself:

 If you're unsure, it's perfectly fine to:
 - Ask for input from other maintainers
- Start a discussion issue
+- Start or link a GitHub Discussion
 - Sleep on it before making a decision

 ---