docs: add comprehensive lesson system documentation#771
Merged
Conversation
- Created docs/lessons.rst with complete documentation - Added lessons to docs index - Enhanced docs/lessons/README.md with: - Autonomous mode configuration - CLI commands reference - Best practices for writing lessons - Migration guide for existing lessons - Added lessons feature to main README Post-merge documentation for PRs #687 and #722. Co-authored-by: Bob <bob@superuserlabs.org>
Contributor
There was a problem hiding this comment.
Greptile Overview
Greptile Summary
This PR adds comprehensive documentation for the lesson system, a feature that provides contextual guidance and best practices automatically included in conversations based on keyword/tool matching. The documentation covers lesson creation, configuration (including interactive vs autonomous mode settings), CLI commands, and YAML frontmatter format. The lesson system, implemented in merged PRs #687 and #722, auto-includes relevant lessons based on conversation context and adapts behavior based on whether the conversation is user-driven (≥30% user messages) or agent-driven (<30%), with separate configuration limits for each mode. This PR integrates the documentation into the existing Sphinx-based docs structure by adding docs/lessons.rst, updating the index, enhancing the lessons directory README, and surfacing the feature in the main README.
Important Files Changed
Changed Files
| Filename | Score | Overview |
|---|---|---|
| docs/lessons.rst | 4/5 | Adds comprehensive RST documentation covering lesson format, YAML frontmatter, configuration variables, CLI commands, and autonomous vs interactive mode behavior |
| docs/index.rst | 5/5 | Adds single line to include lessons documentation in the User Guide table of contents |
| docs/lessons/README.md | 4/5 | Enhances existing README with usage instructions, configuration examples, autonomous mode explanation, and migration guide for lessons without frontmatter |
| README.md | 5/5 | Adds lessons system to main features list with four bullet points and corresponding documentation link |
Confidence score: 4/5
- This PR is safe to merge with low risk; it only adds documentation for already-merged features and does not modify any production code.
- Score reflects potential inconsistencies in documented default configuration values that should be verified against the actual implementation in PRs #687 and #722—specifically the
GPTME_LESSONS_AUTO_INCLUDE_AUTONOMOUSdefault (documented as false in lessons/README.md but true in lessons.rst) and autonomous mode thresholds. - Pay close attention to docs/lessons.rst (lines 169-172, 198-202) and docs/lessons/README.md (lines 72-74) to ensure documented defaults match the implementation; also verify that referenced lesson examples (lines 92-96 in lessons.rst) exist in the repository.
Sequence Diagram
sequenceDiagram
participant User
participant CLI
participant LessonSystem
participant LessonIndex
participant FileSystem
participant Conversation
participant Assistant
User->>CLI: Start gptme conversation
CLI->>LessonSystem: Initialize lesson system
LessonSystem->>FileSystem: Scan lesson directories
Note over FileSystem: ~/.config/gptme/lessons/<br/>./lessons/<br/>package lessons
FileSystem-->>LessonSystem: Return lesson files
LessonSystem->>LessonIndex: Index lessons with metadata
Note over LessonIndex: Parse YAML frontmatter<br/>Extract keywords & tools
LessonIndex-->>LessonSystem: Return indexed lessons
LessonSystem-->>CLI: Lessons indexed
User->>Conversation: Send message with keywords
Conversation->>LessonSystem: Check for matching lessons
LessonSystem->>LessonIndex: Query by keywords/tools
LessonIndex-->>LessonSystem: Return matching lessons
alt Interactive Mode (>= 30% user messages)
LessonSystem->>LessonSystem: Match against user keywords
LessonSystem->>LessonSystem: Apply MAX_INCLUDED limit
else Autonomous Mode (< 30% user messages)
LessonSystem->>LessonSystem: Match against assistant keywords
LessonSystem->>LessonSystem: Apply MAX_INCLUDED_AUTONOMOUS limit
end
LessonSystem->>Conversation: Include relevant lessons
Note over Conversation: Lessons added as hidden context
Conversation->>Assistant: Send prompt with lessons
Assistant-->>Conversation: Generate response with guidance
Conversation-->>User: Display response
opt User checks lessons
User->>CLI: /lesson list
CLI->>LessonIndex: Get all lessons
LessonIndex-->>CLI: Return lesson list
CLI-->>User: Show available lessons
end
opt User searches lessons
User->>CLI: /lesson search <query>
CLI->>LessonIndex: Search by query
LessonIndex-->>CLI: Return matching lessons
CLI-->>User: Show search results
end
opt User views specific lesson
User->>CLI: /lesson show <id>
CLI->>LessonIndex: Get lesson by id
LessonIndex->>FileSystem: Read lesson file
FileSystem-->>LessonIndex: Return lesson content
LessonIndex-->>CLI: Return lesson
CLI-->>User: Display lesson content
end
opt User refreshes lessons
User->>CLI: /lesson refresh
CLI->>LessonSystem: Reload lessons
LessonSystem->>FileSystem: Re-scan directories
FileSystem-->>LessonSystem: Return updated files
LessonSystem->>LessonIndex: Re-index lessons
LessonIndex-->>LessonSystem: Updated index
LessonSystem-->>CLI: Refresh complete
CLI-->>User: Confirm refresh
end
4 files reviewed, no comments
Contributor
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed everything up to 830e7a9 in 59 seconds. Click for details.
- Reviewed
500lines of code in4files - Skipped
0files when reviewing. - Skipped posting
5draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. README.md:203
- Draft comment:
New bullet for the Lessons system in the features list is clear and concise. It nicely summarizes the benefits, and the link to [docs-lessons] is correctly set up. - Reason this comment was not posted:
Confidence changes required:0%<= threshold50%None
2. docs/index.rst:32
- Draft comment:
Adding 'lessons' to the table of contents improves navigation and discoverability of the new lesson documentation. Looks well-integrated. - Reason this comment was not posted:
Confidence changes required:0%<= threshold50%None
3. docs/lessons.rst:34
- Draft comment:
Comprehensive documentation overall. Consider verifying that the nested markdown code fences (triple backticks within the markdown code block) render correctly in Sphinx to avoid potential formatting issues for users. - Reason this comment was not posted:
Confidence changes required:33%<= threshold50%None
4. docs/lessons.rst:177
- Draft comment:
The 'Autonomous Mode' section clearly distinguishes between interactive and autonomous behaviors. Adding a brief example (or reference) could further help users understand the mode differences, but the current explanation is strong. - Reason this comment was not posted:
Confidence changes required:33%<= threshold50%None
5. docs/lessons/README.md:40
- Draft comment:
The enhanced README for example lessons is very thorough. The inclusion of CLI commands, best practices, and a migration guide makes it a valuable resource for users. Great job on structuring and clarifying these steps. - Reason this comment was not posted:
Confidence changes required:0%<= threshold50%None
Workflow ID: wflow_MV35BsrjAQp00lIQ
You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Remove references to non-existent autonomous mode configuration variables (GPTME_LESSONS_AUTO_INCLUDE_AUTONOMOUS, GPTME_LESSONS_MAX_INCLUDED_AUTONOMOUS) that were removed during refactoring. The system now uses unified configuration for all modes: - GPTME_LESSONS_AUTO_INCLUDE (default: true) - GPTME_LESSONS_MAX_INCLUDED (default: 5) Keywords are extracted from both user and assistant messages in all contexts, with no mode detection. Fixes inconsistencies identified in Greptile review (PR #771). Co-authored-by: Bob <bob@superuserlabs.org>
Member
Author
Documentation Fixes AppliedAddressed configuration inconsistencies identified in Greptile review: Issue: Documentation referenced non-existent autonomous mode configuration variables that were removed during refactoring. Changes:
Verified Implementation:
Verification:
Ready for re-review! |
Contributor
There was a problem hiding this comment.
Important
Looks good to me! 👍
Reviewed 29c8584 in 53 seconds. Click for details.
- Reviewed
61lines of code in2files - Skipped
0files when reviewing. - Skipped posting
2draft comments. View those below. - Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.
1. docs/lessons.rst:174
- Draft comment:
Removed the detailed Autonomous Mode section and replaced it with a unified keyword extraction explanation. Confirm that deprecated autonomous env variables (e.g. GPTME_LESSONS_AUTO_INCLUDE_AUTONOMOUS) are noted in the migration guide. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to confirm that deprecated environment variables are noted in the migration guide. This is a request for confirmation, which violates the rule against asking the author to confirm their intention or ensure something is done.
2. docs/lessons/README.md:69
- Draft comment:
Autonomous mode settings were removed here. Ensure the migration guide covers the removal of GPTME_LESSONS_AUTO_INCLUDE_AUTONOMOUS and related variables to help users update their configurations. - Reason this comment was not posted:
Comment did not seem useful. Confidence is useful =0%<= threshold50%The comment is asking the PR author to ensure that the migration guide covers the removal of certain settings. This falls under the category of asking the author to ensure something is done, which is against the rules.
Workflow ID: wflow_JZAWDw8BmsGdPiRo
You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.
Skogix
pushed a commit
to SkogAI/gptme
that referenced
this pull request
Dec 12, 2025
* docs: add comprehensive lesson system documentation - Created docs/lessons.rst with complete documentation - Added lessons to docs index - Enhanced docs/lessons/README.md with: - Autonomous mode configuration - CLI commands reference - Best practices for writing lessons - Migration guide for existing lessons - Added lessons feature to main README Post-merge documentation for PRs gptme#687 and gptme#722. Co-authored-by: Bob <bob@superuserlabs.org> * docs: fix lesson system documentation to match implementation Remove references to non-existent autonomous mode configuration variables (GPTME_LESSONS_AUTO_INCLUDE_AUTONOMOUS, GPTME_LESSONS_MAX_INCLUDED_AUTONOMOUS) that were removed during refactoring. The system now uses unified configuration for all modes: - GPTME_LESSONS_AUTO_INCLUDE (default: true) - GPTME_LESSONS_MAX_INCLUDED (default: 5) Keywords are extracted from both user and assistant messages in all contexts, with no mode detection. Fixes inconsistencies identified in Greptile review (PR gptme#771). Co-authored-by: Bob <bob@superuserlabs.org> --------- Co-authored-by: Erik Bjäreholt <erik.bjareholt@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
Post-merge documentation for the lesson system (PRs #687 and #722).
Changes
Created docs/lessons.rst: Complete documentation of the lesson system
Updated docs/index.rst: Added lessons to documentation table of contents
Enhanced docs/lessons/README.md:
Updated README.md: Added lessons feature to main features list
Related PRs
Testing
Co-authored-by: Bob bob@superuserlabs.org
Important
Adds comprehensive documentation for the lesson system, including creation, configuration, and usage details, and updates main documentation index and README.
docs/lessons.rstwith detailed lesson system documentation, including lesson creation, format, metadata, configuration, CLI commands, and examples.docs/lessons/README.mdto reference main documentation, explain autonomous mode, document CLI commands, and provide best practices and migration guide.docs/index.rstto include lessons in the table of contents.README.md.This description was created by
for 29c8584. You can customize this summary. It will automatically update as commits are pushed.