Create Implementation Plan For Redis API Change

Planning rules, and where the mechanics live

The API, Javadoc, consistency and test mechanics are owned by extend-commands-api and the .agents/docs/ pages; the plan links them in conventions: and never restates them. What this skill adds is the planning sequence:

• Order the steps types-first. Argument and response types exist before any interface references them (extend-commands-api, Decision tree B.1; Top pitfalls 2), so section 5 starts with them and every later step names the type it depends on.
• Write the sync signature in full, the mirrors as a table. The sync method and its Javadoc are the contract; the async, reactive, Kotlin and node-selection forms follow the Mapping rules of .agents/docs/api-consistency.md - list them, do not re-derive the rules. Enumerate the complete overload set Decision tree B.2 demands and justify any omission.
• Decide the reply shape per protocol without a server. Take RESP2 and RESP3 from HLD section 5, mark them expected in Risks, and plan the Resp2 integration overload when they differ (.agents/docs/integration-testing.md).
• Pick the cluster routing shape deliberately - single-key, fan-out or node-specific (Decision tree B.8; .agents/docs/architecture.md, Cluster routing) - and take the read-only flag from HLD section 4 (Decision tree B.9).
• Name the tests so the runner picks them up: *UnitTests run under Surefire, *IntegrationTests under Failsafe (AGENTS.md, Testing Rules); only the latter can appear in integration_targets.
• Link the mechanics, do not restate them - put these headings in conventions: and cite them next to the step that needs them: overload and List<K> rules (Decision tree B.2), @since / @param / @throws forms (Types & args conventions; .agents/docs/javadoc.md), CommandKeyword versus CommandType (Decision tree B.4), ReadOnlyCommands and its count test (Decision tree B.9), the KnownApiDeviations policy (.agents/docs/api-consistency.md, Editing workflow), formatter and @author rules (AGENTS.md, Coding Style Essentials), the removed generator sources (Top pitfalls 5), module areas and standalone-modules (Decision tree D).

Output contract

Exactly one markdown file: ./PLAN.md, or the path the requester gives (supervised only; unattended is always ./PLAN.md). The bot stores the merged file as redis-oss/client-hld/<feature>/lettuce-plan.md in the design repo and validates the frontmatter with pydantic, failing closed, so every key below is present with the stated type.

---
feature: bless
client: lettuce
hld: {path: redis-oss/client-hld/bless/README.md, sha: <approved_sha>}
tracks: [redis/redis#15649]
target_version: "8.12"
decision_class: B                    # the convention skill's decision-tree letter; none when estimated_size is none
conventions:                         # headings the coder reads, as "path#Heading" - block form, every entry quoted
  - ".agents/skills/extend-commands-api/SKILL.md#Decision tree"
  - ".agents/skills/extend-commands-api/SKILL.md#Types & args conventions"
  - ".agents/docs/api-consistency.md#Mapping rules"
estimated_size: medium               # none | small | medium | large
integration_targets: [KeyCommandIntegrationTests, KeyClusterCommandIntegrationTests]   # ^[A-Za-z0-9_.*$#-]+$
unit_targets: [BlessArgsUnitTests, RedisCommandBuilderUnitTests]
open_questions: 2
---

integration_targets names the Failsafe classes the harness runs on standalone and cluster: the group's base <Group>CommandIntegrationTests and its <Group>ClusterCommandIntegrationTests, plus <Group>CommandResp2IntegrationTests when the reply differs by protocol; for the Search area the RediSearch*IntegrationTests classes under core/search/ and RediSearchClusterIntegrationTests. Every entry must match ^[A-Za-z0-9_.*$#-]+$ (a class name, optionally Class#method). Keep conventions in block form with every entry quoted: headings carry &, ( and [ which break a YAML flow sequence, and the bot rejects a plan whose frontmatter does not parse. estimated_size: none (with decision_class: none) means Lettuce is not impacted: the body then has section 1 explaining why from this repo's code, every other section reads "none", and section 5 has no steps.

Then these sections, in this order, all present (write "none" rather than omitting one):

1. Summary - what the change gives a Lettuce user, the decision class, the analogue traced, and the size estimate with its reason.
2. HLD requirement coverage - R.x | where (file, symbol) | proving test | note, one row per R.x and NF.x.
3. Public API to add/change - the sync signatures in full with their Javadoc (house form, @since, @throws for every builder precondition), then a table of the mirrors per flavor (async, reactive, Kotlin, node-selection sync/async) with the mapped return type, the complete overload set, and a back-compat note (additive / deprecates X / breaking).
4. Files to change - path | add/edit | what, covering types, interfaces, builder, dispatch, Kotlin, protocol enums, read-only registry, every test class and docs/new-features.md.
5. Ordered implementation steps - each with the files, the check to run after it (for example the consistency suite command from The consistency suite is the safety net), and a "done when".
6. Test plan - unit (args, builder, output), integration per topology (standalone, cluster; RESP2 through the Resp2 overload where it exists or is created), the gating annotation and value, the written-not-run list (what the sandbox cannot execute), and the exact harness commands: mvn -B -Dtest=<unit_targets> -Dsurefire.failIfNoSpecifiedTests=false test and mvn -B -DskipITs=false -DskipUnitTests=true -Dit.failIfNoSpecifiedTests=false -Dit.test=<integration_targets> verify -Pci with REDIS_ENDPOINTS_CONFIG_PATH set and TEST_ENV_PROVIDER unset.
7. Docs / changelog / public-API files - the docs/new-features.md line, any feature page, and the statement that Lettuce has no API-tracking file to update.
8. Behaviour against older servers - what a user gets on a server without the command or option (the server error, gated tests skipped by @EnabledOnCommand).
9. Risks & open questions - each with the planner's default; includes every unverified item and every HLD-versus-convention conflict.
10. Out of scope - what the HLD mentions that this plan deliberately leaves out, and why.

Running it locally

From this repo, in Claude Code / Codex / Cursor, with an HLD at hand:

Use the create-implementation-plan-for-redis-api-change skill to plan the Lettuce implementation of $TMPDIR/bless/README.md into $TMPDIR/bless/lettuce-plan.md.

The agent reads the HLD and this checkout, traces the analogue, and presents the plan for review; it edits nothing else. Inside the bot the same text is the system prompt of the planning task (plan_skill_path in the roster): the sandbox clones redis/lettuce at main, writes ./HLD.md, runs this skill with Mode: unattended, and opens the resulting ./PLAN.md as one PR in the design repo. Reviewers revise it with /revise <text>, /redo, or a "Request changes" review; merging it is the go for the coding task, which follows the plan rather than this repo's extension skill.

Testing the skill

Three canonical inputs, each with a pass condition:

A plan that cites as existing a file this repo does not have (rows marked add in section 4 may name new files), or a signature with no sibling and no R.x behind it, has failed. A plan whose section 9 is empty while the HLD's section 8 scenarios are all expected has failed too: the unverified replies belong there.