Round 23 — Code Correctness, Coverage Gaps & FLE Skill

Problem Statement

Three categories of issues identified in a deep audit:

Code correctness bugs — 8 code examples in new testing-patterns-* skills and existing skills that won't compile or run, plus 1 missing ctx.QueryAsync() in transactions-dotnet.
Coverage gaps — KV Range Scan missing from 6 sdk-patterns-* skills; analytics write-back body content missing from 7 analytics skills; broken file reference; false statement about PHP/Ruby testcontainers support.
New skill coverage — Field-Level Encryption (FLE) has zero coverage despite being supported by 6 SDKs. Requires 1 concept skill + 9 language skills (6 full, 3 "not supported" stubs).
Shared file completeness — shared/server/durability.md and shared/server/subdocument.md missing examples for 5–6 languages.

Findings & Requirements

Group A — Critical Code Bugs

A1 — `testing-patterns-rust`: `result.content()` on `GetResult` (won't compile)

File: skills/testing-patterns-rust/SKILL.md line 83

let doc: serde_json::Value = result.content().unwrap();  // WRONG

GetResult has content_as::<T>(), not content(). Fix:

let doc: serde_json::Value = result.content_as().unwrap();

A2 — `testing-patterns-rust`: `testcontainers::clients::Cli` removed in v0.15

File: skills/testing-patterns-rust/SKILL.md lines 54–66 Cli::default() + docker.run() was removed in testcontainers 0.15. Fix to use AsyncRunner:

testcontainers = "0.20"
testcontainers-modules = { version = "0.5", features = ["couchbase"] }

use testcontainers::runners::AsyncRunner;
let node = Couchbase::default().start().await.unwrap();
let port = node.get_host_port_ipv4(11210).await.unwrap();

A3 — `testing-patterns-rust`: wrong `ClusterOptions` API

File: skills/testing-patterns-rust/SKILL.md line 61 Uses ClusterOptions::default().authenticator(PasswordAuthenticator::new(...)) — this builder method doesn't exist. Correct API (from server-connection-rust):

use couchbase::authenticator::{Authenticator, PasswordAuthenticator};
use couchbase::options::cluster_options::ClusterOptions;
ClusterOptions::new(Authenticator::PasswordAuthenticator(
    PasswordAuthenticator::new("Administrator", "password")
))

A4 — `testing-patterns-php`: `ClusterOptions::build()` doesn't exist

File: skills/testing-patterns-php/SKILL.md line 76 ClusterOptions::build() is not a PHP SDK method. Correct API (from server-connection-php):

$options = new \Couchbase\ClusterOptions();
$options->credentials('Administrator', 'password');
new \Couchbase\Cluster('couchbase://localhost:' . $port, $options);

A5 — `testing-patterns-scala`: `ClusterOptions.create()` is Java API

File: skills/testing-patterns-scala/SKILL.md line 74 ClusterOptions.create() is the Java SDK factory. Scala uses the case class constructor (from server-connection-scala):

ClusterOptions(PasswordAuthenticator("Administrator", "password"))

A6 — `testing-patterns-ruby`: `Couchbase::Options::Cluster()` is invalid Ruby

File: skills/testing-patterns-ruby/SKILL.md line 66 Function-call syntax is invalid. Correct API (from server-connection-ruby):

options = Couchbase::Options::Cluster.new
options.authenticate('Administrator', 'password')
Couchbase::Cluster.connect("couchbase://localhost:#{port}", options)

A7 — `search-scala`: `Seq[Double]` + `VectorQuery.create()` — wrong type and wrong API

File: skills/search-scala/SKILL.md lines 99, 102, 115, 119

Seq[Double] should be Array[Float]
VectorQuery.create() is the Java factory; Scala uses VectorQuery("field", vector) Fix (matching search-scala/examples/examples.md):

val queryVector: Array[Float] = Array(0.1f, 0.2f /*, ... 1536 dims */)
VectorQuery("embedding_field", queryVector).numCandidates(3)

A8 — `sdk-patterns-rust`: `DecrementOptions` used but not imported

File: skills/sdk-patterns-rust/SKILL.md line 114 DecrementOptions is used but only IncrementOptions is imported. Add:

use couchbase::options::kv_options::{IncrementOptions, DecrementOptions};

A9 — `transactions-dotnet`: missing `ctx.QueryAsync()`, shows wrong SQL syntax

File: skills/transactions-dotnet/SKILL.md — ## SQL++ Transactions section The section shows raw BEGIN TRANSACTION; ... COMMIT TRANSACTION; SQL — a different mechanism from the SDK transaction lambda. Replace with ctx.QueryAsync() matching the pattern in Python/Go:

await cluster.Transactions().RunAsync(async (ctx) => {
    await ctx.QueryAsync(
        "UPDATE `myapp`._default.accounts SET balance = balance - $1 WHERE META().id = $2",
        new TransactionQueryOptions().Parameter(100).Parameter("acct_alice")
    );
    await ctx.QueryAsync(
        "UPDATE `myapp`._default.accounts SET balance = balance + $1 WHERE META().id = $2",
        new TransactionQueryOptions().Parameter(100).Parameter("acct_bob")
    );
});

Group B — Content Correctness

B1 — `sdk-patterns-python`: broken reference to non-existent file

File: skills/sdk-patterns-python/SKILL.md line 112

See [references/bulk-ops.md](references/bulk-ops.md) for chunked bulk get and KV range scan.

references/bulk-ops.md does not exist. Remove the broken link; the sentence can stand alone or reference sdk-patterns-go for the range scan pattern.

B2 — `testing-patterns/SKILL.md`: false statement about PHP/Ruby testcontainers

File: skills/testing-patterns/SKILL.md line 62

For CI pipelines or languages without testcontainers support (PHP, Ruby):

Both testing-patterns-php and testing-patterns-ruby have full testcontainers sections. Change to:

For CI pipelines or when a real cluster is preferred over testcontainers:

Group C — KV Range Scan Coverage

C1 — Add `## KV Range Scan` to 6 sdk-patterns-* skills

KV Range Scan is supported by Java, .NET, Node.js, Scala, PHP, Ruby (Server 7.6+) but none of these skills have a section for it. Add a ## KV Range Scan section to each, using the Go skill as the reference pattern. Each section should show:

Prefix scan (all keys starting with a prefix)
Range scan (lexicographic range)
Note: requires Server 7.6+; operates on key order, not field values

Affected skills: sdk-patterns-java, sdk-patterns-dotnet, sdk-patterns-nodejs, sdk-patterns-scala, sdk-patterns-php, sdk-patterns-ruby

API names per language:

Java: collection.scan(new PrefixScan("user::"), ScanOptions.scanOptions())
.NET: collection.ScanAsync(new PrefixScan("user::"), ScanOptions.Default)
Node.js: collection.scan(new PrefixScan("user::"), { idsOnly: false })
Scala: collection.scan(PrefixScan("user::"), ScanOptions())
PHP: $collection->scan(new PrefixScan("user::"), new ScanOptions())
Ruby: collection.scan(Couchbase::PrefixScan.new("user::"), Couchbase::Options::Scan.new)

Also add KV range scan discovery triggers for these 6 languages to discovery.yaml.

Group D — Analytics Write-Back Body Content

D1 — Add `## Writing Results Back` to 7 analytics skills

All 7 analytics skills (python, java, go, dotnet, nodejs, scala, php) have a routing edge to transactions-<lang> but no body content explaining the pattern before routing. Add a ## Writing Results Back section to each, showing:

Brief explanation: use transactions for atomic write-back, or individual KV upserts for non-atomic
A short code example (upsert loop, matching the language)
Link to transactions-<lang> for the full transactional pattern

Group E — Field-Level Encryption (FLE) Skills

E1 — Create `skills/fle/SKILL.md` (concept skill)

Covers:

What FLE is: client-side encryption of specific document fields before writing to Couchbase
Supported SDKs: Python, Java, Go, .NET, Node.js, PHP
Not supported: Rust SDK 1.0, Scala, Ruby SDK 3.x
Key concepts: CryptoManager, KeyProvider, annotated fields, EncryptedField
When to use vs server-side encryption at rest
Link to language-specific skills

E2 — Create 9 language FLE skills

skills/fle-python/SKILL.md — full content
skills/fle-java/SKILL.md — full content
skills/fle-go/SKILL.md — full content
skills/fle-dotnet/SKILL.md — full content
skills/fle-nodejs/SKILL.md — full content
skills/fle-php/SKILL.md — full content
skills/fle-rust/SKILL.md — "not supported" stub (Rust SDK 1.0)
skills/fle-scala/SKILL.md — "not supported" stub (Scala SDK)
skills/fle-ruby/SKILL.md — "not supported" stub (Ruby SDK 3.x)

Each supported language skill covers:

Dependencies / package setup
CryptoManager + KeyProvider setup
Encrypting a field on write (upsert)
Decrypting on read (get)
Annotating model classes (where applicable)

Each unsupported stub covers:

Clear statement that FLE is not supported
Alternative: server-side encryption at rest (available in Server 8.x for all SDKs)
Link to security skill

Add discovery.yaml entries and routing.yaml edges for all 10 skills.

Group F — Shared File Completeness

F1 — `shared/server/durability.md`: add .NET, Rust, Scala, PHP, Ruby examples

Currently has Python, Java, Node.js, Go. Add sections for the 5 missing languages showing the durability option in a upsert/replace call.

F2 — `shared/server/subdocument.md`: add Python, .NET, Rust, Scala, PHP, Ruby examples

Currently has Node.js, Java, Go in the Language Examples section. Add the 6 missing languages.

Acceptance Criteria

bash scripts/validate-skills.sh exits 0 with 0 failures and 0 warnings.
All 9 code bugs (A1–A9) are fixed — no non-compiling examples.
sdk-patterns-{java,dotnet,nodejs,scala,php,ruby} each have a ## KV Range Scan section.
analytics-{python,java,go,dotnet,nodejs,scala,php} each have a ## Writing Results Back section with a code example.
skills/fle/SKILL.md exists with concept content.
9 skills/fle-{lang}/SKILL.md files exist (6 full, 3 stubs).
shared/server/durability.md has examples for all 9 languages.
shared/server/subdocument.md has examples for all 9 languages.
testing-patterns/SKILL.md no longer falsely claims PHP/Ruby lack testcontainers support.
sdk-patterns-python/SKILL.md has no broken file reference.

Implementation Steps

Fix A1–A3: testing-patterns-rust — fix content_as, testcontainers API, ClusterOptions API
Fix A4: testing-patterns-php — fix ClusterOptions::build()
Fix A5: testing-patterns-scala — fix ClusterOptions.create()
Fix A6: testing-patterns-ruby — fix Couchbase::Options::Cluster() syntax
Fix A7: search-scala — fix Seq[Double] → Array[Float] and VectorQuery.create() → VectorQuery()
Fix A8: sdk-patterns-rust — add DecrementOptions import
Fix A9: transactions-dotnet — replace SQL syntax with ctx.QueryAsync() example
Fix B1: sdk-patterns-python — remove broken references/bulk-ops.md link
Fix B2: testing-patterns concept skill — fix false PHP/Ruby testcontainers statement
Add KV Range Scan to 6 sdk-patterns- skills + discovery triggers* (Group C)
Add Writing Results Back to 7 analytics skills (Group D)
Create FLE concept skill + 9 language skills + discovery.yaml + routing.yaml (Group E)
Run sync-handoffs.sh --apply
Add missing language examples to shared/server/durability.md (Group F1)
Add missing language examples to shared/server/subdocument.md (Group F2)
Run validate-skills.sh — confirm 0 failures, 0 warnings

Round 22 — Routing Correctness & Quality Fixes (archived)

Problem Statement

Seven issues were identified in a PM review of the agent skill pack. They fall into three categories:

Correctness bugs — routing sends users to wrong skills or skills lack body content explaining SDK limitations, causing AI agents to give wrong answers (e.g. Rust/Ruby users receiving Python transaction code).
Missing routing edges — 8 of 9 server-querying-* skills lack a direct path to columnar-analytics, forcing a detour through deprecated skills on Server 8.x.
Quality issues — mid-list blank lines in discovery.yaml trigger lists, a double --- in search-concepts/SKILL.md, and ambiguous use_when wording in analytics-* skills.

Findings & Requirements

Finding 1 — Wrong routing for Rust/Ruby transaction queries (P0)

Affected files: routing.yaml, skills/server-querying-rust/SKILL.md, skills/server-querying-ruby/SKILL.md

Problem: Both server-querying-rust and server-querying-ruby have a routing edge:

condition: user asks about transactions or ACID operations
to: error-handling

error-handling then tries to hand off to transactions-<lang>, but neither transactions-rust nor transactions-ruby exist. Rust SDK 1.0 and Ruby SDK 3.x do not support distributed ACID transactions (confirmed in references/sdk-feature-matrix.md).

Requirements:

Remove both server-querying-rust → error-handling and server-querying-ruby → error-handling routing edges (the transaction-condition ones).
Add a ## Transactions section to skills/server-querying-rust/SKILL.md body explaining:
- Rust SDK 1.0 does not support distributed ACID transactions.
- Recommended alternative: optimistic locking with CAS (link to sdk-patterns-rust).
Add a ## Transactions section to skills/server-querying-ruby/SKILL.md body explaining:
- Ruby SDK 3.x does not support distributed ACID transactions.
- Recommended alternative: optimistic locking with CAS (link to sdk-patterns-ruby).
Remove the two routing edges from the cycle allowlist in scripts/validate-skills.sh if they appear there (stale-entry check would fail otherwise).
Run sync-handoffs.sh --apply after routing changes.

Finding 2 — `server-querying-*` missing `columnar-analytics` edge for 8 languages (P1)

Affected file: routing.yaml

Problem: Only server-querying-python has a direct edge to columnar-analytics. The other 8 languages route through the deprecated analytics-<lang> skill (deprecated since Server 8.0) before reaching columnar-analytics.

Requirements:

Add server-querying-<lang> → columnar-analytics edges for: java, go, dotnet, nodejs, rust, scala, php, ruby.
Use the same condition as Python: "user is on Server 8.x and asks about columnar or OLAP queries".
Run sync-handoffs.sh --apply after routing changes.

Finding 3 — `server-connection-rust` and `server-connection-ruby` lack body explanation for unsupported transactions (P1)

Affected files: skills/server-connection-rust/SKILL.md, skills/server-connection-ruby/SKILL.md

Problem: discovery.yaml routes cold-start queries like "transactions Rust Couchbase" to server-connection-rust. The limitation is only in the compatibility frontmatter field — not in the skill body. An AI agent loading the skill may not surface the frontmatter note.

Requirements:

Add a ## Transactions section to skills/server-connection-rust/SKILL.md body:
- State that Rust SDK 1.0 does not support distributed ACID transactions.
- Suggest CAS-based optimistic locking as the alternative (brief inline note + link to sdk-patterns-rust).
Add a ## Transactions section to skills/server-connection-ruby/SKILL.md body:
- State that Ruby SDK 3.x does not support distributed ACID transactions.
- Suggest CAS-based optimistic locking as the alternative (brief inline note + link to sdk-patterns-ruby).

Finding 4 — `analytics-ruby` missing explanation for transactional write-back (P2)

Affected file: skills/analytics-ruby/SKILL.md

Problem: All other analytics-* skills have a routing edge and body content for "write results back to operational collections transactionally." analytics-ruby has neither — Ruby SDK 3.x has no transactions. A user asking about transactional write-back from analytics gets no guidance.

Requirements:

Add a ## Writing Results Back section to skills/analytics-ruby/SKILL.md:
- Ruby SDK 3.x does not support distributed ACID transactions.
- To write analytics results back to the operational store, use individual KV upsert operations — see sdk-patterns-ruby.

Finding 5 — Blank lines inside trigger lists in `discovery.yaml` (P3)

Affected file: discovery.yaml

Problem: The 5 transactions-* skills (Python, Java, Go, .NET, Node.js) have genuine mid-list blank lines splitting their trigger sequences. All other skill blocks have end-of-block blank lines (harmless style). The user has requested removing all blank lines inside any trigger list for safety with strict parsers.

Requirements:

Remove all blank lines that appear between trigger items (between - "..." lines within a triggers: block) across all skills in discovery.yaml.
End-of-block blank lines (between the last trigger item and the next - skill: entry) are also to be removed.
The blank line separating - skill: entries from each other should be preserved.

Finding 6 — Double `---` in `search-concepts/SKILL.md` (P3)

Affected file: skills/search-concepts/SKILL.md

Problem: Lines 38–40 contain two consecutive --- horizontal rules between the shared-reference note and the ## RAG Pipeline section. Some parsers treat --- as a YAML frontmatter delimiter and may truncate the skill body.

Requirements:

Remove one of the two consecutive --- lines (keep one as a section separator).

Finding 7 — `analytics-*` `use_when` version boundary is ambiguous (P3)

Affected file: discovery.yaml

Problem: All 8 analytics-* skills say "writing <Lang> Analytics queries against Couchbase Server 7.x and earlier". Users on Server 7.6 (current LTS) may not know whether to use analytics-* or columnar-analytics.

Requirements:

Change all 8 analytics-* use_when values to: "writing <Lang> Analytics queries on Couchbase Server 7.x (CBAS — not available on Server 8.x)".
The language name in each entry stays as-is (Python, Java, Go, .NET, Node.js, Scala, Ruby, PHP).

Acceptance Criteria

bash scripts/validate-skills.sh exits 0 with 0 failures and 0 warnings.
server-querying-rust and server-querying-ruby have no routing edge to error-handling for transaction queries.
Both server-querying-rust and server-querying-ruby SKILL.md bodies contain a ## Transactions section explaining the limitation and suggesting CAS.
Both server-connection-rust and server-connection-ruby SKILL.md bodies contain a ## Transactions section.
analytics-ruby SKILL.md body contains a ## Writing Results Back section explaining no transaction support and suggesting KV upserts.
All 8 server-querying-<lang> skills (excluding Python) have a columnar-analytics routing edge.
No blank lines appear between trigger items in any triggers: block in discovery.yaml.
skills/search-concepts/SKILL.md has only one --- between the shared-reference note and ## RAG Pipeline.
All 8 analytics-* use_when values contain "(CBAS — not available on Server 8.x)".

Implementation Steps

Fix routing.yaml — remove wrong Rust/Ruby transaction edges (Finding 1)
Fix routing.yaml — add columnar-analytics edges for 8 languages (Finding 2)
Run sync-handoffs.sh --apply
Fix validate-skills.sh allowlist — check for and remove any stale cycle entries from deleted edges
Add ## Transactions section to server-querying-rust/SKILL.md (Finding 1)
Add ## Transactions section to server-querying-ruby/SKILL.md (Finding 1)
Add ## Transactions section to server-connection-rust/SKILL.md (Finding 3)
Add ## Transactions section to server-connection-ruby/SKILL.md (Finding 3)
Add ## Writing Results Back section to analytics-ruby/SKILL.md (Finding 4)
Fix discovery.yaml — remove blank lines inside trigger lists (Finding 5)
Fix search-concepts/SKILL.md — remove duplicate --- (Finding 6)
Fix discovery.yaml — update analytics- use_when wording* (Finding 7)
Run validate-skills.sh — confirm 0 failures, 0 warnings

Round 21 Spec — PM Feedback Fixes (archived)

Problem Statement

Product feedback identified 8 structural and quality issues with the repository as consumed by AI code assistants. This spec covers all 8. Finding 2 (routing consumption contract) is explicitly skipped — it's the platform's responsibility.

Issue 1 — Implement `eval.sh --execute` via Anthropic API

Finding: eval.sh --execute exits with an error. The eval contract (expect/reject/code_block fields) is defined but never executed.

Decision: Wire --execute to the Anthropic API via curl. Requires ANTHROPIC_API_KEY env var.

Requirements

eval.sh --execute --model MODEL calls api.anthropic.com/v1/messages for each eval case
System prompt: load the skill's SKILL.md content as the system message
User message: the case's input field
Assertions run against the response text:
- All expect terms must appear (case-insensitive substring match)
- No reject terms may appear (case-insensitive substring match)
- If code_block: LANG is set, a fenced code block of that language must appear (```LANG)
- If threshold is set, only that many expect terms need to match (not all)
Output per case: PASS or FAIL with which terms failed
Exit code: 0 if all cases pass, 1 if any fail
--skill SKILL flag limits to one skill (already implemented for dry-run)
--model MODEL flag (required for --execute); default suggestion: claude-3-5-haiku-20241022
Clear error if ANTHROPIC_API_KEY is not set

Acceptance criteria

eval.sh --execute --model claude-3-5-haiku-20241022 --skill getting-started runs 3 cases and reports PASS/FAIL
eval.sh --dry-run still works unchanged
Missing ANTHROPIC_API_KEY prints a clear error and exits 2
Script is self-contained (bash + curl only, no Python/Node deps)

Issue 2 — Skipped (routing consumption contract is platform's responsibility)

Issue 3 — Validator: warn when language-family skills are missing canonical sections

Finding: No automated check that all 9 language variants in a family cover the same sections. transactions-python/go/dotnet are missing ctx.query() examples; section names vary across the matrix.

Decision: Warn only (don't fail). Define canonical required-section lists per family in the validator.

Required sections per family (derived from current majority pattern)

transactions-* (7 skills: python, java, go, dotnet, nodejs, scala, php):

## Bank Transfer Example OR ## Basic Transaction (either accepted)
## SQL++ (prefix match — covers "SQL++ Transactions", "SQL++ Inside a Transaction")
## Error Handling
## Design Rules

server-connection-* (9 skills):

## The One Rule OR ## Connect (either accepted — Rust/Scala/PHP/Ruby use Connect)
## Singleton (prefix match)
## Sub-Document
## Durability OR ## Error Handling (either accepted — Rust/PHP/Ruby use Error Handling)

sdk-patterns-* (9 skills):

## CAS
## Bulk Operations
## Atomic Counters
## Error Handling

Acceptance criteria

validate-skills.sh emits a warn (not fail) for each missing canonical section
All 90 skills currently pass with 0 failures after the check is added
The check is implemented as a new validate_section_coverage() function called from the main loop

Issue 4 — Add `ctx.query()` to `transactions-python` and `transactions-go`

Finding: transactions-python and transactions-go have ## SQL++ Transactions sections but show only bare BEGIN TRANSACTION SQL — no ctx.query() SDK call inside the lambda. Java, Node.js, Scala, PHP all have it.

Fix: Add ctx.query() example to the SQL++ section in both files, matching the pattern already in transactions-java and transactions-nodejs.

Acceptance criteria

transactions-python/SKILL.md SQL++ section shows ctx.query(...) inside the lambda
transactions-go/SKILL.md SQL++ section shows ctx.Query(...) inside the lambda
Both still show the bare BEGIN TRANSACTION alternative

Issue 5 — Add per-language error reference to each `server-connection-*` skill

Finding: error-handling uses Java-style exception names and JavaScript code. A Go developer gets DocumentNotFoundException (Java) instead of gocb.ErrDocumentNotFound.

Decision: Add a ## Common Errors section to each of the 9 server-connection-* skills listing the language-specific error class names for the 6 most common errors.

The 6 errors to cover (per language)

Concept	Python	Java	Go	.NET	Node.js	Rust	Scala	PHP	Ruby
Doc not found	`DocumentNotFoundException`	`DocumentNotFoundException`	`gocb.ErrDocumentNotFound`	`DocumentNotFoundException`	`DocumentNotFoundError`	`ErrorKind::KeyNotFound`	`DocumentNotFoundException`	`DocumentNotFoundException`	`DocumentNotFoundException`
Doc exists	`DocumentExistsException`	`DocumentExistsException`	`gocb.ErrDocumentExists`	`DocumentExistsException`	`DocumentExistsError`	`ErrorKind::KeyExists`	`DocumentExistsException`	`DocumentExistsException`	`DocumentExistsException`
CAS mismatch	`CasMismatchException`	`CasMismatchException`	`gocb.ErrCasMismatch`	`CasMismatchException`	`CasMismatchError`	`ErrorKind::CasMismatch`	`CasMismatchException`	`CasMismatchException`	`CasMismatchException`
Unambiguous timeout	`UnambiguousTimeoutException`	`UnambiguousTimeoutException`	`gocb.ErrUnambiguousTimeout`	`UnambiguousTimeoutException`	`UnambiguousTimeoutError`	`ErrorKind::UnambiguousTimeout`	`UnambiguousTimeoutException`	`UnambiguousTimeoutException`	`UnambiguousTimeoutException`
Ambiguous timeout	`AmbiguousTimeoutException`	`AmbiguousTimeoutException`	`gocb.ErrAmbiguousTimeout`	`AmbiguousTimeoutException`	`AmbiguousTimeoutError`	`ErrorKind::AmbiguousTimeout`	`AmbiguousTimeoutException`	`AmbiguousTimeoutException`	`AmbiguousTimeoutException`
Temporary failure	`TemporaryFailureException`	`TemporaryFailureException`	`gocb.ErrTemporaryFailure`	`TemporaryFailureException`	`TemporaryFailureError`	`ErrorKind::TemporaryFailure`	`TemporaryFailureException`	`TemporaryFailureException`	`TemporaryFailureException`

Each server-connection-* skill gets a ## Common Errors section with:

A table of the 6 errors with their language-specific class name, cause, and whether it's safe to retry
A brief code example showing try/catch for the most common case (DocumentNotFoundException)

Acceptance criteria

All 9 server-connection-* skills have a ## Common Errors section
Each section uses the correct language-specific error class names
validate-skills.sh passes with 0 failures

Issue 6 — Split `testing-patterns` into 9 language-specific skills

Finding: testing-patterns is a single skill covering all 9 languages, inconsistent with the rest of the matrix (transactions-, search-, etc. are all per-language).

Decision: Split into testing-patterns-python, testing-patterns-java, testing-patterns-go, testing-patterns-dotnet, testing-patterns-nodejs, testing-patterns-rust, testing-patterns-scala, testing-patterns-php, testing-patterns-ruby.

Keep testing-patterns as a concept/entry-point skill (like search-concepts) that explains the strategies and routes to the language-specific skills.

Structure

testing-patterns (concept skill — keep, slim down):

Remove all language-specific code
Keep: strategy overview (unit vs integration), test data management, scope/collection isolation pattern, Docker Compose CI setup
Add variant handoff to all 9 language-specific skills
Update references/mock-examples.md → move to shared/server/testing-mock-examples.md (referenced by all 9 language skills)

testing-patterns-LANG (9 new skills):

Frontmatter: name, summary, compatibility (SDK version)
## Unit Testing — mock example for that language (from references/mock-examples.md)
## Integration Testing — testcontainers example for that language
## Common Errors in Tests — what errors to expect and how to handle them in tests
Handoff back to testing-patterns (concept) and to server-connection-LANG
examples/examples.md with 3 cases: unit mock, integration test, test isolation

shared/server/testing-mock-examples.md:

Move content from skills/testing-patterns/references/mock-examples.md
Referenced by all 9 language skills

discovery.yaml

testing-patterns: priority: primary, existing triggers
Each testing-patterns-LANG: priority: secondary, language-specific triggers (e.g. "unit test Couchbase Python", "mock Couchbase collection Python", "pytest Couchbase")

routing.yaml

testing-patterns → testing-patterns-LANG (variant edges, one per language)
Each testing-patterns-LANG → testing-patterns (topic: "user asks about testing concepts")
Each testing-patterns-LANG → server-connection-LANG (topic: "user asks about connection setup")
getting-started → testing-patterns (already exists)
local-dev-setup → testing-patterns (already exists)

Acceptance criteria

9 new skill directories created, each passing validate-skills.sh
testing-patterns concept skill slimmed to <150 lines, no language-specific code
shared/server/testing-mock-examples.md exists and is referenced by all 9 language skills
discovery.yaml has entries for all 10 skills (1 concept + 9 language)
validate-skills.sh passes with 0 failures and 0 warnings
scripts/sync-handoffs.sh --apply runs clean

Issue 7 — Validator: add `last_verified` staleness check on the field value (not git date)

Finding: All 90 skills have last_verified: "2026-05" set in bulk. The existing staleness check uses git commit date, not the last_verified field value. The field is meaningless if it's never checked.

Status check: The validator already checks last_verified at line 148 — verify what it actually does and whether it's sufficient. If it already warns on stale last_verified field values, this issue may be partially resolved.

Fix: Ensure the validator:

Warns if last_verified is missing
Warns if last_verified value is >6 months old (parse YYYY-MM, compare to today)
The existing git-commit-date check (180 days) is separate and complementary — keep both

Acceptance criteria

Validator warns if last_verified: "2024-01" (>6 months old)
Validator does not warn for last_verified: "2026-05" (current)
Both checks (field value + git commit date) are active

Issue 8 — Fix `analytics-*` `use_when` wording ("legacy CBAS" is premature)

Finding: All 8 analytics-* language skills have use_when: "writing X Analytics queries against Couchbase Server 6.x–7.x (legacy CBAS)". Server 7.6 is current LTS — calling it "legacy" is wrong.

Fix: Update all 8 use_when entries in discovery.yaml to remove "legacy CBAS" and replace with "for Server 7.x and earlier".

Also update README.md which says > Rust SDK 1.0 does not support the Analytics service. Skills below target Server 6.x–7.x (legacy CBAS).

Acceptance criteria

All 8 analytics-* use_when entries say "for Server 7.x and earlier" (not "legacy CBAS")
README.md analytics note updated
validate-skills.sh passes with 0 failures

Implementation Order

Issue 8 — discovery.yaml + README.md wording fix (2 minutes, zero risk)
Issue 4 — Add ctx.query() to transactions-python and transactions-go
Issue 7 — Verify/fix last_verified field staleness check in validator
Issue 3 — Add section-coverage validator check
Issue 5 — Add ## Common Errors to all 9 server-connection-* skills
Issue 6 — Split testing-patterns into 9 language skills + concept skill
Issue 1 — Implement eval.sh --execute via Anthropic API curl
Validate — bash scripts/validate-skills.sh, confirm 0 failures 0 warnings

FilesExpand file tree

spec.md

Latest commit

History

spec.md

File metadata and controls

Round 23 — Code Correctness, Coverage Gaps & FLE Skill

Problem Statement

Findings & Requirements

Group A — Critical Code Bugs

A1 — testing-patterns-rust: result.content() on GetResult (won't compile)

A2 — testing-patterns-rust: testcontainers::clients::Cli removed in v0.15

A3 — testing-patterns-rust: wrong ClusterOptions API

A4 — testing-patterns-php: ClusterOptions::build() doesn't exist

A5 — testing-patterns-scala: ClusterOptions.create() is Java API

A6 — testing-patterns-ruby: Couchbase::Options::Cluster() is invalid Ruby

A7 — search-scala: Seq[Double] + VectorQuery.create() — wrong type and wrong API

A8 — sdk-patterns-rust: DecrementOptions used but not imported

A9 — transactions-dotnet: missing ctx.QueryAsync(), shows wrong SQL syntax

Group B — Content Correctness

B1 — sdk-patterns-python: broken reference to non-existent file

B2 — testing-patterns/SKILL.md: false statement about PHP/Ruby testcontainers

Group C — KV Range Scan Coverage

C1 — Add ## KV Range Scan to 6 sdk-patterns-* skills

Group D — Analytics Write-Back Body Content

D1 — Add ## Writing Results Back to 7 analytics skills

Group E — Field-Level Encryption (FLE) Skills

E1 — Create skills/fle/SKILL.md (concept skill)

E2 — Create 9 language FLE skills

Group F — Shared File Completeness

F1 — shared/server/durability.md: add .NET, Rust, Scala, PHP, Ruby examples

F2 — shared/server/subdocument.md: add Python, .NET, Rust, Scala, PHP, Ruby examples

Acceptance Criteria

Implementation Steps

Round 22 — Routing Correctness & Quality Fixes (archived)

Problem Statement

Findings & Requirements

Finding 1 — Wrong routing for Rust/Ruby transaction queries (P0)

Finding 2 — server-querying-* missing columnar-analytics edge for 8 languages (P1)

Finding 3 — server-connection-rust and server-connection-ruby lack body explanation for unsupported transactions (P1)

Finding 4 — analytics-ruby missing explanation for transactional write-back (P2)

Finding 5 — Blank lines inside trigger lists in discovery.yaml (P3)

Finding 6 — Double --- in search-concepts/SKILL.md (P3)

Finding 7 — analytics-* use_when version boundary is ambiguous (P3)

Acceptance Criteria

Implementation Steps

Round 21 Spec — PM Feedback Fixes (archived)

Problem Statement

Issue 1 — Implement eval.sh --execute via Anthropic API

Requirements

Acceptance criteria

Issue 2 — Skipped (routing consumption contract is platform's responsibility)

Issue 3 — Validator: warn when language-family skills are missing canonical sections

Required sections per family (derived from current majority pattern)

Acceptance criteria

Issue 4 — Add ctx.query() to transactions-python and transactions-go

Acceptance criteria

Issue 5 — Add per-language error reference to each server-connection-* skill

The 6 errors to cover (per language)

Acceptance criteria

Issue 6 — Split testing-patterns into 9 language-specific skills

Structure

discovery.yaml

routing.yaml

Acceptance criteria

Issue 7 — Validator: add last_verified staleness check on the field value (not git date)

Acceptance criteria

Issue 8 — Fix analytics-* use_when wording ("legacy CBAS" is premature)

Acceptance criteria

Implementation Order

A1 — `testing-patterns-rust`: `result.content()` on `GetResult` (won't compile)

A2 — `testing-patterns-rust`: `testcontainers::clients::Cli` removed in v0.15

A3 — `testing-patterns-rust`: wrong `ClusterOptions` API

A4 — `testing-patterns-php`: `ClusterOptions::build()` doesn't exist

A5 — `testing-patterns-scala`: `ClusterOptions.create()` is Java API

A6 — `testing-patterns-ruby`: `Couchbase::Options::Cluster()` is invalid Ruby

A7 — `search-scala`: `Seq[Double]` + `VectorQuery.create()` — wrong type and wrong API

A8 — `sdk-patterns-rust`: `DecrementOptions` used but not imported

A9 — `transactions-dotnet`: missing `ctx.QueryAsync()`, shows wrong SQL syntax

B1 — `sdk-patterns-python`: broken reference to non-existent file

B2 — `testing-patterns/SKILL.md`: false statement about PHP/Ruby testcontainers

C1 — Add `## KV Range Scan` to 6 sdk-patterns-* skills

D1 — Add `## Writing Results Back` to 7 analytics skills

E1 — Create `skills/fle/SKILL.md` (concept skill)

F1 — `shared/server/durability.md`: add .NET, Rust, Scala, PHP, Ruby examples

F2 — `shared/server/subdocument.md`: add Python, .NET, Rust, Scala, PHP, Ruby examples

Finding 2 — `server-querying-*` missing `columnar-analytics` edge for 8 languages (P1)

Finding 3 — `server-connection-rust` and `server-connection-ruby` lack body explanation for unsupported transactions (P1)

Finding 4 — `analytics-ruby` missing explanation for transactional write-back (P2)

Finding 5 — Blank lines inside trigger lists in `discovery.yaml` (P3)

Finding 6 — Double `---` in `search-concepts/SKILL.md` (P3)

Finding 7 — `analytics-*` `use_when` version boundary is ambiguous (P3)

Issue 1 — Implement `eval.sh --execute` via Anthropic API

Issue 4 — Add `ctx.query()` to `transactions-python` and `transactions-go`

Issue 5 — Add per-language error reference to each `server-connection-*` skill

Issue 6 — Split `testing-patterns` into 9 language-specific skills

Issue 7 — Validator: add `last_verified` staleness check on the field value (not git date)

Issue 8 — Fix `analytics-*` `use_when` wording ("legacy CBAS" is premature)