Skip to main content
skill CX Codex

reflect · rsmdt — Claude Code skill: session log mining and proposals

The reflect skill reads Claude Code session logs over a date range, spots weaknesses in project setup, and proposes concrete changes — new skills, hooks, rules, or edits to CLAUDE.md.

MIT ★ 587 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup
Open on GitHub

What reflect does

reflect scans session logs through six lenses: tool errors and retry loops (friction), inefficient dialogue (conversation), token waste on model routing (router), manual multi-step work without automation (capability), dangerous operations without guardrails (guardrail), and dead or ignored instructions in CLAUDE.md (instruction). The skill clusters findings into opportunities, adversarially validates each claim, and reports proposals to improve existing artifacts or create new ones.

Run it as /start:reflect last 3 days or /start:reflect 2026-07-10..2026-07-16; no argument defaults to yesterday. It requires Node.js, access to the project's log directory, and plan approval before launch. It never edits anything itself — you apply changes.

The report includes a six-dimension grade (justification, evidence accuracy, coverage, novelty, actionability, balance), but the skill does not revise the report when dimensions fail — failing scores remain visible.

What it helps with

  • mine session logs for error patterns and inefficiencies
  • propose new skills and hooks to automate recurring manual work
  • spot dead or ignored rules in CLAUDE.md
  • verify every proposal is backed by cited log evidence

Example prompts for the agent

  • /start:reflect last 3 days
  • /start:reflect 2026-07-10..2026-07-16
  • Review yesterday's logs and show where guardrails are missing

How to install reflect

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install start@the-startup

This installs the whole start plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill reflect -a claude-code

3Manually: put the files in place

~/.claude/skills/reflect/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/reflect/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about reflect

How to install reflect in Claude Code?

Run /plugin marketplace add rsmdt/the-startup, then /plugin install start@the-startup. The skill file will be at ~/.claude/skills/reflect/SKILL.md.

What does reflect do?

The skill reads Claude Code session logs over a date range, finds issues through six analysis lenses, and proposes concrete project changes — new skills, hooks, rules, or edits to CLAUDE.md. It never edits anything itself.

Which analysis lenses does reflect use?

Six lenses: friction (errors, retries), conversation (inefficient dialogue), router (token waste on models), capability (manual work without automation), guardrail (dangerous operations), instruction (dead rules in CLAUDE.md).

Source text

SKILL.md · MIT
---
name: reflect
description: Self-improvement from this project's Claude Code session logs. Mines a date range (default "yesterday") through parallel signal lenses, clusters what it finds into improvement opportunities, drafts a concrete change per opportunity, adversarially validates the cited evidence, and reports improve/create proposals across the project harness — skills, subagents, output styles, the CLAUDE.md/AGENTS.md instruction, and guardrails (permission rules, hooks). Advisory — it never edits an artifact; you decide what to apply.
user-invocable: true
argument-hint: "date range (default: yesterday), e.g. 'last 3 days' or '2026-07-10..2026-07-16'"
---

## Persona

Act as the self-improvement orchestrator. You turn a date range into a **reflect plan** (purpose,
date range, signal lenses), get the user to approve it, then author and run **one dynamic workflow**
(the Workflow tool with an inline script you write) that mines, clusters, proposes, validates, and
reports. You do **not** mine logs, draft changes, or write the report yourself.

**Date range**: $ARGUMENTS

**Advisory is the identity.** reflect never edits or creates an artifact. It reports proposals, each
labelled **improve** (edit an existing artifact) or **create** (a new skill, subagent, hook, or
permission rule), with a concrete change and cited session-log evidence. A human applies them.

**In scope** — the project harness, all git-tracked: skills, subagents, and output styles under
`plugins/`; the project `CLAUDE.md` / `AGENTS.md`; guardrails in the project `.claude/settings.json`
(permission rules, hooks) and `CLAUDE.md` rules. **Out of scope:** the user's global `~/.claude/` files
and other projects' logs.

## Constraints

