| name | suggest-improvement |
| description | Propose codifying reusable lessons from trial-and-error or explicit user requests into lint, rules, or skills. Use near task completion after failed first attempts, or when the user asks to "make it a rule" or "leave a lesson". NOT for empirically testing instructions on fresh agents (tune-prompt) or drafting a new skill without a lesson to codify. |
Suggest improvement
When a task finishes, extract "if we had known this upfront, we would not have taken the detour" and make it reusable. Lessons learned through trial and error are especially worth codifying.
When to use
- Near task completion after trial-and-error, or when asked to "leave a lesson" / "make it a rule"
- After an initial attempt failed and you reached a solution through iteration
- When similar work is likely to happen again
Do not use when:
- The task succeeded on the first try with nothing to extract
- A one-off, project-specific fix (a commit message is enough)
Steps
1. Pair failure and success
Write:
- First attempt: what you tried and how it failed
- Final solution: what actually worked
- Bridge insight: why the first attempt could not reach the solution
2. State what should have been known upfront
Condense to 1–3 sentences as instructions to future you. Prefer imperatives: "do not …", "check … first".
3. Classify the output
| Criterion | Destination | Example |
|---|
| Detectable mechanically at syntax level | Lint (ESLint, ast-grep, etc.) | Use set.size instead of Array.from(set).length |
| One short line, always on, no judgment | Agent config (global or project) | "Use pnpm v10+" |
| Procedure, context, templates | New or existing skill | "How to write MoonBit C bindings" |
| One-off project-specific | Skip (commit/PR is enough) | — |
Principle: if lint can catch it, do not put it in prose. Agents ignore natural-language duplicates of static checks.
"Agent config" varies by tool (Cursor: .cursor/rules/, Claude Code: CLAUDE.md, etc.). Match this project.
4. Duplicate check (required)
Before proposing, search existing knowledge. Prefer append over new when similar content exists.
Extract 2–3 keywords and search:
- Global skill dirs (
~/.cursor/skills/, ~/.claude/skills/, etc.)
- Project agent config (
.cursor/rules/, CLAUDE.md, etc.)
- Lint config
Classify:
- New: no hit → normal proposal
- Append: related rule/skill exists and new info complements it
- Duplicate: already fully covered → no proposal (record the duplicate check only)
- Unclear: cannot decide → ask the user
5. Prepare proposal text
Prepare content as text only—do not write files yet (step 7 writes after approval).
Lint: include rule definition and valid/invalid test cases.
Agent config: add brief rationale in parentheses.
- Use pnpm v10 or newer (lockfile format differs on v9 and below, causing CI drift)
Skill: frontmatter + when to use + steps + caveats, matching existing skill style.
6. Get user approval
Show the proposal and wait for approval. Do not edit agent config or skills without approval. If rejected, keep notes in the session only.
7. Commit on a separate branch
After approval, create a branch separate from main work and write files only there.
Stash only if the working tree has changes (tracked, staged, or untracked). If the tree is clean, do not run git stash—a no-op stash can make a later blind git stash pop restore the wrong entry.
ORIGINAL_BRANCH=$(git branch --show-current)
if ! git diff --quiet || ! git diff --cached --quiet || [ -n "$(git ls-files --others --exclude-standard)" ]; then
git stash push -u -m "suggest-improvement: before improvement branch"
fi
git fetch origin && git checkout -b cursor/improve-<short-lesson-name> origin/main
git add <files>
git commit -m "<short improvement message>"
8. Open a PR and return to the original branch
git push -u origin HEAD
After push, create a PR per create-pull-request. In Problem, note codifying a lesson from the task; in Solution, include the retrospective summary.
Then return:
git checkout "$ORIGINAL_BRANCH"
Run git stash pop only if you stashed before creating the improvement branch.
Presentation format
## Retrospective
- First failure: <one line>
- Final solution: <one line>
- Insight: <one line>
## Proposal
Candidates:
- [lint] <rule name>: <one line>
- [skill append] <existing skill>: <one line>
- [skill new] <skill name>: <one line>
- [rule] agent config (global/project): <one line>
Duplicate (no proposal):
- <existing skill/rule> already covers this → no addition
Declined:
- <one-line reason> (e.g. project-specific / hard to express in lint / absorbed elsewhere)
Reply with item numbers or names to adopt. "No proposal" is valid.
For multiple lessons, use multiple retrospective blocks and tag proposal lines with "from lesson N". Omit empty sections.
Notes
- Do not skip describing failure. Solution-only notes invite the same trap.
- Avoid overly specific grains. Abstract to "what to verify", not raw version numbers.
- Do not write without approval.
- Zero proposals is valid. Do not invent thin lessons.
- Do not dirty the main feature branch. Stash if needed, branch, PR, then return.
