---
name: gdd-reflect
description: "Run design-reflector on demand - produces .design/reflections/<cycle-slug>.md with improvement proposals. Review proposals with {{command_prefix}}apply-reflections."
argument-hint: "[--dry-run] [--cycle <slug>]"
tools: Read, Write, Task
---

@reference/retrieval-contract.md

# {{command_prefix}}reflect

Run `design-reflector` on demand against the current (or specified) cycle. Produces `.design/reflections/<cycle-slug>.md` with numbered improvement proposals. Every proposal requires explicit user review - nothing is auto-applied.

## Steps

1. **Parse args**: extract `--dry-run` flag and `--cycle <slug>` value.

2. **Resolve cycle slug**:
   - If `--cycle <slug>` given: use that slug directly
   - Else: read `.design/STATE.md`, extract the active `cycle:` ID from the `<position>` block
   - If STATE.md not found: abort with "No .design/STATE.md found. Run `{{command_prefix}}new-project` first."

3. **Build required-reading list**:
   ```
   .design/STATE.md
   .design/DESIGN-VERIFICATION.md
   .design/learnings/*.md (glob)
   .design/telemetry/costs.jsonl
   .design/agent-metrics.json
   .design/learnings/question-quality.jsonl
   .design/cycles/<slug>/CYCLE-SUMMARY.md
   .design/authority-report.md
   ```
   Use the resolved slug where `<slug>` appears.

3.5. **Optional: capability-gap pre-scan** (Phase 29 Plan 02; runs only if `.design/config.json.reflector.capability_gap_scan_enabled !== false`):
   See @skills/reflect/procedures/capability-gap-scan.md for the full procedure.
   The `design-reflector` agent runs the scan automatically as part of its reflection pass; this step lets users dry-run it independently with:
   ```
   node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/reflector/capability-gap-scan.cjs" --dry-run
   ```
   The scan emits `capability_gap` events (`source: "reflector_pattern"`) for recurring patterns lacking a dedicated executable owner; Plan 29-03 aggregates these for `{{command_prefix}}apply-reflections`.

4. **Spawn design-reflector**:
   ```
   Task("design-reflector", """
   <required_reading>
   @.design/STATE.md
   @.design/DESIGN-VERIFICATION.md
   @.design/agent-metrics.json
   @.design/telemetry/costs.jsonl
   @.design/learnings/question-quality.jsonl
   </required_reading>

   Cycle slug: <slug>
   Dry-run: <true|false>

   Produce .design/reflections/<slug>.md with all reflection sections and proposals.
   If dry-run is true, print proposals to stdout only — do not write the file.
   """)
   ```

5. **After completion**:
   - If `--dry-run`: print the agent output directly; skip steps below
   - Else: read `.design/reflections/<slug>.md`
   - Count proposals by type (scan for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`)
   - Print summary:
     ```
     Reflection complete — cycle: <slug>
     Proposals: N total
       [FRONTMATTER] N
       [REFERENCE] N
       [BUDGET] N
       [QUESTION] N
       [GLOBAL-SKILL] N

     Review and apply: {{command_prefix}}apply-reflections
     ```

## Do Not

- Do not auto-apply any proposal.
- Do not modify agent files, reference files, or budget.json.
- Do not run the full audit pipeline - this is a standalone reflection run.
- Do not bypass the threshold knob. The default `reflector.capability_gap_threshold: 3` exists to suppress noise; do NOT lower it below 1.