**Always:**
- Resolve the date range to absolute ISO `since` / `until` before launching; default to yesterday.
- Resolve `logRoot` to this project's session-log directory (the Claude home `projects/<slugified-cwd>/`) and confirm it has sessions in range; if none, say so and stop.
- Show the full plan in the chat and get approval before launching.
- Require citations: every proposal traces to a session-log record, and to a `file:line` where it points at code.
- Prefer **improve** over **create**; create only where no existing artifact fits.
- Writing under `.start/reflect/` is pre-authorized.

**Never:**
- Mine, draft, validate, or write the report outside the workflow.
- Apply a proposal unless the user asks — then on a branch, one proposal at a time.

## Reference Materials

- [Workflow Contract](reference/workflow.md) — stages, agent return schemas, decision rules, result shape
- [Surfaces](reference/surfaces.md) — each harness surface: what it is, where its fix lives, what to read first
- [Mine Agent](reference/mine-agent.md) — shared mining block plus the six lens prompts
- [Cluster Agent](reference/cluster-agent.md) · [Propose Agent](reference/propose-agent.md) · [Validate Agent](reference/validate-agent.md) · [Synthesize Agent](reference/synthesize-agent.md) · [Grade Agent](reference/grade-agent.md)
- [Plan Template](template.md) — the reflect plan document

## Workflow

### 1. Frame the Plan

Derive from `$ARGUMENTS` the date range (`since`, `until`, `label`), a slug `name` (e.g. `2026-07-16`),
and a terse purpose. Choose the signal lenses — default all six:

- `friction` — tool errors, user interrupts and rejections, retry loops, expensive turns
- `conversation` — inefficient dialogue that leaves no structured trace (samples sessions)
- `router` — over- or under-provisioned models per role
- `capability` — recurring manual multi-step work no skill or subagent owns (→ create)
- `guardrail` — recurring mistakes and unguarded dangerous operations (→ permission rule, hook, rule)
- `instruction` — dead, ignored, bloated, or ambiguous CLAUDE.md / AGENTS.md rules

Create `.start/reflect/[name]/` with a `.tracker/` directory and write `reflect.md` from template.md
with `status: draft`.

### 2. Approve or Refine

Display in the chat: the purpose, the resolved date range with ISO dates, the lenses, the target scope,
and that the run is advisory. Ask the user to *Approve* or *Refine*. On refine, update `reflect.md`,
re-display, and ask again. On approve, set `status: approved`.

### 3. Seed the Tracker

For each lens create a mine task and record its id:

`node ${CLAUDE_PLUGIN_ROOT}/scripts/task.js create --home .start/reflect/[name] --type mine --name "{lens}"`

### 4. Run the Dynamic Workflow

These instructions are the opt-in: call the Workflow tool directly with an inline script. Do not load the workflow-authoring reference or assemble the script through shell commands first — runs that detour through either stall before launching. Read reference/workflow.md,
reference/surfaces.md, and the agent references. Author one workflow script that implements the
contract exactly, each agent's prompt taken from its reference with placeholders filled. Launch it with
the Workflow tool, passing the resolved values as `args`. Set `status: in-progress`.

Choose `model` and `effort` per stage from what the stage does. Structured mining — scanning records for
errors, interrupts, and token counts — can run on a smaller, faster model. Reading dialogue for
inefficiency, spotting capability gaps, auditing instructions, clustering, validating, and grading need
the strongest model. A validating or grading stage never runs on a weaker model than the stage it
judges. When unsure, omit `model` so the stage inherits the session model.

Present a one-line dispatch summary, e.g.
`Reflecting on "{name}": {n} lenses over {label} → dynamic workflow (advisory)`.

### 5. Report

When the workflow returns (shape in reference/workflow.md):

1. Present the report: the per-surface ranking and the validated proposals grouped by surface, each with
   its change, label, evidence, and tier. Say how many were dropped in validation. Show the grade
   (`overall` and each dimension) and name every failing dimension — the report is not revised to clear
   it. If no proposal survived, say the run found nothing supportable and show no grade.
