docs(lessons): add absolute-paths and git-commit-format workflow lessons#74
docs(lessons): add absolute-paths and git-commit-format workflow lessons#74TimeToBuildBob wants to merge 1 commit intomasterfrom
Conversation
These two lessons have the highest positive impact on session reward from LOO (leave-one-out) effectiveness analysis on Bob's workspace: - absolute-paths-for-workspace-files (Δ=+0.198, p<0.001) - git-commit-format (Δ=+0.162, p<0.001) Neither lesson is currently in gptme-contrib/lessons/, so new agents created from this template were missing both. Adding them to the template's own lessons/workflow/ ensures all new agents start with these high-value behavioral constraints. Co-authored-by: Bob <bob@superuserlabs.org>
Greptile SummaryThis PR adds two new workflow lessons to the Key findings:
Confidence Score: 2/5
Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[Agent writes a file] --> B{Path type?}
B -->|Relative path| C[Resolve against CWD]
C --> D{CWD = agent workspace?}
D -->|Yes| E[✅ File lands correctly]
D -->|No - changed dir| F[❌ File lands in wrong repo]
B -->|git rev-parse toplevel| G[Resolve against current git root]
G --> H{Current repo = agent workspace?}
H -->|Yes| E
H -->|No - in external repo| F
B -->|Hardcoded absolute path| I[Always resolves to fixed location]
I --> E
Last reviewed commit: "docs(lessons): add a..." |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
|
|
||
| # ✅ Correct: absolute path works from any directory | ||
| WORKSPACE=$(git rev-parse --show-toplevel) | ||
| echo "..." >> "$WORKSPACE/journal/2025-10-14-topic.md" | ||
| ``` |
There was a problem hiding this comment.
The suggested fix using git rev-parse --show-toplevel does not solve the problem this lesson is meant to prevent. If the agent has already cd'd into an external repo (the exact failure scenario described), git rev-parse --show-toplevel returns the root of that repo — not the agent workspace. The file would still land in the wrong location.
The rule itself is correct ("always use absolute paths"), but the shell example undermines it by deriving the path from the current git context rather than using a hardcoded or pre-established absolute path. The second example further down with a literal /home/agent/workspace/... path is actually the correct approach.
Consider replacing the shell example with something like:
# ❌ Wrong: relative path depends on cwd
cd ~/projects/gptme
echo "..." >> journal/2025-10-14-topic.md # creates in wrong repo!
# ❌ Also wrong: still depends on current git repo
WORKSPACE=$(git rev-parse --show-toplevel)
echo "..." >> "$WORKSPACE/journal/2025-10-14-topic.md"
# ✅ Correct: hardcoded absolute path to agent workspace
echo "..." >> "/home/agent/workspace/journal/2025-10-14-topic.md"
| - **No confusion**: Explicit about which repo/workspace receives the file | ||
|
|
||
| ## Related | ||
| - Full context: knowledge/lessons/workflow/absolute-paths-for-workspace-files.md |
There was a problem hiding this comment.
The Related section links to knowledge/lessons/workflow/absolute-paths-for-workspace-files.md, but this companion file is not created in this PR and does not exist in the repository. Per the README, companion docs are optional — if there is no companion doc, this line should be removed rather than pointing to a non-existent file.
| - Full context: knowledge/lessons/workflow/absolute-paths-for-workspace-files.md | |
| ## Related | |
| - [Conventional Commits Specification](https://www.conventionalcommits.org/) |
Or simply omit the Related section body if there are no valid links.
| --- | ||
| match: | ||
| keywords: | ||
| - "save file to" | ||
| - "write journal entry" | ||
| - "mkdir -p journal" | ||
| - "file path" | ||
| - "wrong directory" | ||
| - "file ended up in wrong" | ||
| - "journal created in external repo" | ||
| status: active |
There was a problem hiding this comment.
TEMPLATE.md uses an inline list for keywords:
match:
keywords: ["keyword1", "keyword2", "specific phrase"]Both new lessons use YAML block sequence style (dashes). While both are valid YAML, the inconsistency with the template may cause issues with pre-commit validators that parse the frontmatter with specific format expectations. The same applies to lessons/workflow/git-commit-format.md (lines 1–12).
| --- | |
| match: | |
| keywords: | |
| - "save file to" | |
| - "write journal entry" | |
| - "mkdir -p journal" | |
| - "file path" | |
| - "wrong directory" | |
| - "file ended up in wrong" | |
| - "journal created in external repo" | |
| status: active | |
| --- | |
| match: | |
| keywords: | |
| - "save file to" | |
| - "write journal entry" | |
| - "mkdir -p journal" | |
| - "file path" | |
| - "wrong directory" | |
| - "file ended up in wrong" | |
| - "journal created in external repo" | |
| status: active | |
| --- |
Consider aligning with the template format:
---
match:
keywords: ["save file to", "write journal entry", "mkdir -p journal", "file path", "wrong directory", "file ended up in wrong", "journal created in external repo"]
status: active
---| ## Rule | ||
| All commit messages must follow Conventional Commits format with a type prefix, optional scope, and short description. | ||
|
|
There was a problem hiding this comment.
Per the project's writing guidelines for tool/agent instructions, the rule and context sections should be framed in terms of how following this pattern benefits the agent and enhances its capabilities, rather than as a documentation-style imperative. The current phrasing ("All commit messages must follow…", "When creating git commits…") reads as external documentation rather than agent-centric guidance.
For example:
| ## Rule | |
| All commit messages must follow Conventional Commits format with a type prefix, optional scope, and short description. | |
| ## Rule | |
| Use Conventional Commits format to keep history scannable, enable automated changelogs, and signal the nature of your change at a glance. | |
| ## Context | |
| Every time you create a git commit, this format helps reviewers — and your future self — quickly understand what changed and why. |
The same applies to the absolute-paths-for-workspace-files.md lesson (## Rule and ## Context sections).
Rule Used: When writing tool instructions, focus on how the s... (source)
Learnt From
gptme/gptme#722
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
|
Shouldn't these lessons go in gptme-contrib instead? |
|
You're right. These are generic lessons that should benefit all agents via gptme-contrib, not just new ones from the template. Closing this. Will create a gptme-contrib PR instead with properly generalized versions (the absolute-paths lesson hardcodes Bob's path, and the commit-format lesson includes Bob-specific co-authorship that needs to be stripped). |
|
Follow-up: created gptme/gptme-contrib#507 with properly generalized versions:
|
2 participants
Summary
Adds two workflow lessons to the template's
lessons/workflow/directory, based on LOO (leave-one-out) effectiveness analysis from Bob's workspace:absolute-paths-for-workspace-files(Δ=+0.198 session reward, p<0.001): Always use absolute paths when writing workspace files. Prevents journal entries and other files from being created in the wrong directory when working across multiple repos.git-commit-format(Δ=+0.162 session reward, p<0.001): Conventional Commits format for all commit messages. Keeps git history clean and scannable.Neither lesson is currently in
gptme-contrib/lessons/workflow/, so new agents created from this template were missing both. The template's ownlessons/workflow/directory was empty before this PR.Why these two?
From LOO effectiveness analysis (
scripts/lesson-loo-analysis.py --category-controlled), these are the top two lessons by session reward improvement that are NOT already in gptme-contrib. Adding them to the template ensures every new agent benefits from day one.Test plan
markdown-codeblock-syntax.mdstyle