aep-workflow-feedback

Workflow Feedback

A reusable pattern for capturing workflow observations in downstream projects and routing them upstream to improve AEP skills and documentation.

Two modes:

• Capture — run in a downstream project after builds to standardize observations.
• Review — run in the AEP repo to pull and route upstream candidates from downstreams.

DOWNSTREAM PROJECT                           AEP REPO
━━━━━━━━━━━━━━━━━━                           ━━━━━━━━
/aep-build → lessons.md                          /aep-workflow-feedback review
/aep-wrap  → lessons-learned/                      ↓
/aep-workflow-feedback capture                   Read .aep/config.yaml
  ↓                                            ↓
.dev-workflow/feedback.md  ──────────────→   Route to docs/
  (standardized + classified)                  ↓
                                             Human approves
                                               ↓
                                             tag release → re-pin downstreams ──→ updated skills flow back

Session: Main, interactive with user.

Hard guardrail — this skill never edits AEP skill files. In either mode, propose amendments in the feedback/lesson file; a human applies them upstream via a deliberate re-pin.

---

Mode 1: Capture

Run this in a downstream project after completing a layer, a batch of stories, or an autopilot run. The goal is to standardize raw observations into a format AEP can review.

Step 1 — Gather sources

Collect observations from all available sources, including AEP skill/process behavior, not only product bugs (product-specific bugs go to /aep-reflect → story creation, not here):

1. Archived lessons: lessons-learned/*.md (written by /aep-wrap)
2. Process lessons: lessons-learned/process/*.md (from /aep-reflect)
3. Unarchived workspace lessons: .feature-workspaces/*/dev-workflow/lessons.md (if workspaces not yet wrapped)
4. User observations: Ask the user what they noticed during the run that isn't captured above.

Postcondition: each user observation is recorded in the feedback file (Step 3), or the user explicitly confirms there were none.

Step 2 — Classify each observation

Assign each observation a classification:

Classification	Description	Upstream?
process	AEP workflow improvement — a skill, phase, or gate should change	Yes
tech-stack	Technology-specific gotcha — applies to any project using this tech	Yes
discovery	New understanding about the product domain or architecture	Maybe
project-local	Specific to this project's codebase, not generalizable	No

Mark upstream_candidate: yes only for items that would benefit other projects using AEP. Postcondition: every observation carries a classification.

Step 3 — Write standardized feedback

Write to .dev-workflow/feedback.md:

# Workflow Feedback: <project> <layer/context>

Date: YYYY-MM-DD
Project: <name>
Layer: <layer>
Stories: <count>

## Observations

### <title>

- **Classification:** process | tech-stack | discovery | project-local
- **Skill affected:** /aep-calibrate, /aep-build, /aep-autopilot, etc. (if applicable)
- **Technology:** Rust, Cloudflare, etc. (if tech-stack)
- **Observation:** <what happened>
- **Recommendation:** <proposed change>
- **Upstream candidate:** yes | no

Postcondition: .dev-workflow/feedback.md exists with one Observations entry per gathered observation.

Step 4 — Commit

Commit .dev-workflow/feedback.md to the downstream project, making it available for AEP review mode. Postcondition: git status shows .dev-workflow/feedback.md committed.

---

Mode 2: Review

Run this in the AEP repo to pull feedback from downstream projects and route it into AEP documentation.

Step 1 — Scan downstreams

Read .aep/config.yaml to find registered downstream project paths. For each project:

1. Check for .dev-workflow/feedback.md (standardized feedback from Capture mode).
2. If no feedback.md exists, check lessons-learned/**/*.md (raw lessons from builds) — feedback may be incomplete, so read these directly when present.

If a downstream has no feedback file, note it and move on. Postcondition: every registered downstream is either scanned or noted as having no feedback.

Step 2 — Filter upstream candidates

Pull observations that are:

• Marked upstream_candidate: yes, or
• Classified process or tech-stack (almost always upstream-relevant), or
• Classified discovery only when they reveal a pattern applicable beyond one project.

Pull project-local items only when the human explicitly requests it.

Step 3 — Route items

For each upstream candidate, determine the destination, noting which AEP skills a process observation affects:

Classification	Destination	Format
process	docs/lessons/YYYY-MM-DD-<project>-<context>.md	Date-prefixed lesson with skill amendment notes
tech-stack	docs/tech-stack/<technology>-<topic>.md	Standalone tech gotcha doc
discovery	Present to human for decision	May go to docs/decisions/ or docs/workflow/

Step 4 — Present summary

Show the human a table of every upstream candidate — including minor ones — with proposed routing:

| # | Source | Classification | Title | Proposed destination |
|---|--------|---------------|-------|---------------------|
| 1 | <project> | process | /aep-calibrate should modify real components | docs/lessons/... |
| 2 | <project> | tech-stack | Rust keyring needs platform features | docs/tech-stack/... |

The human approves, modifies, or rejects each item.

Step 5 — Write approved items

For each approved item, create the target file following the conventions in docs/README.md. Record proposed skill amendments inside the lesson/decision file (per the hard guardrail above) for a human to apply.

After writing, remind the human that approved skill improvements reach downstream projects only via a deliberate re-pin: cut a new AEP release tag, then re-pin each downstream registered in .aep/config.yaml per the README "Upgrading to a new release" flow. Postcondition: each approved item exists as a file under docs/.

---

When to Use This Skill

Situation	Mode
Just finished a layer in a downstream project	Capture
Autopilot run completed, want to capture learnings	Capture
/aep-reflect identified process observations	Capture
Time to review what downstream projects have learned	Review
Preparing an AEP release with accumulated improvements	Review

Relationship to adjacent skills: /aep-reflect classifies product feedback (bugs, refinements, discoveries, polish); this skill handles the process and tech-stack observations it surfaces but doesn't route upstream. /aep-wrap archives workspace lessons to lessons-learned/ and /aep-build writes raw observations to .dev-workflow/lessons.md — Capture reads both. /aep-autopilot's orchestration-learning.md captures meta-patterns across workspaces that Review can pull upstream.