claude-engineering-plugin/docs/plans/2026-02-09-refactor-dspy-ruby-skill-update-plan.md

title, type, date

title	type	date
refactor: Update dspy-ruby skill to DSPy.rb v0.34.3 API	refactor	2026-02-09

Update dspy-ruby Skill to DSPy.rb v0.34.3 API

Problem

The dspy-ruby skill uses outdated API patterns (.forward(), result[:field], inline T.enum([...]), DSPy::Tool) and is missing 10+ features (events, lifecycle callbacks, GEPA, evaluation framework, BAML/TOON, storage, etc.).

Solution

Use the engineering skill as base (already has correct API), enhance with official docs content, rewrite all reference files and templates.

Source Priority (when conflicts arise)

1. Official docs (../dspy.rb/docs/src/) — source of truth for API correctness
2. Engineering skill (../engineering/.../dspy-rb/SKILL.md) — source of truth for structure/style
3. NavigationContext brainstorm — for Typed Context pattern only

Files to Update

Core (SKILL.md)

1. skills/dspy-ruby/SKILL.md — Copy from engineering base, then:
   • Fix frontmatter: name: dspy-rb → name: dspy-ruby, keep long description format
   • Add sections before "Guidelines for Claude": Events System, Lifecycle Callbacks, Fiber-Local LM Context, Evaluation Framework, GEPA Optimization, Typed Context Pattern, Schema Formats (BAML/TOON)
   • Update Resources section with 5 references + 3 assets using markdown links
   • Fix any backtick references to markdown link format

References (rewrite from themed doc batches)

2. references/core-concepts.md — Rewrite

   • Source: core-concepts/signatures.md, modules.md, predictors.md, advanced/complex-types.md
   • Cover: signatures (Date/Time types, T::Enum, defaults, field descriptions, BAML/TOON, recursive types), modules (.call() API, lifecycle callbacks, instruction update contract), predictors (all 4 types, concurrent predictions), type system (discriminators, union types)

3. references/toolsets.md — NEW

   • Source: core-concepts/toolsets.md, toolsets-guide.md
   • Cover: Tools::Base, Tools::Toolset DSL, type safety with Sorbet sigs, schema generation, built-in toolsets, testing

4. references/providers.md — Rewrite

   • Source: llms.txt.erb, engineering SKILL.md, core-concepts/module-runtime-context.md
   • Cover: per-provider adapters, RubyLLM unified adapter, Rails initializer, fiber-local LM context (DSPy.with_lm), feature-flagged model selection, compatibility matrix

5. references/optimization.md — Rewrite

   • Source: optimization/miprov2.md, gepa.md, evaluation.md, production/storage.md
   • Cover: MIPROv2 (dspy-miprov2 gem, AutoMode presets), GEPA (dspy-gepa gem, feedback maps), Evaluation (DSPy::Evals, built-in metrics, DSPy::Example), Storage (ProgramStorage)

6. references/observability.md — NEW

   • Source: production/observability.md, core-concepts/events.md, advanced/observability-interception.md
   • Cover: event system (module-scoped + global), dspy-o11y gems, Langfuse (env vars), score reporting (DSPy.score()), observation types, DSPy::Context.with_span

Assets (rewrite to current API)

7. assets/signature-template.rb — T::Enum classes, description: kwarg, Date/Time types, defaults, union types, .call() / result.field usage examples

8. assets/module-template.rb — .call() API, result.field, Tools::Base, lifecycle callbacks, DSPy.with_lm, configure_predictor

9. assets/config-template.rb — RubyLLM adapter, structured_outputs: true, after_initialize Rails pattern, dspy-o11y env vars, feature-flagged model selection

Metadata

10. .claude-plugin/plugin.json — Version 2.31.0 → 2.31.1

11. CHANGELOG.md — Add [2.31.1] - 2026-02-09 entry under ### Changed

Verification

# No old API patterns
grep -n '\.forward(\|result\[:\|T\.enum(\[\|DSPy::Tool[^s]' plugins/compound-engineering/skills/dspy-ruby/SKILL.md

# No backtick references
grep -E '`(references|assets|scripts)/' plugins/compound-engineering/skills/dspy-ruby/SKILL.md

# Frontmatter correct
head -4 plugins/compound-engineering/skills/dspy-ruby/SKILL.md

# JSON valid
cat plugins/compound-engineering/.claude-plugin/plugin.json | jq .

# All files exist
ls plugins/compound-engineering/skills/dspy-ruby/{references,assets}/

Success Criteria

• All API patterns updated (.call(), result.field, T::Enum, Tools::Base)
• New features covered: events, callbacks, fiber-local LM, GEPA, evals, BAML/TOON, storage, score API, RubyLLM, typed context
• 5 reference files present (core-concepts, toolsets, providers, optimization, observability)
• 3 asset templates updated to current API
• YAML frontmatter: name: dspy-ruby, description has "what" and "when"
• All reference links use [file.md](./references/file.md) format
• Writing style: imperative form, no "you should"
• Version bumped to 2.31.1, CHANGELOG updated
• Verification commands all pass

Source Materials

• Engineering skill: /Users/vicente/Workspaces/vicente.services/engineering/plugins/engineering-skills/skills/dspy-rb/SKILL.md
• Official docs: /Users/vicente/Workspaces/vicente.services/dspy.rb/docs/src/
• NavigationContext brainstorm: /Users/vicente/Workspaces/vicente.services/observo/observo-server/docs/brainstorms/2026-02-09-typed-navigation-context-brainstorm.md