cleveragents/cleveragents-core

Fork 3

Proposal: improve implementer agents — verify domain model fields before referencing #2879

New issue

Closed

opened 2026-04-05 02:31:40 +00:00 by freemo · 4 comments

freemo commented

2026-04-05 02:31:40 +00:00

Owner

Agent Improvement Proposal

Pattern Detected

Type: Prompt improvement
Affected Agents: ca-implementer-sonnet, ca-implementer-codex, ca-implementer-opus
Evidence:

During the v3.7.0 build session (session state issue #1530), the milestone reviewer discovered a critical integration failure pattern:

"Session CLI ↔ Domain Model Mismatch — PRs #1566, #1567, #1569, #1481 reference fields that don't exist — Runtime crashes on session CLI commands"

Specifically, multiple implementer agents created code referencing Session.automation_profile, SessionService.list_messages(), and other fields/methods that do not exist in the actual domain model. This caused:

5 Pyright type errors on master (issue #2109)
Runtime crashes on session CLI commands
Broken typecheck quality gate (1 of the 4 failing gates)

The root cause: issue descriptions described desired behavior (e.g., "display the Automation field"), and implementers assumed the corresponding domain model fields already existed. They wrote code like session.automation_profile without first checking whether Session has an automation_profile attribute.

This pattern was identified in the session state comment:

"Integration testing is critical. Multiple independently-merged PRs created integration failures that only became visible in holistic review."

Proposed Change

Add a new subsection to the implementer agents' "## Your Task" section, between steps 2 and 3:

### Domain Model Verification (CRITICAL)

Before writing code that references any field, method, or attribute on a
domain model class, you MUST verify it exists by reading the actual class
definition. **Never assume a field exists based solely on the issue
description.** Issue descriptions often describe *desired* behavior — the
field may not yet exist in the codebase.

Specifically:
- Before accessing `model.some_field`, read the model class to confirm
  `some_field` is defined.
- Before calling `service.some_method()`, read the service class to confirm
  `some_method` exists with the expected signature.
- If a required field or method does not exist, you must CREATE it as part
  of your implementation (including database schema changes if needed),
  not just reference it and hope it exists.

This change would be applied to all three implementer agent definitions:

.opencode/agents/ca-implementer-sonnet.md
.opencode/agents/ca-implementer-codex.md
.opencode/agents/ca-implementer-opus.md

Expected Impact

Prevents domain model mismatches: Implementers verify fields exist before referencing them
Catches missing fields early: Instead of discovering mismatches in holistic review, they're caught during implementation
Reduces Pyright errors: Type errors from non-existent fields are eliminated at the source
Saves escalation cycles: Fewer quality gate failures means fewer escalation attempts in the subtask loop

Risk Assessment

Very low risk: This adds verification guidance without changing any implementation logic or permissions.
Potential downside: Slightly more time spent reading model definitions before implementing. However, this is far less time than the escalation cycles wasted on Pyright failures.
No behavioral change: Implementers already have "Read any existing code in the relevant modules" as step 2. This makes that guidance more specific and actionable.

This is a proposal from the agent evolver. A human must approve this issue before the change will be implemented. To approve: remove the needs feedback label, add State/Verified, or comment with approval.

Automated by CleverAgents Bot
Supervisor: Agent Evolver | Agent: ca-agent-evolver

## Agent Improvement Proposal ### Pattern Detected **Type**: Prompt improvement **Affected Agents**: `ca-implementer-sonnet`, `ca-implementer-codex`, `ca-implementer-opus` **Evidence**: During the v3.7.0 build session (session state issue #1530), the milestone reviewer discovered a critical integration failure pattern: > "Session CLI ↔ Domain Model Mismatch — PRs #1566, #1567, #1569, #1481 reference fields that don't exist — Runtime crashes on session CLI commands" Specifically, multiple implementer agents created code referencing `Session.automation_profile`, `SessionService.list_messages()`, and other fields/methods that **do not exist** in the actual domain model. This caused: - **5 Pyright type errors** on master (issue #2109) - **Runtime crashes** on session CLI commands - **Broken typecheck quality gate** (1 of the 4 failing gates) The root cause: issue descriptions described *desired behavior* (e.g., "display the Automation field"), and implementers assumed the corresponding domain model fields already existed. They wrote code like `session.automation_profile` without first checking whether `Session` has an `automation_profile` attribute. This pattern was identified in the session state comment: > "Integration testing is critical. Multiple independently-merged PRs created integration failures that only became visible in holistic review." ### Proposed Change Add a new subsection to the implementer agents' "## Your Task" section, between steps 2 and 3: ```markdown ### Domain Model Verification (CRITICAL) Before writing code that references any field, method, or attribute on a domain model class, you MUST verify it exists by reading the actual class definition. **Never assume a field exists based solely on the issue description.** Issue descriptions often describe *desired* behavior — the field may not yet exist in the codebase. Specifically: - Before accessing `model.some_field`, read the model class to confirm `some_field` is defined. - Before calling `service.some_method()`, read the service class to confirm `some_method` exists with the expected signature. - If a required field or method does not exist, you must CREATE it as part of your implementation (including database schema changes if needed), not just reference it and hope it exists. ``` This change would be applied to all three implementer agent definitions: - `.opencode/agents/ca-implementer-sonnet.md` - `.opencode/agents/ca-implementer-codex.md` - `.opencode/agents/ca-implementer-opus.md` ### Expected Impact - **Prevents domain model mismatches**: Implementers verify fields exist before referencing them - **Catches missing fields early**: Instead of discovering mismatches in holistic review, they're caught during implementation - **Reduces Pyright errors**: Type errors from non-existent fields are eliminated at the source - **Saves escalation cycles**: Fewer quality gate failures means fewer escalation attempts in the subtask loop ### Risk Assessment - **Very low risk**: This adds verification guidance without changing any implementation logic or permissions. - **Potential downside**: Slightly more time spent reading model definitions before implementing. However, this is far less time than the escalation cycles wasted on Pyright failures. - **No behavioral change**: Implementers already have "Read any existing code in the relevant modules" as step 2. This makes that guidance more specific and actionable. --- *This is a proposal from the agent evolver. A human must approve this issue before the change will be implemented. To approve: remove the `needs feedback` label, add `State/Verified`, or comment with approval.* --- **Automated by CleverAgents Bot** Supervisor: Agent Evolver | Agent: ca-agent-evolver

freemo referenced this issue

2026-04-05 02:35:30 +00:00

[Automated] Product Build Session State - v3.7.0 Completion #1530

freemo commented

2026-04-05 02:51:33 +00:00

Author

Owner

approved

freemo referenced this issue from a commit

2026-04-05 03:33:06 +00:00

chore(agents): improve implementer agents — verify domain model fields before referencing

freemo referenced this issue from a pull request that will close it,

2026-04-05 03:35:27 +00:00

chore(agents): improve implementer agents — verify domain model fields before referencing #3007

freemo referenced this issue

2026-04-05 03:39:48 +00:00

[Automated] Product Build Session State - v3.7.0 Completion #1530

freemo referenced this issue

2026-04-05 04:14:37 +00:00

[Automated] Product Build Session State - v3.7.0 Completion #1530

freemo commented

2026-04-05 04:34:41 +00:00

Author

Owner

PR #3007 reviewed, approved, and merged.

The implementer agent improvement has been applied to all three agent definitions (ca-implementer-sonnet, ca-implementer-codex, ca-implementer-opus). The new domain model verification step is now active.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3007 reviewed, approved, and merged. The implementer agent improvement has been applied to all three agent definitions (`ca-implementer-sonnet`, `ca-implementer-codex`, `ca-implementer-opus`). The new domain model verification step is now active. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo closed this issue

2026-04-05 04:35:21 +00:00

freemo referenced this issue

2026-04-05 05:29:57 +00:00

chore(agents): improve implementer agents — verify domain model fields before referencing #3007

freemo commented

2026-04-05 05:36:46 +00:00

Author

Owner

PR #3007 reviewed, approved, and merged.

The domain model verification step has been added to all three implementer agents (ca-implementer-sonnet, ca-implementer-codex, ca-implementer-opus). This should prevent the class of Pyright type errors caused by referencing non-existent domain model fields.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3007 reviewed, approved, and merged. The domain model verification step has been added to all three implementer agents (`ca-implementer-sonnet`, `ca-implementer-codex`, `ca-implementer-opus`). This should prevent the class of Pyright type errors caused by referencing non-existent domain model fields. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this issue

2026-04-05 07:27:26 +00:00

chore(agents): improve implementer agents — verify domain model fields before referencing #3007

freemo commented

2026-04-05 07:31:17 +00:00

Author

Owner

PR #3007 reviewed, approved, and merged.

The domain model verification step has been added to all three implementer agents (ca-implementer-sonnet, ca-implementer-codex, ca-implementer-opus). All CI checks passed. Issue was already in State/Completed and closed.

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3007 reviewed, approved, and merged. The domain model verification step has been added to all three implementer agents (`ca-implementer-sonnet`, `ca-implementer-codex`, `ca-implementer-opus`). All CI checks passed. Issue was already in `State/Completed` and closed. --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer

freemo referenced this issue from a commit

2026-04-05 21:15:02 +00:00

chore(agents): improve implementer agents — verify domain model fields before referencing