Gemini 3 critiques Leo's Preface (and home page)
Edward K. Ream
Here is my prompt to gemini3:
> Please suggest improvements to Leo's "preface" at https://leo-editor.github.io/leo-editor/preface.html
Everything that follows is the response. Looks like I flunked marketing 101:
Based on an analysis of the text at the provided URL, the "preface" (titled "A Brief Summary of Leo") exhibits several rhetorical weaknesses that undermine its effectiveness for a technical audience.
The current text relies on subjective claims, dated comparisons, and insider jargon ("Leonine way"). A skeptical reader will likely view the broad listing of features (IDE, PIM, Outliner) as a sign of a tool lacking a defined scope, rather than a versatile one.
The following improvements address these issues, focusing on precision and verifiable value propositions.
1. Remove the Dated ComparisonCurrent: “Word outlines are very useful. But Leo makes Word look like a clunky toy.”—Joe Orr
Critique: Comparing a developer tool to Microsoft Word is a category error. It lowers the ceiling of expectations. Most developers do not use Word for code or serious data organization; they use VS Code, Vim, Emacs, or Obsidian. Acknowledging Word implies the tool is aimed at non-technical office users, which contradicts the later claim that it is a "fully-featured IDE."
Recommendation: Remove the quote entirely. Start with a direct definition of the tool's primary differentiator: the integration of outlining with codebase logic.
2. Clarify the "Directed Acyclic Graph" (DAG) ClaimCurrent: “Leo's underlying data is a Directed Acyclic Graphs. As a result, Leo organizes data in completely new ways.”
Critique: Stating the data structure is a DAG is a factual statement about implementation, not a benefit. The statement "organizes data in completely new ways" is vague marketing fluff. The user needs to know why a DAG matters (i.e., zero-cost aliasing/cloning of nodes).
Recommendation: Replace the implementation detail with the functional consequence.
Proposed Revision: "Unlike standard tree-based editors, Leo allows a single node to appear in multiple places simultaneously (clones). Editing a node in one location updates it everywhere, allowing for multidimensional organization of source code."
Current: “Leo's clone find commands enable the Leonine way to refactor programs.”
Critique: This is circular terminology. A new user does not know what "Leonine" means. Using proper nouns to describe a methodology often signals an insular community rather than a standard tool.
Recommendation: Describe the methodology strictly in operational terms.
Proposed Revision: "Leo enables refactoring by treating code structure as a manipulatable [sic] outline, allowing you to reorganize large codebases via drag-and-drop operations rather than text cutting and pasting."
Current: The list claims Leo is an IDE, an Outliner, a Data Manager, a Scripting Environment, and a study tool.
Critique: Tools that claim to do everything often trigger skepticism regarding their depth in any single area. A developer will question how a single tool can compete with IntelliJ (IDE) and Obsidian (PIM) simultaneously.
Recommendation: Hierarchy is needed. Define the tool primarily as one thing (likely a Literate Programming Editor or Scriptable Outliner) and list the others as secondary capabilities derived from that core.
5. Reframe the "Steep Learning Curve" WarningCurrent: “You won't learn all about Leo in a day or two... Please ask for help immediately if you get stuck.”
Critique: While honest, this frames the complexity as a liability rather than an investment. "Ask for help immediately" suggests the UI is non-intuitive.
Recommendation: Focus on progressive disclosure.
Proposed Revision: "While Leo's advanced scripting features offer depth that takes time to master, the basic outlining features provide immediate utility for navigating complex files."
Assumption: The claim "Written in 100% pure Python" assumes the user values interpretability over performance.
Critique: For a modern IDE, "100% Python" may raise concerns about latency and UI responsiveness compared to Rust or C++ based editors (like Zed or VS Code).
Recommendation: If performance is a concern, qualify this claim by explaining why it is Python (e.g., "ensuring the entire editor is hackable [sic] and scriptable by the user at runtime").
Summary of Proposed Structural ChangesHeadline: Change from "A Brief Summary" to "Technical Overview".
Lead: Delete the Word quote. State clearly that Leo is a scriptable outline editor for code and data.
Features: Group features by workflow (e.g., "For Coding," "For Scripting," "For Knowledge Management") rather than a flat list.
Technical differentiation: explicitly link "Clones" to the DAG structure to explain the mechanism of action.
Félix
I've often tried to define Leo in some other various ways when writing documentation... so I find this experiment very interesting!
... I think I'm going to try it out right this gemini3 thingy now for myself :)
Félix
Thomas Passin
Edward K. Ream
The hardest part is how to talk about all the non-programming things that Leo can do or be made to do. I agreed with most of what the chatbot had to say, including de-emphasizing clones. I'm also a little unhappy when Leo is called an IDE, because these days people expect much more from IDEs than Leo provides, especially for non-Python programming. Yet Leo makes managing long, complex code bases many many times more easy and feasible than anything else I've tried. Leo also makes trying experimental code way easier than anything else (e.g., running a script to test out some programming issue). So hard to capture the flavor of all that!I use Leo every day, all the time, for non-programming things. I don't see how I could replace it if it somehow vanished.
Edward K. Ream
The hardest part is how to talk about all the non-programming things that Leo can do or be made to do. I agreed with most of what the chatbot had to say, including de-emphasizing clones. I'm also a little unhappy when Leo is called an IDE, because these days people expect much more from IDEs than Leo provides, especially for non-Python programming. Yet Leo makes managing long, complex code bases many many times more easy and feasible than anything else I've tried. Leo also makes trying experimental code way easier than anything else (e.g., running a script to test out some programming issue). So hard to capture the flavor of all that!I use Leo every day, all the time, for non-programming things. I don't see how I could replace it if it somehow vanished.
Thomas Passin
rengel
Edward K. Ream
Thanks for sharing! Did you try to put the complete Leo codebase into an AI-based IDE like Windsurf or Google Antigravity? Then you can get a critique of the entire codebase or parts thereof or the complete documentation within the IDE and get automatic improvements (if you wish so) or suggestions for improvements.I know that this isn't the Leonine way of programming, but it might be worth a try.
rengel
Leo issue #4472 is a hobby project...This sentence [from gemini3] captures my initial vague idea exactly:
Your proposal essentially transforms Pylint from an Inference Engine (which is slow and guess-prone) into a Logic Validator (which is fast and deterministic).
==============================
Take the file D:\WORKSPACE\leo-editor-devel\leo\core\leoImport.py and adapt it so that it copies signatures for classes, methods and functions into a .pyi (stub) file. This will be a much easier project than my old make-stub-files script.
I’ll create a short TODO plan and read the file now.
Here’s a concrete plan and some design questions before I touch the code.
---
## High‑level idea
Add a **new command + helper(s)** in [leoImport.py](cci:7://file:///d:/WORKSPACE/leo-editor-devel/leo/core/leoImport.py:0:0-0:0) that:
1. Takes a Python module path (or uses the current `@file` node’s file).
2. Uses `ast` to parse it.
3. Walks classes, methods, and functions.
4. Writes a corresponding `.pyi` file (next to the `.py` or into a chosen directory) containing only **signatures** and minimal bodies (`...`).
This stays strictly simpler than a general “make-stub-files” script: no cross‑module analysis, no type inference; just copy what’s already in annotations/defaults.
---
## Design questions for you
To avoid guessing, I’d like your preferences on these:
1. **Source of file to stub**
- **Option A**: a command that uses the **current `@file` node**’s external file (`c.p`).
- **Option B**: a command that prompts for one or more `.py` files (similar to other `import*` commands).
- We can support both, but which should be the primary workflow?
2. **Where to write `.pyi`**
- Same directory as the `.py` (`foo.py` → `foo.pyi`)?
- Or some configurable “stubs directory” (setting) relative to the project?
3. **What to include**
- Only top‑level `def` and `class` definitions?
- For classes: include all methods, `@classmethod`, `@staticmethod`, properties?
- Skip private names starting with `_` or include everything?
4. **Handling existing `.pyi` files**
- Always **overwrite**?
- Or refuse if exists (unless a config/argument says “force”)?
If you answer these, I can implement something that matches your intended workflow.
---
## Proposed concrete changes in [leoImport.py](cci:7://file:///d:/WORKSPACE/leo-editor-devel/leo/core/leoImport.py:0:0-0:0)
### 1. Add a small AST-based stub generator
Implement a pure helper (no Leo dependency) near [LeoImportCommands](cci:2://file:///d:/WORKSPACE/leo-editor-devel/leo/core/leoImport.py:137:0-1339:13) or at the bottom:
- `generate_stub(source: str) -> str`
- Parse with `ast.parse`.
- Collect:
- `ast.FunctionDef` / `ast.AsyncFunctionDef` at module level.
- `ast.ClassDef` and their methods.
- Reconstruct signatures:
- Use `ast.get_source_segment` if feasible, or format `args`, `returns` yourself.
- Body is always `...` (ellipsis).
- `write_stub_for_file(path: str) -> str`
- Read file.
- Call `generate_stub`.
- Write to `path.replace('.py', '.pyi')` (or similar logic).
- Return path of written stub.
This part will be straightforward and fully testable without GUI.
### 2. Add Leo-facing helpers in [LeoImportCommands](cci:2://file:///d:/WORKSPACE/leo-editor-devel/leo/core/leoImport.py:137:0-1339:13)
For example:
- `def makeStubForCurrentFile(self) -> None:`
- Use `c.p` to find the underlying external `.py` (via `c.fullPath(p)` / `atFileCommands` if needed).
- Call `write_stub_for_file`.
- Report in the log (`g.es(f"created stub: {stub_path}")`).
- Optionally: `def makeStubsForFiles(self, paths: list[str]) -> None:`
- Loop over a list of `.py` files (if you want a “batch” mode with a dialog).
### 3. Add commands (decorated functions) near the other `@g.command` definitions
Following the style you showed:
```python
@g.command('make-stub-for-current-file')
def make_stub_for_current_file(event: LeoKeyEvent) -> None:
c = event.get('c')
if c:
c.importCommands.makeStubForCurrentFile()
```
Optionally another command taking multiple files via an open dialog, if you want parity with other import commands.
---
## Behavior details (default proposal)
Unless you say otherwise, I’d implement:
- **Source**:
- Primary: current `@file` node’s underlying `.py`.
- Fallback: if `c.p` is not an `@file` node with `.py`, show an error.
- **Destination**:
- Same directory, same basename, `.pyi` extension.
- **Included items**:
- All **top‑level** functions and classes.
- For classes:
- All methods (including async) and static/class methods.
- Properties exposed via `@property`.
- Don’t filter private names initially (keep it simple and predictable).
- **Docstrings**:
- Omitted in `.pyi` (just signatures + `...`).
- **Existing stubs**:
- **Overwrite** by default, with a log message.
We can add a config bool later, e.g. `@bool stub_generation_overwrite = True/False`.
---
## Next step
If you confirm your answers to the 4 design questions (or accept the defaults above), I’ll:
- Implement the stub generator helpers in [leoImport.py](cci:7://file:///d:/WORKSPACE/leo-editor-devel/leo/core/leoImport.py:0:0-0:0).
- Add a `LeoImportCommands.makeStubForCurrentFile` (and optional batch variant).
- Add a `@g.command` wrapper to invoke it from Leo.
- Keep comments/structure consistent with existing code and not touch unrelated parts.
Then I’ll summarize exactly what changed and how to use the new command.
Regards