Reflecting

Overview

Reflecting is the mandatory reflection gate. It runs primarily at a passing /dr-compliance verdict; /dr-archive Step 0.5 is a freshness fallback that regenerates the reflection only when it is missing or stale. It runs for every completed task, reviewing what happened, extracting lessons learned, and proposing framework improvements. Since v1.10.0 it has replaced the former optional /dr-reflect command — because reflection was expected on every task yet trivially skippable as a separate stage.

Invocation Contract

This skill is not a standalone command. It is loaded internally by /dr-compliance (primary) or by /dr-archive Step 0.5 (fallback). The input is the resolved task state from datarim/tasks.md and datarim/activeContext.md. The output is a reflection document at datarim/reflection/reflection-{task-id}.md, plus optional approved Class A evolution changes and a follow-up task list returned to /dr-archive Step 4. Freshness is decided by dev-tools/reflection-freshness.sh: the reflection carries a reflection_basis stamp (a truncated hash of the compliance report), and archive regenerates it only when the file, the stamp or the report is missing, or the stamp no longer matches the report.

What It Does

1. Load reviewer persona and security + testing skills for context
2. Review changes against the Definition of Done, verify tests pass, check for security vulnerabilities
3. Create reflection document using the reflection template
4. Record the known-fix decision — either one validated known_fix record (failure class, symptoms, fix steps, verification, sources) in the task's insights file, or an explicit none; an omitted verdict blocks archive
5. Generate evolution proposals — classify each as Class A (content change, approval-ready) or Class B (operating-model change, requires PRD update first per the evolution skill's gate). Before declining a lesson as redundant, a recurrence check against earlier reflections runs; a recurring lesson must be promoted to a gate
6. Run health-metrics check — count total skills, agents, commands and compare against thresholds. Suggest /dr-optimize if any threshold is exceeded
7. Identify follow-up tasks and return them to /dr-archive Step 4 for backlog writes

Class A vs Class B Gate

Class A proposals (add a recipe, fix a description, update an existing skill) go through normal approval. Class B proposals (change source-of-truth direction, sync semantics, pipeline routing, core contract) require a PRD update before they can be approved. This gate was introduced after the <TASK-ID>/<TASK-ID> incident where a research conclusion was treated as a regular proposal and caused 6 hours of wrong-direction work.

Failure Mode

If the skill fails to load or the user rejects all proposals, the archive process stops at Step 0.5. It does not proceed to Step 1. The archive is idempotent — re-running re-enters Step 0.5.