Follow the learning product workflow
See how review and releases connect shared improvements.
Open this resource →Workbook · Shared improvements
Turn a useful correction into a reviewable lesson.
Review a private learning candidate, examine its verification, and plan a limited release when the evidence supports reuse.
A correction can help the next task. First establish where it applies, what was verified, and which information can safely leave the local draft.
01 / Workbook · Shared improvements
A lesson from a pagination repair
A Search developer fixes duplicate results at a page boundary. A focused cursor check exposes a problem that a general build never exercised.
The developer sees a possible reusable lesson: pagination changes need checks across adjacent pages. This scenario is illustrative.
The observation has a useful beginning, but its scope still matters. A service with a different pagination contract may need different checks.
Describe the task condition before proposing a shared rule. Reuse works better when the reader can recognize when the lesson belongs in their task.
Keep the verification close to the proposed lesson. A completed agent response does not establish that the repaired page boundary behaves correctly.
The purpose of this workbook is to organize that evidence and the review decision. It does not assume that every local improvement needs fleet distribution.
02 / Workbook · Shared improvements
Understand the private candidate
Native optimization can draft observations through the active native agent. Those observations remain advisory and private until a separate sharing decision.
A local draft is scoped to the repository, runtime, and enrollment. Discovery alone does not add it to repository files or an upload queue.
Two distinct tasks can qualify a candidate. A correction with an existing explicit verification receipt can also provide qualification.
Qualification does not turn a model's completion claim into a verified outcome. The receipt must relate to meaningful verification of the intended behavior.
The developer can inspect the candidate, keep it locally, or dismiss it. Before sharing, the developer must inspect the exact bounded contribution and confirm submission interactively.
The MCP bridge cannot perform that submission automatically. Keep local candidate state separate from a contribution actually received by the service.
03 / Workbook · Shared improvements
Draft a lesson with a recognizable condition
For the Search example, describe the pagination contract that made the adjacent-page check useful. Avoid prescribing one test command to unrelated repositories.
Practice lesson:
For a change to cursor pagination, inspect the boundary between consecutive pages.
Check whether a record can disappear or appear twice.
Use checks that match the service’s documented ordering contract.Explain why the check mattered: compilation did not exercise cursor continuity. Keep that explanation separate from a measured claim about the lesson’s effect.
Describe the limits. A read-only documentation edit does not need pagination execution merely because this lesson exists.
Remove private identifiers from the shareable summary. The useful condition and observed result can often be expressed without exposing a query, record, or path.
Public contributions exclude source, scripts, prompts, transcripts, paths, commands, and credentials. Digests identify protected material without transmitting its private bytes.
04 / Workbook · Shared improvements
Inspect the candidate before sharing
- 01
Check the described condition
Compare the proposed applicability with the task that produced it.
- 02
Check the observed result
Locate the meaningful verification supporting the candidate.
- 03
Check the explanation
Separate the developer’s reasoning from evidence of the actual outcome.
- 04
Check the proposed audience
Identify other tasks or projects where the condition could reasonably occur.
- 05
Check the public summary
Remove information that does not belong in a bounded shared contribution.
- 06
Choose the next state
Keep, dismiss, or explicitly authorize the reviewed submission.
05 / Workbook · Shared improvements
Use the supported local review commands
After setup, list the native candidates. Use the returned identity to open the candidate you intend to examine.
betterloop optimize --harness codex --action list
betterloop optimize --harness codex --candidate UUID --action reviewCompare the private draft with your task evidence. Read its condition, rationale, and verification claims before making a decision.
Keep local preserves the candidate without submitting it. Dismiss removes the notice. Submitted revisions remain immutable; revised drafts have new identities.
Share for review opens the bounded public submission. Type submit only after you choose to authorize that exact contribution.
Permission to complete the original development task does not include this separate sharing decision. The task can remain complete while the candidate stays private.
06 / Workbook · Shared improvements
Review script proposals through their proper path
A lesson may suggest a repeatable procedure that needs executable support. That proposal requires more than a short memory entry.
A script-backed draft needs instructions, scripts, focused tests, and verification tied to exact bytes. Private script content is excluded from the learning contribution.
Review and merge executable resource files through the ordinary repository pull-request workflow. The bounded contribution can describe the idea without transporting its private implementation.
A generated Team Rules variant remains a proposal for review. It still needs the normal governance, signing, and release process.
Text learning entries and executable skills therefore have different delivery paths. Skills with scripts use Team Rules rather than executable fleet packs.
Choose the form that fits the repeatable work. A script should solve a stable operational need rather than merely make the lesson look more complete.
07 / Workbook · Shared improvements
Assess readiness without turning counts into causation
To qualify, a candidate needs evidence from three contributors and two projects, with five verified successes and no verified failures. These conditions determine eligibility for the next review stage.
They do not prove that the lesson caused those successes. Inspect the task conditions, applied revision, and verification alongside the counts.
TypeSafe/Jev examines sanitized candidates for reuse, evidence, sensitive details, conflicts, and workflow form. Private code and transcripts are outside that assessment.
An absent, unavailable, or uncertain assessment leaves the candidate pending. Assessment can recommend a memory, skill, or skill with scripts.
Approval must come from another eligible human and cover the precise lesson revision that qualifies for review. The author cannot approve their own draft.
New evidence or changed review text can require reassessment and invalidate prior readiness. Approval needs to correspond to the final content under review.
08 / Workbook · Shared improvements
Plan a useful first release
- 01
Select comparable work
Choose tasks that match the lesson’s applicability.
- 02
Identify the revision
Record the exact lesson version entering the limited group.
- 03
Define the useful outcome
Specify the observable behavior that would support a successful result.
- 04
Choose the initial group
Keep the first rollout small enough for direct review.
- 05
Separate exposure from outcomes
Record delivery independently from meaningful verification results.
- 06
Review adverse observations
Investigate regressions and tasks where the lesson does not fit.
- 07
Decide the next release
Continue, revise, or pause according to the available evidence.
09 / Workbook · Shared improvements
Interpret the first observations carefully
A canary is a limited initial rollout. For the example lesson, use comparable cursor-pagination tasks rather than unrelated service migrations.
Receiving a lesson establishes exposure. A meaningful verification receipt can support an outcome report, but it remains client-reported evidence rather than machine attestation.
A failing verification command is neutral on its own. It may reveal the intended defect without establishing that the lesson caused a failure.
Likewise, token or timing comparisons need comparable task conditions. A smaller task cannot establish that a lesson made an unrelated larger task more efficient.
Inspect the actual applied revision when a result looks wrong. Consider whether the instruction was incorrect, applied outside its condition, or unrelated to the problem.
Keep those explanations separate until the available evidence supports one. Qualification counts do not remove the need for that investigation.
10 / Workbook · Shared improvements
Revise or retire a lesson with a clear record
If another service uses incompatible ordering, pause wider distribution while examining its result. Compare that task with the lesson's stated condition.
Narrow an overbroad lesson in a new reviewed revision. Preserve the previous observations so the change has a visible reason.
Use revocation when the approved response requires it. Refresh signed state before repeating the relevant check on connected clients.
Explain the issue through bounded summaries. Keep private source and raw task content within their authorized repository review process.
Sometimes the right outcome is a useful local candidate. Insufficient evidence for shared use does not erase the value of the original observation.
Record why wider release was deferred. That decision helps a later reviewer distinguish an untested idea from an evaluated but unsuitable generalization.
11 / Workbook · Shared improvements
Questions during lesson review
Does finishing the task count as a verified success?
A completion statement alone does not qualify. Meaningful explicit verification must establish the intended behavior.
Can the author approve the final lesson?
No. Another eligible human must approve the exact revision that qualifies for review.
Can one local correction become useful without a fleet release?
Yes. The developer can keep a candidate private while gathering evidence or using it within its original context.
What belongs in the public contribution?
Only the reviewed bounded submission. Private work content and executable bytes remain outside that submission.