Skill lifecycle phase 3: reflection rides the persistence branch

[jamiepine]

Phase 3 of docs/design-docs/skill-lifecycle.md: the pump that turns outcomes into skills. Stacked on #622.

One deliberate divergence from the design doc, per discussion: no separate reflection branch. The memory persistence branch already is the replay-fork this phase needs — silent, history-cloning, output-suppressed — so reflection rides it as one unified pass instead of spawning a second silent branch after heavy turns. This is also the shape Hermes actually runs in production (one post-task review fork handles memory and skills together).

How it works

The channel accumulates a reflection signal from two sources:

• a turn whose agentic loop crossed min_tool_iterations tool calls (counted from the appended history — one tool-call assistant message per iteration), or
• a worker attached to the conversation completing successfully.

When the signal is set and the cooldown allows, the next persistence branch spawns with skill_reflection on: its prompt gains the reflection section and its toolset gains read_skill/skill_manage/skills_list under WriteOrigin::Agent — so every Phase 2 rail applies mechanically (workspace-only, no installed or pinned targets, read-before-write, delete archives). The reflection signal can spawn the pass on its own even when no memory trigger fired, and cron conversations never reflect — scheduled runs repeat the same procedure on a timer and would grind out noise skills.

Persistence passes without the signal are byte-for-byte unchanged, and ingestion's persistence branch never reflects.

The prompt is the policy

The reflection section carries the rules that matter:

• decide first whether anything is worth keeping — no skill writes is the common case; a user correcting the agent's procedure is the strong write signal
• preference ladder: patch the governing skill → patch a related skill → add a references/ file → only then create, named for the task class, never the incident
• the negative-capture bans: no environment-dependent failures, no "tool X doesn't work" claims (they harden into refusals that outlive the problem), no transient errors, no one-off narratives, no unresolved failures dressed as procedure

Config

[skills.reflection]
enabled = true            # default
min_tool_iterations = 10  # per-turn tool calls that mark a turn worth reflecting on
cooldown_secs = 3600      # per-conversation

Follows the defaults + per-agent override pattern, hot-reloadable through RuntimeConfig like everything else.

Testing

Tool-call counting over history slices, the reflection section gating in the rendered prompt, and the TOML merge for the new [skills.reflection] block.

Note

This PR implements skill reflection on the memory persistence branch, triggered when turns exceed min_tool_iterations tool calls or workers complete successfully. The reflection signal is consumed by the next persistence pass, which now renders an additional reflection prompt section and gains skill management tools under agent-origin rails. Key changes: reflection signal tracking in Channel, tool-call counting in channel_history, prompt rendering for conditional skill reflection in memory_persistence.md.j2, and new reflection config block in toml_schema.rs. Cron conversations never reflect to avoid noise. _{Written by Tembo for commit 44edee99. This will update automatically on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: adf08797-431d-46bc-a0a6-34874e7e582b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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