Add readItem() / CosmosItemResponse unwrapping guidance to sdk-java-content-response rule

[Copilot]

~30% of raw-SDK Java runs treat CosmosItemResponse<T> as T directly on readItem() calls, missing .getItem() — causing compilation failures. The existing rule only covered write-side (contentResponseOnWriteEnabled); this extends it to cover read-side unwrapping.

Rule changes (sdk-java-content-response.md)

• New leading section with incorrect/correct examples for both sync and async readItem() unwrapping
• Broadened title/tags/impact to reflect full read+write scope
• Updated Key Points to list all CRUD operations that return CosmosItemResponse<T>

Key pattern added

// ❌ readItem returns CosmosItemResponse<Player>, NOT Player
Player player = container.readItem(playerId, new PartitionKey(playerId), Player.class);

// ✅ Unwrap with getItem()
CosmosItemResponse<Player> response = container.readItem(
    playerId, new PartitionKey(playerId), Player.class);
Player player = response.getItem();

// ✅ Async: map to unwrap
Mono<Player> player = container.readItem(playerId, new PartitionKey(playerId), Player.class)
    .map(response -> response.getItem());

Other files

• AGENTS.md — recompiled

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Java Gaming Leaderboard — readItem() return type not unwrapped — CosmosItemResponse treated as entity in ~30% of raw-SDK runs (P01, P03)</issue_title>
<issue_description># readItem() return type not unwrapped — CosmosItemResponse treated as entity in ~30% of raw-SDK runs (P01, P03)

Field	Value
GitHub	#27
Type	Rule Enhancement
Target Rule	sdk-java-content-response
Action	Add readItem() / CosmosItemResponse<T> unwrapping guidance for Java SDK
Severity	MEDIUM
Hit Rate	~30% of raw-SDK runs
Profiles	P01/R02, P01/R04, P03/R03 (AK)
Labels	enhancement, SCOPE, agent-kit, rule:sdk

---

Summary

Code treats CosmosItemResponse<T> as T directly — missing the .getItem() call to extract the actual entity value. This causes type mismatch compilation errors in every readItem() call site.

Evidence

Affected: P01/R02, P01/R04, P03/R03 (~30% of raw-SDK runs)

Incorrect Pattern

public Mono<Optional<PlayerProfile>> readProfile(String id, String partitionKey) {
    return container.readItem(id, new PartitionKey(partitionKey),
                              CosmosItemRequestOptions.class, PlayerProfile.class)
        .map(Optional::of);
    // BUG: response is CosmosItemResponse<PlayerProfile>, not PlayerProfile
}
// Compile error: incompatible types

Correct Pattern

public Mono<Optional<PlayerProfile>> readProfile(String id, String partitionKey) {
    return container.readItem(id, new PartitionKey(partitionKey), PlayerProfile.class)
        .map(CosmosItemResponse::getItem)   // Unwrap the response
        .map(Optional::of);
}

Impact

• Compilation failure: every readItem() call site fails to compile
• Common pattern: affects any run using raw Cosmos SDK (non-Spring-Data) for point reads

Recommended Fix

Add to SDK rules:

Always unwrap CosmosItemResponse<T> with .getItem().

readItem(), createItem(), replaceItem(), and upsertItem() return CosmosItemResponse<T>, not T directly. Call .getItem() to extract the entity, .getStatusCode() for HTTP status, and .getRequestCharge() for RU cost.
</issue_description>

<agent_instructions>Review the issue, analyse how agent skills are organised in this repo, and propose a fix in a draft PR based on the recommendations in the issue. </agent_instructions>

Comments on the Issue (you are @copilot in this section)

@jaydestro ## SCOPE Reclassification Update

Type: Rule Enhancement (not new rule)
Target Rule: sdk-java-content-response
Action: Add readItem() / CosmosItemResponse<T> unwrapping guidance. Code treats the response wrapper as the entity directly — missing .getItem() call causes compilation failures at every readItem() call site.

Rationale: Merges with local issue #5 (reactive NPE from same root cause — missing .getItem() unwrap). The rule already covers content-on-write; extending to cover content-on-read is a natural fit.

Hit Rate: ~30% of raw-SDK runs (P01/R02, P01/R04, P03/R03)</comment_new>

• Fixes Java Gaming Leaderboard — readItem() return type not unwrapped — CosmosItemResponse treated as entity in ~30% of raw-SDK runs (P01, P03) #27

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[TheovanKraay]

@copilot we don't need to update the improvements log, that is only for changes implemented via the testing frameworks within this repo. These are separately analysed changes via SCOPE testing (a separate tool). remove the log updates.

[Copilot]

@copilot we don't need to update the improvements log, that is only for changes implemented via the testing frameworks within this repo. These are separately analysed changes via SCOPE...

Reverted the testing-v2/IMPROVEMENTS-LOG.md changes in d0cbf8b.