---

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>