# Sage Reflect

> Cycle review, Learnings with prevention rules, Next-cycle seeds

- Skill: `xoai/sage-reflect` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xoai/sage-reflect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xoai/sage-reflect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: xoai (https://skillmd.com/u/xoai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xoai/sage-reflect

---


## When to Use
Load this skill when the user runs `/sage-reflect` or asks to reflect something (the Sage reflect workflow).

## Arguments
Hermes does NOT interpolate an in-body argument token. The user's arguments/flags arrive as a SEPARATE instruction line appended to this skill invocation. Wherever the steps below refer to "the user's arguments", use the text of that appended instruction line.

## Independent review (delegate_task)
When a step calls for an independent review, invoke `delegate_task` against the `sage-reviewer` skill. Hermes delegate_task has NO toolset-restriction parameter — read-only is prompt-enforced, and you MUST verify afterward that the reviewer made no edits (e.g. `git status` unchanged) before accepting its verdict.

RULES (apply to every step — non-negotiable):
- Announce: "Sage → reflect workflow." before starting work
- Review the FULL cycle: artifacts, decisions, approaches tried
- ASK the user for real-world feedback — do not skip this step
- Every learning MUST use WHEN/CHECK/BECAUSE format
- Present learnings BEFORE storing — Zone 2 for approval
- Save reflection report to .sage/docs/reflect-*.md
- Seed the next cycle with concrete recommendations (Zone 3)
- Reflect is for looking back, NOT fixing. Suggest /fix if needed.
- Never use code blocks for interaction (checkpoints, options, status)


# Reflect Workflow

Look back. Extract learnings. Seed the next cycle.

## Auto-Pickup

Scan `.sage/work/` for recently completed initiatives
(status: completed in frontmatter). Scan `.sage/docs/` for
research and analysis artifacts. For the decision trail, read the
initiative's own log first —
`.sage/work/[initiative]/decisions.md` — then fall back to the
global `.sage/decisions.md` (cross-initiative decisions live
there; older projects may have only the global file).

If no completed work exists: "Sage: No completed initiatives
found. /reflect works best after a deliver cycle. Describe
what you want to reflect on, or type / for other commands."

## Step 1: Review the Cycle (Zone 1)

Sage → reflect workflow. Looking back at what was done.

[1] Full initiative — review the entire cycle for [initiative name]
[2] Recent work — reflect on the last few decisions
[3] Specific topic — describe what you want to reflect on

Pick 1-3, type / for commands, or describe what you need.

**For full initiative review, gather and present:**

Sage: Cycle review for [initiative name].

Timeline:
  [Date] — Brief approved: [summary]
  [Date] — Spec approved: [key decisions]
  [Date] — Plan: [N] tasks planned
  [Date] — Build complete: [what was shipped]

Decisions made: [count from decisions.md]
Approaches tried: [count from scratch.md if exists]
Learnings stored: [count from self-learning entries]

Key artifacts:
  .sage/work/[initiative]/brief.md
  .sage/work/[initiative]/spec.md
  .sage/docs/[related research/analysis]

## Step 2: Evaluate Outcomes

Ask the user for real-world feedback. This is the human input
Sage cannot generate — the signal from reality.

Sage: Now I need your perspective on how this went.

[1] What worked well? (What should we do again?)
[2] What didn't work? (What caused friction or rework?)
[3] What surprised you? (What was unexpected?)
[4] What feedback have you received? (From users, team, stakeholders)

Share any or all — or describe your overall assessment.

Pick 1-4, type / for commands, or describe what you need.

Listen to the user's responses. Ask follow-up questions if
the feedback is vague — specifics make better prevention rules.

## Step 3: Extract Learnings

Based on the cycle review + user feedback, identify learnings
in three categories:

**Reinforce** — what went well and should become standard practice.
**Prevent** — what went wrong and should be avoided next time.
**Improve** — what could be better with a specific change.

For each learning, write a WHEN/CHECK/BECAUSE prevention rule:

```
WHEN: [situation that triggers this learning]
CHECK: [observable condition to verify]
BECAUSE: [what happens if you don't — the consequence]
```

**Learnings quality check (before presenting):**
- Specific? Names concrete situations, not vague patterns.
- Actionable? A future agent could apply this without context.
- Has a CHECK? Observable condition, not self-assessment.
If a learning fails any criterion, improve it before presenting.

🔒 **LEARNINGS CHECKPOINT (Zone 2):**

Sage: Learnings extracted from [initiative/topic].

Reinforce:
  1. [Learning] — WHEN/CHECK/BECAUSE
  2. [Learning]

Prevent:
  1. [Learning] — WHEN/CHECK/BECAUSE
  2. [Learning]

Improve:
  1. [Learning] — WHEN/CHECK/BECAUSE

[A] Approve — store learnings  [R] Revise  [N] New session

Pick A/R/N, or tell me what to change.

## Step 4: Store and Update

On approval:

1. **Store each learning** via sage_memory_store with tags:
   `self-learning`, `reflect`, `[initiative-slug]`, and
   category tag (`reinforce`, `prevent`, or `improve`).

2. **Update conventions.md** if any learning revealed a project
   pattern that should become a convention. Announce what was
   added.

3. **Save reflection report** to `.sage/docs/reflect-[slug].md`
   with the full cycle review, user feedback, and learnings.

4. **Prepend to decisions.md:**
   ```
   ### YYYY-MM-DD — Reflection: [initiative/topic]
   [Summary of key learnings and what changes going forward.]
   ```

## Step 5: Seed the Next Cycle (Zone 3)

The most powerful step — connect learnings to future work.

Sage: Reflection complete. [N] learnings stored.

Seeds for next cycle:
  [Specific recommendation based on learnings, e.g.,
  "Start with payment edge case research next time —
  this area took 3x longer than expected."]

Report: .sage/docs/reflect-[slug].md

Next steps:
  /research — start the next initiative (learnings loaded via Rule 0)
  /build    — spec → plan → implement → verify
  /design   — brief → spec → copy

Type a command, or describe what you want to do next.

## Quality Criteria

Good reflection output:
- Cycle review is factual — dates, decisions, artifacts, not summaries
- User feedback is captured in their words, not paraphrased away
- Every learning has WHEN/CHECK/BECAUSE format
- Learnings are specific enough for a different agent to apply
- Next-cycle seeds are concrete recommendations, not generic advice
- The reflection report is saved as a permanent artifact

## Rules

- Reflect is for LOOKING BACK, not for fixing. If the reflection
  reveals something to fix, suggest /fix. Don't fix during reflect.
- User feedback is required. Don't generate learnings from the
  cycle review alone — the real-world signal matters most.
- WHEN/CHECK/BECAUSE is mandatory for every learning.
- Store learnings with `self-learning` + `reflect` tags so Rule 0
  memory search finds them in future cycles.
- Save the reflection report to .sage/docs/ — it's a permanent
  artifact, not a transient conversation.
- Seeding the next cycle is not optional. The value of reflection
  is in what changes going forward, not in the act of looking back.