feat: examples + output_shape on Lesson schema (#129)

[Gradata]

Closes #129.

Changes

• New Example dataclass with good/bad fields
• New optional fields on Lesson: examples: list[Example], output_shape: str | None
• Markdown round-trip preserved (parse_lessons + format_lessons)
• Rule injection emits structured <rule><goal/><shape/><good/><bad/></rule> XML when populated
• capture_example_from_correction populates examples on graduation (de-duped, cap=3)
• 4 new tests cover round-trip + back-compat + rendering + capture

Test plan

• pytest tests/test_lesson_examples.py -xvs — 4/4 pass
• Full suite (excluding integration): 4115 pass, 1 pre-existing flake (test_doctor_runs_on_brain, fixed in fix(test): de-flake test_doctor_runs_on_brain #157)

Layering check

No Layer 0 -> 2 imports introduced.

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 23391b37-a72c-462c-9c3d-ea64c59129a8

📥 Commits

Reviewing files that changed from the base of the PR and between 99c477e and 9909071.

📒 Files selected for processing (4)

• Gradata/src/gradata/_types.py
• Gradata/src/gradata/enhancements/self_improvement/_confidence.py
• Gradata/src/gradata/rules/rule_engine/_formatting.py
• Gradata/tests/test_lesson_examples.py

---

📝 Walkthrough

• New dataclass Example with good and bad fields for representing paired corrections; includes to_dict() and from_dict() serialization methods
• Extended Lesson schema with two optional fields: examples: list[Example] (defaults to empty list) and output_shape: str | None (defaults to None)
• Backward compatible — pre-upgrade serialized lessons default to empty examples and None output_shape
• Updated parsing/formatting for lessons in _confidence.py — now deserializes Examples: JSON blocks and Output shape: fields from markdown
• Structured XML rendering in rule injection — emits <rule><goal/><shape/><good/><bad/></rule> blocks when examples or output_shape are populated; falls back to legacy prose bullets when absent
• Auto-populated examples via capture_example_from_correction() — appends surviving corrections as Example(good, bad) entries, deduplicated and capped at 3 most recent
• Four comprehensive tests covering round-trip serialization, legacy back-compat, XML rendering, and example capture with deduplication
• No breaking changes — all changes are additive; layering check confirmed no Layer 0→2 import violations

Walkthrough

This PR adds a new Example dataclass to the Lesson schema to capture paired "good" vs "bad" guidance from corrections, along with an optional output_shape field to describe governed output characteristics. Parsing and formatting logic are updated to serialize/deserialize these fields in markdown, and the rule-formatting function now emits structured XML <rule> blocks with example pairs and shape information when available.

Changes

Cohort / File(s)	Summary
Data Schema Gradata/src/gradata/_types.py	Adds Example dataclass with good/bad string fields, to_dict(), and from_dict() methods. Updates Lesson with examples: list[Example] (defaults to empty list) and output_shape: str | None (defaults to None) for backward compatibility.
Lesson Parsing & Serialization Gradata/src/gradata/enhancements/self_improvement/_confidence.py	Extends markdown parsing to deserialize Examples: JSON arrays into Lesson.examples (with graceful handling of malformed input) and extract Output shape: into Lesson.output_shape. Updates formatting to serialize both fields back to markdown when populated.
Rule Formatting & Example Capture Gradata/src/gradata/rules/rule_engine/_formatting.py	Modifies format_rules_for_prompt() to emit structured XML <rule> blocks with <goal>, <shape>, and <good>/<bad> tags when examples or output\_shape are present; falls back to bullet format when absent. Extends capture_example_from_correction() to populate lesson.examples with deduplication and a 3-example cap.
Test Suite Gradata/tests/test_lesson_examples.py	Comprehensive test coverage validating roundtrip preservation of examples and output\_shape, legacy markdown parsing without new fields, structured XML rendering, and example deduplication/capping logic.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(rules): slot-grouped brain injection + graduation-time classifier #138: Modifies the same Lesson dataclass and lesson markdown parsing/formatting infrastructure, creating potential for overlapping changes or integration concerns.

Suggested labels

feature

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/lesson-examples-output-shape

---

_{Review rate limit: 2/5 reviews remaining, refill in 34 minutes and 46 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}