Understand contribution data
See how private drafts differ from public summaries and evidence digests.
Open this resource →Shared engineering knowledge
Let a useful correction outlive its session.
Keep local observations private until a developer chooses to share them, then review their usefulness before wider distribution.
Teams often discover the same working lesson more than once. Betterloop gives a useful observation a deliberate route from local draft to reviewed guidance.
01 / Shared engineering knowledge
Describe the recurring situation, not the whole conversation.
Imagine Harbor's Search team repeatedly overlooking a verification step after search-api changes. The useful lesson explains when that check matters and what result is required.
A reminder to take care gives the next developer little help. A specific condition and a meaningful completion check are easier to apply.
The example is fictional. It illustrates the contribution workflow rather than a measured customer improvement.
Supported native integrations can ask the active coding agent to draft generalized observations locally. That request remains advisory; the agent is not compelled to continue.
Two distinct tasks can qualify an observation. A correction can also qualify when it already has an explicit verification receipt.
Repeated identical observations are deduplicated. A private draft stays within its repository, agent, and enrollment context until the developer makes a sharing decision.
Discovery does not add files to Git or create an upload queue. The draft is an opportunity for review rather than an automatic publication.
Remove customer details from the proposed lesson. Explain the general condition without copying prompts, source, transcripts, paths, arguments, or credentials.
02 / Shared engineering knowledge
Give the developer a real choice.
A supported active context can present a short notice for a candidate revision. A context without space leaves that notice pending.
The developer can inspect the exact private draft. Keeping or dismissing it ends repeated notices for that revision without requiring a public contribution.
Sharing opens the bounded submission for inspection. Terminal confirmation is required before that specific content is sent. The MCP bridge cannot make that decision automatically.
Submitted revisions remain immutable. Editing a draft produces a new candidate identity so review results do not silently attach to different text.
Keeping a lesson private is a valid outcome. It can remain useful locally even when its details are too specific for a team-wide recommendation.
For Harbor, this means contributors choose what leaves the working context. A positive local result is not permission to upload the surrounding work.
Use the commands below to list candidates, inspect one revision, or retain it privately. None of these operations publishes a shared learning pack.
betterloop optimize --harness codex --action list
betterloop optimize --harness codex --candidate UUID --action review
betterloop optimize --harness codex --candidate UUID --action keep03 / Shared engineering knowledge
Choose a form that preserves the judgment.
Some improvements fit a brief memory. Others need a reusable skill. A deterministic part of a workflow may justify scripts with focused verification.
A deterministic step has defined inputs and repeatable outputs. Leave judgment in the instructions when a fixed procedure would conceal an important choice.
A script draft describes dependencies, inputs, outputs, and side effects. Its instructions and test files should make the intended behavior inspectable.
Staging places the reviewed files in a private optimization directory. It neither stages a Git change nor replaces different existing content.
Explicit verification compares candidate bytes before and after the check. A passing receipt binds to the candidate digest rather than an unrelated later revision.
The public learning submission carries a bounded summary and evidence digests. It does not carry private instructions or script files.
Executable distribution follows normal repository review and Team Rules. A script does not become executable merely because a learning contribution was accepted.
| Representation | Appropriate use | Publication route |
|---|---|---|
| Memory | A concise insight can improve a later decision | Text review followed by a signed learning pack |
| Skill | A repeated workflow needs contextual judgment | Team Rules and reviewed resource publication |
| Skill with scripts | A repeatable procedure benefits from deterministic execution | Focused verification, pinned file references and Git approval |
04 / Shared engineering knowledge
Ask whether the lesson can travel.
Assessment examines the sanitized submission for reusable value and supporting evidence. It also checks sensitive detail, conflicts, overfitting, and the appropriate representation.
Unavailable assessment does not produce approval. Missing or malformed results leave the contribution pending until a usable result exists.
The assessment records input and content digests alongside its model, prompt, schema, and code versions. Reviewers can identify exactly what the result evaluated.
An edit to the review text or supporting evidence invalidates earlier readiness. The changed revision needs another assessment before approval.
For an eligible memory, one reviewer generalizes the contribution. A different human approves that exact revision before signing and staged delivery.
A skill with scripts needs meaningful passing verification before submission. Its later delivery still uses the ordinary configuration approval path.
A search-specific lesson may be valuable to Search but unsuitable for another team. Narrow applicability before widening distribution rather than adding a universal claim.
- 01
Inspect the candidate
Read the generalized observation and its supporting local evidence.
- 02
Choose the representation
Select memory, skill, or skill with scripts for the actual improvement.
- 03
Confirm the submission
Approve the bounded public content in the terminal.
- 04
Evaluate reuse
Assess evidence and applicability for the exact submitted revision.
- 05
Complete independent review
Obtain separate generalization and approval reviews where required.
- 06
Check staged delivery
Inspect the signed pack and its intended cohort.
05 / Shared engineering knowledge
Measure the next use, not the download.
Exposure means an integration supplied an entry to a session. A downloaded pack or installed file alone does not establish that event.
The subsequent result needs a meaningful local verification check. A completed model turn does not show that the lesson improved the work.
For Search, a useful check would exercise the verification behavior the lesson addresses. Repeating the instruction in a test proves little about correctness.
Compare similar tasks when discussing correctness, elapsed time, tool calls, or available token counts. Record differences in difficulty and integration coverage.
A failing check needs investigation. It does not by itself establish that the lesson caused the failure. Uncertain outcomes stay neutral.
An attributed failure can pause staged distribution. Scope, expiry, and revocation remain part of the signed pack; later signed material carries revocation state.
Before restarting distribution, examine the affected scope and the correction. Retain the verification context rather than treating a new signature as outcome evidence.
The result can support a narrow engineering conclusion. A successful check on a search task does not justify a promise about all future tasks.
Does learning require uploading our session history?
No. Native candidate drafting happens locally. Sharing requires a bounded submission that the developer inspects and explicitly confirms.
Can an automated assessment approve publication?
No. It informs the review process. Independent human approval, signing, and staged distribution remain separate requirements.
What proves that a lesson helped?
Record actual exposure and a meaningful verification result on suitable work. Treat uncertain attribution as unresolved rather than a positive outcome.