reflect git:20261030.7d3bf2cA

Immutable. This exact content never changes and is served at /api/v1/blob/8b5464cb55f894ce.

---
name: reflect
description: Post-implementation self-review — catch issues before /review (/adlc:review on the plugin install)
argument-hint: Optional REQ-xxx ID or branch name to scope the reflection
---

# /reflect — Post-Implementation Reflection

You are performing a self-review of recently implemented code to catch issues before the formal `/review` step. This is a fast, honest assessment of your own work.

## Ethos

!`test -s .adlc/ETHOS.md && cat .adlc/ETHOS.md || echo No ethos found — run /init, or /adlc:init on the plugin install, to vendor .adlc/ETHOS.md`

## Context

Run this block first, with your shell tool, and read its output before you continue. Each read prints a notice instead of failing when its file is absent.

```sh
# adlc-context
echo '--- Current branch'
git branch --show-current 2>/dev/null || echo 'Not a git repo'
echo '--- Committed changes vs main'
git diff-tree --stat -r main HEAD 2>/dev/null || echo 'No diff available'
echo '--- Uncommitted changes'
git status --short 2>/dev/null || echo 'Not a git repo'
```

**Context files loaded on demand**: `.adlc/context/conventions.md` and `.adlc/context/architecture.md` are loaded by Step 1 below — **skip the Read if they are already in the current conversation** (e.g., when invoked from `/proceed`, which preloads them at Phase 0).

## Input

The scope is the argument: whatever follows `/reflect` in the invocation (on Claude Code it can also arrive as an `ARGUMENTS:` line appended to this text). With none, Step 1 reviews every change on the current branch.

## Prerequisites

Before proceeding, verify that `.adlc/context/conventions.md` exists. If it doesn't, stop and tell the user: "The `.adlc/` structure hasn't been initialized. Run `/init` (`/adlc:init` on the plugin install) first to set up conventions."

## Instructions

### Step 1: Determine Scope
1. If given a REQ ID, find the associated branch and review its changes
2. If given a branch name, review all changes on that branch vs `main`
3. If no argument, review all changes on the current branch vs `main`
4. Get the full diff: `git diff main...HEAD`
5. **Context files**: if `.adlc/context/conventions.md` and `.adlc/context/architecture.md` are NOT already in your conversation context, Read them now. Otherwise skip — they're already loaded.

### Step 2: Dispatch the `reflector` agent
Launch the **reflector** agent via the Agent tool. The agent owns the canonical self-review checklist (Correctness, Convention Compliance, Architecture, Testing, Completeness) and handles reading changed files and cross-referencing lessons learned. Keeping the checklist in the agent ensures a single source of truth that `/proceed` Phase 5 also uses.

If this harness can run subagents, dispatch these agents in parallel; if it cannot, or you are a subagent, run each checklist inline from `.adlc/agents/<name>.md`. Agent names are bare on the symlink install and `adlc:`-prefixed on the plugin install (`adlc:<name>`): before dispatching, check which form the Agent tool lists and use that one, and do not wait for an error, because a name it does not list can silently run a generic agent without the checklist; if neither form is listed, say which agent is missing and run its checklist inline. When `.adlc/agents/` is absent, say that `/init` (`/adlc:init` on the plugin install) vendors it, then read `$ADLC_TOOLKIT_ROOT/agents/<name>.md` (the toolkit root is the parent of this skill's base directory) where your file tool can reach it; never improvise a checklist. An inline run of a review or audit agent is read-only: report findings, apply no fixes, and run no test runner, build tool, package manager or interpreter.

Provide the agent with:
- The scope (REQ ID, branch name, or "current uncommitted changes")
- The full diff from Step 1
- `conventions.md` and `architecture.md` content (from Step 1)

Instruct it: "Read all changed files in full, grep `.adlc/knowledge/lessons/` for applicable lessons, run your checklist, and report findings + questions. Do not apply fixes."

The agent will return:
- **Issues Found** — grouped by severity (Critical / Major / Minor) with file/line, description, suggested fix
- **Clean Areas** — 1-2 sentences on what was checked and looked good
- **Questions for the User** — ambiguities, design tradeoffs, assumptions, deferred edge cases

### Step 3: Present the Agent's Report
Relay the agent's Issues Found and Clean Areas sections to the user verbatim. Do not re-run the checklist yourself — that would duplicate work and risk drift.

### Step 4: Surface Questions from the Agent
The reflector agent returns a "Questions for the User" block covering ambiguous requirements, design tradeoffs, assumptions made, deferred edge cases, and UX/behavioral uncertainties. Relay that block to the user as a numbered list. If the agent returned "No questions — implementation is unambiguous," state that explicitly.

Do not proceed past this step until the user has answered — their responses may change what needs to be fixed.

### Step 5: Fix or Defer
1. If Critical issues are found, fix them immediately
2. If Major issues are found, ask the user whether to fix now or note for `/review` (`/adlc:review` on the plugin install)
3. Minor issues can be listed for the user to decide
4. After fixes, re-run tests to verify nothing broke

### Step 6: Recommend Next Action
- If no issues or only minor ones: "Ready for `/review` (`/adlc:review` on the plugin install)"
- If fixes were applied: "Fixes applied. Re-run `/reflect` to verify, or proceed to `/review` (`/adlc:review` on the plugin install)"
- If blockers remain: "Address these issues before `/review` (`/adlc:review` on the plugin install)"