/craft-reflect

name: reflect
description: "Apply captured learnings to improve the Craft harness and project patterns. Converts .learnings.yaml into permanent updates."
aliases:
  - apply-learnings
  - update-harness

Reflect

Convert captured learnings from `.craft/.learnings.yaml` into permanent harness files in `.claude/`.

When to Use

• Triggered automatically by `/craft` when pending learnings exist
• Manually via `/craft:reflect` at any time
• Prompted at cycle-complete before archiving

Flow

Step 1: Load Pending Learnings & Ungraduated Fixes

Read `.craft/.learnings.yaml` and filter for `status: pending`:

Use **Grep** with pattern `status: pending`, path `.craft/.learnings.yaml`, output_mode `count` → `pending_count`. If the file doesn't exist, `pending_count = 0`.

Also check for aggregated failure patterns from the active cycle:

If `ACTIVE_CYCLE` is set, use **Grep** with pattern `^ - pattern:`, path `.craft/cycles/$ACTIVE_CYCLE/.failure-patterns.yaml`, output_mode `count` → `failure_patterns`. If file doesn't exist or `ACTIVE_CYCLE` not set, `failure_patterns = 0`.

Also count ungraduated fix records (the second intake - fixes carry human-confirmed root causes that can graduate into `.claude/rules/`):

FIX_COUNT=$(bash "${CLAUDE_PLUGIN_ROOT}/hooks/scripts/count-ungraduated-fixes.sh")
THRESHOLD=$(grep -m1 '^rule_pass_threshold:' "${CRAFT_PROJECT_ROOT:-.}/.craft/settings.yaml" 2>/dev/null | sed 's/^rule_pass_threshold:[[:space:]]*//')
THRESHOLD=${THRESHOLD:-10}

The fix queue is **actionable only when `FIX_COUNT >= THRESHOLD`** - below the threshold there is no fix action available, so it counts as empty for this gate.

**If no pending learnings AND no failure patterns AND `FIX_COUNT < THRESHOLD`:** > "No pending learnings to process. Harness is up to date."

**If anything is actionable:** Continue to Step 1b.

---

Step 1b: Rule-Pass Offer (when the fix queue is actionable)

**If `FIX_COUNT >= THRESHOLD`**, offer the rule pass FIRST - before any learnings drain. Fixes are the denser signal (every record is a human-confirmed root cause).

Use **AskUserQuestion**:

question: "[FIX_COUNT] fixes have accumulated since the last rule pass. Run a rule pass to mine them for graduation-worthy rules?"
header: "Rule pass"
options:
  - label: "Run the rule pass"
    description: "~2-3 min agent read + per-rule review. Proposals are review-gated - nothing is written without your approval."
  - label: "Not now"
    description: "Skip - the offer returns next reflect (the counter does not reset on decline)"

**If "Run the rule pass":** Read `${CLAUDE_PLUGIN_ROOT}/commands/references/rule-pass.md` and follow its instructions completely (agent invocation, presentation, review, write, receipt, watermark). When the pass completes, continue below.

**If "Not now":** Do NOT touch `.craft/fixes/.rule-pass-state` - the watermark only advances on a completed pass. Continue below.

**Then:** If `pending_count > 0` or `failure_patterns > 0`, continue to Step 2 (the learnings drain, unchanged). Otherwise the session is done: > "Nothing else to reflect on."

**If `FIX_COUNT < THRESHOLD`** (learnings or failure patterns brought us here): skip this step, continue to Step 2.

---

Step 2: Present Summary

Present learnings organized by type and target. Include all sections that have items:

> "**Pending Learnings** > > **Conventions** (→ `.claude/CLAUDE.md`): > - Use Zustand for client state (2 occurrences) > - Prefer server components (3 occurrences) > > **Behaviors** (→ `.claude/CLAUDE.md`): > - Never skip pre-existing code (2 occurrences) > > **Enforcements** (→ `.claude/rules/`): > - no-any-type: Never use 'any' (3 occurrences) > > **Automations** (→ `.claude/settings.local.json`): > - prettier on edit (2 occurrences) > > **Skills** (→ `.claude/skills/`): > - our-form-pattern (3 occurrences) > > **Workflows** (→ `.claude/commands/`): > - create-component (3 occurrences) > > **Tool Failure Patterns** (→ `.claude/rules/`): > - [label from patterns file] ([total_count] failures across [N] stories) > > These are knowledge gaps the agent hit repeatedly — project-specific things it should learn. > > Apply these to the harness?"

Read `.failure-patterns.yaml` to populate the Tool Failure Patterns section. For each `pattern` entry, display its `label`, `total_count`, and the number of unique stories. Only show the Tool Failure Patterns section if `failure_patterns > 0`.

Use **AskUserQuestion**:

question: "Apply learnings to harness?"
header: "Reflect"
options:
  - label: "Apply all"
    description: "Write all pending learnings to .claude/"
  - label: "Review each"
    description: "Approve one by one"
  - label: "Skip for now"
    description: "Keep learnings pending"

---

Step 3: Write to Harness

**Ensure directories exist:**

mkdir -p .claude/rules .claude/skills .claude/commands

---

3a. Conventions & Behaviors → `.claude/CLAUDE.md`

If `.claude/CLAUDE.md` doesn't exist, create it:

# Project Instructions

## Stack & Conventions

## Behaviors

**Append conventions** to Stack & Conventions section:

- Use Zustand for client state, not Redux
- Prefer server components by default

**Append behaviors** to Behaviors section:

- Never skip pre-existing code with 'unchanged' comments
- Always read files before editing

---

3b. Enforcements → `.claude/rules/*.md`

Create `.claude/rules/[rule_name].md` with `paths:` frontmatter:

---
paths:
  - "**/*.ts"
  - "**/*.tsx"
---
# No Any Type

Never use `any` in TypeScript. Always provide proper types.

## Bad

```typescript
const data: any = fetchData()

Good

const data: User = fetchData()

#### 3b-ii. Tool Failure Patterns → `.claude/rules/[suggested_rule].md`

For each approved failure pattern, write `.claude/rules/[suggested_rule].md`:

```markdown
# Rule: [label]

[description of what to do instead, d