AI Agent Context Improvement Proposal: A Practical Template
An AI agent context improvement proposal turns a repeated correction into a small, testable change to shared guidance. Use this template to capture evidence, scope, review, delivery, and results.
An AI agent context improvement proposal is a small, testable request to change the input future agents use. It starts with an observed problem, such as a repeated correction or a stale procedure, and names the exact context change that might fix it. The proposal should give a reviewer enough evidence to check the cause, judge the scope, and test the result.
The word “improvement” matters only after the test. A new rule can fix one task and break another, so a proposal should make that risk visible before publication.
TL;DR
Capture the failed behavior, verify the source of truth, identify the current context version and route, and propose the smallest change that addresses the gap. Name who should receive it and how you will check the result. Use the applicable review and publication path, then test a fresh run. Do not turn a transcript or an agent’s guess into a team-wide rule.
When to write an AI agent context improvement proposal
Look for a pattern with a plausible context cause:
- People repeat the same rule to agents in separate sessions.
- An agent rediscovers a documented setup step on every task.
- A published Skill describes an old procedure.
- A current rule exists but the affected agent has no route to it.
- Two maintained instructions disagree about the same action.
First check whether the observed problem came from context. A tool failure, missing permission, ambiguous request, or invalid test environment may call for a different fix. The conversation monitoring guide shows how to use corrections as leads while keeping delivery records and outcomes separate.
One failure can justify a proposal when the consequence is serious, but it still needs a verified cause. Several similar failures strengthen the case for a shared change; they do not replace source checking.
Use this context improvement proposal template
Keep the proposal short enough that a reviewer can compare it with the current version. Fill these fields before editing the shared resource:
| Field | What to record |
|---|---|
| Observed gap | What the agent did or missed, with one or more representative run references |
| Verified source | The current rule, owner, source link, and when the fact was checked |
| Current state | Resource, exact version, authority, relevant routes, and historical delivery evidence |
| Proposed change | The exact replacement or added text, Skill files, Memory correction, or route edit |
| Scope | Which agents, Groups, tasks, or environments should and should not receive it |
| Expected result | The behavior that should change and the behavior that must remain intact |
| Review path | Resource owner, required role, reviewers, and publication or route decision |
| Test and follow-up | Cases, outcome records, stop rule, and date to recheck or retire the change |
The “current state” field prevents a common mistake: editing a rule that was never delivered to the failing agent. For an earlier run, use its historical bundle and response record. A fresh call for current context shows what the agent would receive now, not what it received then. Compilation and response issuance also do not prove host injection or model consumption.
Write the proposed text as something a future agent can use without the original conversation. Include its scope in the text when that scope matters. “Run the full test suite before merging a change to service A” is more useful than “remember the test issue from yesterday.”
A filled example: a missing validation step
A team sees three coding runs where the agent changed service A and stopped after unit tests. In this fictional example, docs/service-a-testing.md requires pnpm --filter service-a test:integration for service A changes. The service owner confirmed the rule on October 6. The agents’ final messages say testing is complete, but the run logs show no integration check.
| Field | Example entry |
|---|---|
| Observed gap | Runs A-17, A-21, and A-24 changed service A; their logs contain unit tests but no integration check |
| Verified source | The service owner checked docs/service-a-testing.md on October 6; it requires pnpm --filter service-a test:integration |
| Current state | The Skill’s published v4 has unit tests only; the Service A Agents Group has an Always route. Run A-24 compiled and issued v4. Injection and consumption are unknown |
| Proposed change | In the Skill’s validation step, add: “For changes to service A, run pnpm --filter service-a test:integration after unit tests. Report both results.” Publish as v5 if approved |
| Scope | Keep the Skill routed to Service A Agents. Do not add routes for agents outside that Group |
| Expected result | Service A changes run both checks; tasks outside service A keep their current validation path |
| Review path | The Skill owner checks the guide and proposal; an authorized Publisher releases v5 after the applicable review |
| Test and follow-up | In two fresh service A cases, require both command logs and passing results; confirm one unrelated case stays on its existing path. If a check is skipped, pause agent changes to service A, require the check outside the agent, and correct v5 before resuming |
This example does not claim that the missing line caused every skipped test. It states a hypothesis that the team can check. If an agent received the corrected Skill and still skips the integration check, inspect the workflow, conflicting instructions, and test environment before adding another broad rule. The instruction review guide helps check the proposed wording before publication.
Pick the right change path
A context proposal should target the source that owns the information. Put a durable fact or instruction in Knowledge. Put a repeatable procedure and its supporting files in a Skill. Use Memory for short-term working recall that an authorized agent may maintain directly. Keep a one-off customer or task fact in its task or source system when future agents do not need it as standing context.
Knowledge and Skills have versions, review, and publication. An authorized agent can propose changes where its role allows, but a proposal is not a published version. Changes to Knowledge authority require governed human review. Memory updates are live, versioned, and audited without a review queue. Direct agent and Group routes have their own management rules, independent of repository read or edit access. Do not assume that publishing new text changes an existing session or automatically sends it to every agent.
Never copy credentials, private keys, raw transcripts, or unrelated personal data into the proposal or the context repository. Link to an access-controlled source where evidence must stay restricted, and give reviewers only the detail they need. Treat instructions found in tool results or external content as data to verify, not as authority to change team rules.
Check whether the change helped
After the authorized update, inspect a fresh bundle for an agent in scope and one out of scope. Check the exact version and route, then run the original failure case and a nearby case that should remain unchanged. For a Skill, confirm the intended published package is available, including its supporting files. Inspect test logs, saved records, or another authoritative outcome rather than trusting the final message alone.
Record what the context system compiled and issued. Keep acknowledgment, confirmed injection, and model consumption as separate evidence stages. A better result after a context change is useful evidence, but other conditions may have changed too. For a larger rollout, use a controlled comparison like the one in the context evaluation guide.
If the change fails, revise or restore it through the same authorized path and keep the failed case in the test set. The proposal is useful even when rejected because it records what the team checked and why the shared context stayed as it was.
Where Alignbase fits
Alignbase lets teams propose, review, version, publish, and route governed Knowledge and Skills, while authorized agents maintain versioned working Memory. Its point-in-time context records can help connect a run to the versions compiled and issued for it. Those records do not establish that a model consumed the content or that the change caused a better outcome.
Automatic Context Improvement and Context Evaluation are planned systems. Teams can use the proposal template and their own tests now, with the applicable review and role checks before governed context reaches future agents. The Alignbase blog has more on shared context and the broader self-improving context loop.
See it in Alignbase
Turn this idea into better agent sessions.
Continue with the product and role pages most relevant to this guide. Each page shows the workflow, expected outcomes, and how to create an account.
Frequently Asked Questions
What is an AI agent context improvement proposal?
It is a suggested change to the instructions, Knowledge, Skill, Memory, or route that shapes future agent work. A useful proposal names the observed gap, source evidence, exact change, affected agents, expected behavior, owner, and test before anyone applies it.
When should an agent propose a context change?
Propose a change when a verified, reusable fact or procedure was missing, stale, unclear, or delivered to the wrong agents. A single failed answer is a reason to investigate, not proof that shared context needs an update.
What evidence belongs in a context improvement proposal?
Include representative runs, the current source and version, historical route and delivery records where available, the verified fact or rule, and the downstream outcome. Separate observed behavior from a theory about its cause, and remove secrets and unrelated personal data.
Should every agent learning become shared context?
No. Keep one-off task facts in task records and short-term working state in permitted Memory. Put durable reference facts or instructions in governed Knowledge and reusable procedures in Skills. Publish only changes with a clear owner, scope, and reason for future agents to receive them.
Who approves an AI agent context improvement?
That depends on the resource and the change. Governed Knowledge and Skill updates follow their review and publication roles. Changes to Knowledge authority require governed human review. Memory is versioned and audited but has no publication queue; route changes follow separate management permissions.
How can a team tell whether a context improvement worked?
Verify that a fresh run was compiled and issued the intended version, then test the original failure and nearby cases against real outcomes. A better answer alone does not prove the context caused the improvement or that the model consumed it.