/reflect

description: Analyze session and extract learnings to CLAUDE.md Skill Memories. Supports subcommands --on, --off, --status, --clear. Activates for reflect, remember, learn from session, extract learnings.
argument-hint: [--on | --off | --status | --clear [--skill name | --all]]

Reflect Command

**Analyze session and extract learnings to CLAUDE.md Skill Memories section.**

Usage

# Manual reflection (analyzes session signals)
sw:reflect
sw:reflect "Focus on the API patterns we discussed"

# Enable auto-reflection on session end
sw:reflect --on

# Disable auto-reflection
sw:reflect --off

# Show reflection config and learning statistics
sw:reflect --status

# Clear learnings
sw:reflect --clear --skill frontend
sw:reflect --clear --all

Subcommands

Default (no flags) - Manual Reflection

Scans conversation for learnable signals and extracts to CLAUDE.md.

**Signal Detection:**

**Corrections (High Confidence)**

User: "No, don't use that button. Use our <Button variant='primary'>"
      → Learning: Always use Button component with variant='primary' from design system
      → Skill: frontend

**Problem Reports (High Confidence)**

User: "Voice control doesn't recognize commands"
      → Learning: Voice dictation mangles slash commands - type manually or paste
      → Skill: general

**Approvals (Medium Confidence)**

User: "Perfect! That's exactly how our API should look."
      → Learning: Continue using API pattern with status, data, error fields
      → Skill: backend

**LLM Extraction** uses Claude Haiku to extract SpecWeave-specific learnings, then writes to the `## Skill Memories` section in CLAUDE.md.

`--on` - Enable Auto-Reflection

Enables automatic session analysis via the stop hook.

**Execution:** 1. Read existing config from `.specweave/config.json` 2. Update config to set `reflect.enabled: true` 3. Display confirmation

**Output:**

Auto-reflection ENABLED

Stop hook will analyze sessions on exit.
Learnings saved to CLAUDE.md Skill Memories section.

Disable with: sw:reflect --off

`--off` - Disable Auto-Reflection

Disables automatic session analysis. Manual `sw:reflect` still works.

**CRITICAL: This is a SIMPLE operation. NO Glob, NO parallel tool calls needed.**

**Execution:** 1. Read existing config from `.specweave/state/reflect-config.json` (If file doesn't exist, create with autoReflect: false) 2. Write updated config: set `autoReflect` to `false`, preserve other fields 3. Display confirmation

**Output:**

Auto-reflection DISABLED

Manual sw:reflect still works.
Existing learnings preserved.

Re-enable with: sw:reflect --on

**WARNING**: Do NOT use Glob to scan directories - this operation only writes ONE file.

`--status` - Show Config & Statistics

Shows reflection configuration and learning statistics.

**Execution:** 1. Read config from `.specweave/config.json` for reflect settings 2. Read CLAUDE.md to find Skill Memories section 3. Parse learnings by skill category 4. Display dashboard

**Output:**

REFLECT: Status Dashboard

CONFIGURATION
  Reflection:      Enabled
  Model:           haiku
  Max/session:     3

SKILL MEMORIES (CLAUDE.md)
  Skill           Learnings
  devops          1
  frontend        2
  backend         3
  general         2
  Total:          8

RECENT LEARNINGS
  - [devops] LSP requires ENABLE_LSP_TOOL=1 env var
  - [frontend] Use shadcn/ui Button component
  - [backend] Return 404 for missing resources

## Skill Refinement Suggestions
  Skill            Signals (J/R/C)   Severity   Last seen         Command
  sw:architect     5 (3/1/1)         high       2026-04-19 18:22  sw:skill-refine sw:architect
  sw:pm            3 (2/1/0)         medium     2026-04-18 09:07  sw:skill-refine sw:pm

Introduced in **increment 0671 — skill refinement loop**. Skills with ≥3 negative signals in `.specweave/state/skill-signals.json` (`type: "refinement"`) are ranked by severity × recency. Entries with `<3` signals are omitted from the list; the whole section is omitted when no skills qualify.

Signal sources (J/R/C = judge-llm / rubric / code-reviewer) come from closure gates. See [`sw:skill-refine`](./skill-refine.md) for flags, attribution heuristics, and the four red-line ADRs.

`--clear` - Remove Learnings

Remove specific learnings from CLAUDE.md Skill Memories section.

sw:reflect --clear --skill frontend   # Clear all learnings for skill
sw:reflect --clear --all              # Clear ALL learnings (requires confirmation)

**Execution:** 1. Read CLAUDE.md to find Skill Memories section 2. Show confirmation with what will be deleted 3. Edit CLAUDE.md to remove matching learnings on confirmation

Session-end Nudge

Added in increment 0671. When `/sw:done` closes an increment, the reflect stop-hook checks whether the session accumulated either:

• ≥1 high-confidence learning (eligible for CLAUDE.md persistence), or
• ≥1 refinement signal in `.specweave/state/skill-signals.json` attributed to an existing skill.

If so, a **single-line** prompt is printed at closure time:

Detected: 2 signals for sw:architect — run sw:skill-refine sw:architect? (y/N)

or, for a learning nudge:

Detected: 1 high-confidence learning — run sw:reflect? (y/N)

**The nudge never auto-executes a command.** The user must explicitly run the suggested command. Declining (N or no input within 5s) logs no penalty; signals remain in `skill-signals.json` for later invocation.

Performance: the nudge check adds <100ms to `/sw:done` close time.

Disabling the nudge

Set `reflect.autoNudge: false` in `.specweave/config.json`:

{
  "reflect": {
    "enabled": true,
    "autoNudge": false
  }
}

When `autoNudge` is false, no nudge is printed at close; `sw:reflect` and `sw:skill-refine` remain manually invocable.

Configuration

In `.specweave/config.json`:

{
  "reflect": {
    "enabled": true,
    "model": "haiku",
    "maxLearningsPerSessi