2. Set `reflect.md` `status: review`.
3. Ask the user to choose: *Apply a proposal (on a branch)* | *Deepen a lens* | *Persist report to
   docs/research/* | *Done*. When applying, run the target's `evals/evals.json` where one exists and
   surface the result before the next proposal.

© Rudolf S. · MIT · rsmdt/the-startup

Similar skills

All skills for Agent setup: memory, context, orchestration →

reflect by other authors comes first.

reflect backnotprop reflect is a Claude Code skill that reads the current session transcript and turns the user's corrections into edits on existing skills. The trigger is the word reflect. CX Codex +1 10,400installs reflect Alireza Rezvani reflect is a Claude Code skill that pauses a task and reviews the conversation’s direction. It runs when asked to zoom out or check whether the work is on course. CX Codex +1 320installs reflect NeoLabHQ reflect — a skill that makes the agent reread its own answer and list the flaws before you accept the work. CX Codex +1 1,400installs reflect haowjy reflect reviews delivered work before the final report and routes session knowledge into project files. Useful for catching overlooked needs while context is fresh. CX Codex +1 438installs reflect pwguler reflect — a skill that extracts lessons from a coding agent session and places them into project checks, skills, or instruction files. Runs at the end of a session with corrections, errors, or surprises. CX Codex +1 904installs create-pr OrchestKit create-pr — a skill that opens a GitHub pull request after running tests, linter, types, and security checks. Triggers on explicit invocation; plain gh pr create stays a command. CX Codex +1 209installs audit-library-health MoizIbnYousaf audit-library-health — a skill for diagnosing a skills library: validates structure, finds stale elements, checks documentation sync. Run before publishing or updating. CX Codex +1 170installs langgraph-human-in-the-loop langchain-ai langgraph-human-in-the-loop — a skill for building LangGraph workflows that pause and wait for human input. Use it to show agent output, request approval, or validate user responses before continuing. CX Codex +1 18,300installs skill-authoring-workflow deanpeters skill-authoring-workflow walks a skill from rough notes to a SKILL.md that passes the repo's checks. Useful when you add or update skills in Product-Manager-Skills. CX Codex +1 2,200installs coordination transilienceai coordination — a skill for coordinating agents in security testing workflows. Manages executor and validator spawning, holds engagement state in a single context, and avoids delegating thinking to sub-subagents. CX Codex +1 198installs skill-update transilienceai skill-update generates skill directory structure, validates against Anthropic best practices, and enforces line count limits per file. Use when creating or updating a skill. CX Codex +1 174installs

From the same set50

The whole set →
monitor-production The monitor-production subagent plans production metrics, logs, traces, alerts, and dashboards. Use it when defining SLOs or investigating recurring service failures. CX Codex ★ 587repo stars review-compatibility review-compatibility — a subagent for Claude Code that examines code for breaking changes to APIs, databases, and configs. CX Codex ★ 587repo stars specify-requirements specify-requirements is a Claude Code skill that drafts and validates PRDs in spec.md, structuring user stories and acceptance criteria. CX Codex +1 ★ 587repo stars build-feature build-feature is a Claude Code subagent that implements features across UI, APIs, services, and other project layers. It joins coding requests to build or change something. CX Codex ★ 587repo stars validate validate orchestrates spec reviews, file audits, spec-to-code drift detection, and constitution rule checks across specialist subagents. CX Codex +1 ★ 587repo stars the-chief the-chief — a subagent that scores task complexity, maps dependencies, and routes work to maximize parallel execution. Use it when requirements are unclear, work spans multiple systems, or independent activities can run simultaneously. CX Codex ★ 587repo stars design-system design-system designs a service's architecture — pattern, data stores, scaling path — and hands back diagrams and ADRs. Useful when you're deciding whether to split a monolith. CX Codex ★ 587repo stars optimize-performance optimize-performance — a performance optimization subagent for Claude Code. Targets slow page loads, backend API latency, database queries, and memory leaks based on profiling metrics. CX Codex ★ 587repo stars

Project sponsors

Companies that keep this analytics open