/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.

# 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)"