# Aep Reflect > Classifies post-ship feedback and routes it to the story graph, architecture, or hypothesis. Use after /aep-wrap or user testing, or for "what did we learn". - Skill: `memorysaver/aep-reflect` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add memorysaver/aep-reflect` - Raw SKILL.md: https://api.skillmd.com/api/skills/memorysaver/aep-reflect/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: memorysaver (https://skillmd.com/u/memorysaver) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/memorysaver/aep-reflect --- # Reflect Close the feedback loop. Transform real-world observations into actionable changes to the product context — the story graph, the architecture, or even the opportunity hypothesis. **Where this fits:** ``` /aep-envision → /aep-map → /aep-scaffold → [ /aep-design → /aep-launch → /aep-build → /aep-wrap ] → /aep-reflect ▲ you are here ``` **Session:** Main, interactive with user **Input:** Observations after shipping (user testing, error logs, cost data, product instincts) **Output:** Classified feedback + updated `product-context.yaml`; if product intent changed, also updated `product/index.yaml` (split mode) --- ## Before Starting Mode semantics (split vs v1 vs new-project) are canonical in `references/file-resolution.md` — run the probe there. Reflect reads the product definition from `product/index.yaml` (split) or `product-context.yaml` (v1) for what was intended, and reads operational state (`cost`, `stories`, `changelog`) from `product-context.yaml` for what happened. It writes operational changes to `product-context.yaml`; product-intent changes go to `product/index.yaml` (split) or `product-context.yaml` (v1). If neither file exists there is nothing to reflect on — run `/aep-envision` then `/aep-map` first. --- ## Step 1: Gather Feedback Collect observations from all sources: - **User testing:** What worked? What confused people? What was missing? - **Error logs / monitoring:** Runtime failures, performance issues, unexpected behavior - **Cost data:** Review the `cost` section of `product-context.yaml`. If agent execution traces exist, review per-story costs. Which story types were expensive? Where did retries concentrate? - **Product instincts:** After seeing the thing work, what does the user's gut say? What feels right, what feels off? - **Dogfood reports:** Read `.dev-workflow/dogfood-*.md`. Normalize each `##` finding via the `dogfood_report` adapter (`references/telemetry-ingestion.md` → Dogfood-report adapter) into the same observation record Step 2 classifies — the same source `/aep-watch` ingests headlessly. - **Lessons learned:** Read `lessons-learned/*.md` (observations captured by workspace agents during builds); summarize recurring errors, solutions that worked, missing documentation. - **Layer distillations:** Read `lessons-learned/distillations/*.yaml` — the proposal-only synthesis written by `/aep-wrap` Reflect and Advance when a layer completes. Normalize each item via the `distillation` adapter (`references/telemetry-ingestion.md` → Distillation adapter): `refinements` → refinement (with `target_layer`), `skill_amendments` → process (proposed, never auto-applied), `weak_areas` → discovery/refinement. **Automated ingestion (optional):** Error logs, analytics, and monitoring can be pulled in directly per `references/telemetry-ingestion.md`, normalized into the same observation format Step 2 classifies. Configure endpoints under `topology.routing.telemetry_sources`. Ingested records merge with human input before classification, and the human still reviews each classification. **Postcondition:** every source above is reviewed and its findings normalized into observation records for Step 2 (or the source is explicitly empty this cycle). --- ## Step 2: Classify Each Observation Every piece of feedback becomes exactly one of the five categories below. Present each classification to the user and let them override — they know their product better than any framework. This section is the canonical classifier; `/aep-watch` applies it headlessly. ### Bug Specified behavior that does not work. - **Action:** Add a new story directly to the `stories` section of `product-context.yaml` with `priority: high` and `status: pending` in the current layer; route to `/aep-dispatch`. ### Refinement Working behavior that needs improvement — or existing stories that need to move between layers. - **Action:** Add a new story to the `stories` section in the next layer with `status: pending` (include layer assignment and dependencies). Alternatively, promote an existing story from a later layer to an earlier one if learning shows it is needed sooner. **Sub-type — Calibration:** a gap between "works correctly" and "feels right." The code works as specified and the spec was correct, but the result doesn't match what the human wanted. Confirm: does the code work as specified (yes → not a bug)? Was the spec correct (yes → not a discovery)? Does the result feel right (no → calibration)? Which dimension is off (visual-design / ux-flow / api-surface / data-model / scope-direction / copy-tone / performance-quality)? Route by the dimension's weight — the heavy/light split is canonical in `/aep-map` `references/alignment-layers.md`: - **Heavy** dimensions: create stories in the next `.5` alignment layer with `calibration_type: `; run `/aep-calibrate ` before dispatching. - **Light** dimensions: route to `/aep-calibrate ` directly — it may create stories in the next integer layer or update product context inline. No `.5` layer needed. ### Discovery New requirement or invalidated assumption. - **Action:** Revisit product context. A product assumption → update the `product` section via `/aep-envision` (mark the affected assumption as revised). An architecture issue → update the `architecture` section via `/aep-map`. ### Opportunity Shift Fundamentally changes the bet — the original opportunity hypothesis is wrong or has shifted. - **Action:** Back to `/aep-envision` Phase 0. Signs: the problem you're solving isn't the problem users actually have, or a market shift made the opportunity moot. ### Process Observations about the workflow itself, not the product (permission stalls, signal staleness, missing tooling, agent-config gaps). - **Action:** Document the pattern in `lessons-learned/process/.md` (what happened — description, frequency, impact; root cause if known; proposed mitigation). Add a `process_learnings` entry (`pattern`, `mitigation`, `discovered_at`) to `topology.routing` in `product-context.yaml`. - **Skill amendments:** If the pattern warrants a skill-file change, record it as a proposed amendment in the `changelog` — `type: process-improvement`, `summary`, and `proposed_changes` (`skill`, `change`, `rationale`). Skill files are reviewed and applied by a human; the classifier proposes amendments, never edits skill files. - **Upstream routing:** For systematic capture of process and tech-stack observations across multiple downstream runs, use `/aep-workflow-feedback` (standardized format + downstream→AEP routing). **Postcondition:** every observation carries exactly one user-confirmed category and its routing action is recorded — a story appended to `stories`, a `product`/`architecture` update queued, or a `process_learnings`/amendment entry written. --- ## Step 2.5: Re-slice the Map After classifying all feedback, review the current layer assignments. Release lines are pencil marks — they shift based on what you learned. For each layer not yet built: review story priorities against the classified feedback; promote stories from later layers when learning shows they're needed sooner and demote ones that turned out less critical; add new stories from classified Refinements to the appropriate layer; update the `layer` assignments in the `stories` section of `product-context.yaml`. **Key rule:** Re-slicing does not require going back to `/aep-envision` — you route there only when the backbone (user activities) or product framing changes, not when layer assignments shift. See `docs/decisions/release-line-adjustments.md` for the full framework. **Postcondition:** `layer` assignments in `stories` reflect the classified feedback (or are unchanged because nothing moved). --- ## Step 2.75: Evaluate Outcome Contracts If the completed layer has an `outcome_contract` defined in `product.layers[]`: 1. **Present the hypothesis** to the user: "The hypothesis was: [hypothesis]. The success metric was: [type] [target]." 2. **Ask for evaluation** — outcome contracts are not automated tests; they may require user testing, analytics review, or qualitative assessment. 3. **Apply the decision rule:** `keep_if` condition met → record as passed, advance to the next layer; `otherwise` triggered → record as failed, recommend re-slicing (promote stories from later layers, adjust backbone if needed). 4. **Record the result** in the `changelog` — `type: outcome_evaluation`, `summary` noting passed/failed with the metric, actual value, and target. **Auto-evaluation (optional, opt-in):** the pause can be skipped when the metric is telemetry-bound. See `references/telemetry-ingestion.md` for the `topology.routing.auto_outcome_eval` modes: `quantitative` runs the `coverage_check` gate (§1.5) and, if the metric is bound to a source, fetches the actual value and applies `keep_if`/`otherwise` mechanically; an unbound metric or a failed fetch falls back to the human pause. Qualitative metrics still pause — unless `topology.routing.full_auto: true`, where the agent evaluates by its own judgment. Default (`auto_outcome_eval: none`, `full_auto: false`) preserves the human-in-the-loop pause exactly. If no outcome contract exists for the completed layer, skip this step. **Postcondition:** the outcome result is recorded in the `changelog` as passed or failed, or the step was skipped because `product.layers[]` had no `outcome_contract`. --- ## Step 3: Cost Review Review the `cost` section of `product-context.yaml` along with any execution traces from `.dev-workflow/`: - **Which story types are consistently expensive?** Could they benefit from more precise context assembly, simpler decomposition, or a different agent role? - **Where did retries concentrate?** Patterns in failure suggest either ambiguous specs or incorrect module boundaries. - **Is the agent topology efficient?** Does the routing policy need adjustment? **Postcondition:** cost observations and any topology-adjustment recommendations are captured for Step 4 (as `cost_observations` in the reflection `changelog` entry and/or `topology` edits) — or recorded as an explicit "none this cycle." --- ## Step 4: Update Product Context Based on the classified feedback, update the appropriate file: operational changes (new stories, architecture amendments, topology, cost, changelog) → `product-context.yaml`; product-intent changes (opportunity shift, persona change, goals, mvp_boundary, layers, activities) → `product/index.yaml` (split mode) or `product-context.yaml` (v1 mode). 1. **Append a `changelog` entry** per the product-context schema — `date`, `type: reflection`, `summary`, and a `feedback` map holding `bugs` (`description`, `story_id`), `refinements` (`description`, `story_id`, `target_layer`), `discoveries` (`description`, `affected_section`), and `opportunity_shifts` (`description`), plus `cost_observations`. 2. **Update the `stories` section** with new stories (bug fixes get `priority: high`, refinements go to the next layer). 3. **Update the `product` section** if assumptions changed (version the changes). 4. **Update the `topology` section** if routing adjustments are needed. 5. **Validate YAML** (see `references/yaml-guardrails.md` for the full checklist and common fixes): ```bash npx js-yaml product-context.yaml > /dev/null && echo "YAML OK" ``` Fix any error before committing. 6. **Commit** per `/aep-git-ref` "Control-Plane Commits" (resolve `$BASE` per `/aep-git-ref` "Resolving `$BASE`"): ```bash git pull --ff-only origin "$BASE" git add product-context.yaml product/ git commit -m "chore: reflect — classify feedback and update product context" git push origin "$BASE" ``` **Postcondition:** `npx js-yaml` printed `YAML OK` and `git push` exited 0. --- ## Step 5: Decide Next Action Based on the reflection, recommend the next step: | Feedback type | Next action | | ------------------------ | --------------------------------------------------------------------------------- | | Only bugs | Fix stories added to YAML → `/aep-dispatch` → `/aep-design` → `/aep-build` | | Refinements | Next layer stories added to YAML → `/aep-dispatch` → `/aep-design` → `/aep-build` | | Discovery (product) | `/aep-envision` to update assumptions | | Discovery (architecture) | `/aep-map` to update system map | | Opportunity shift | `/aep-envision` Phase 0 (re-validate) | | Calibration (heavy) | `.5` alignment stories created → `/aep-calibrate ` → `/aep-dispatch` | | Calibration (light) | `/aep-calibrate ` (inline) → stories may update → `/aep-dispatch` | | All clear | Next layer or ship to production | **Postcondition:** a next action from the table is recommended to the user.