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

File Resolution:

ls product/index.yaml 2>/dev/null && echo "SPLIT MODE" || echo "V1 MODE"
cat product-context.yaml

• Split mode (product/index.yaml exists): Read product definition from product/index.yaml (what was intended). Read operational state from product-context.yaml (what happened).
• V1 mode: Read everything from product-context.yaml.

If product-context.yaml does not exist, there is nothing to reflect on — run /aep-envision and /aep-map first.

---

Step 1: Gather Feedback

Collect observations from all sources. Read product definition (from product/index.yaml in split mode, product-context.yaml in v1 mode) for what was intended, and product-context.yaml cost section for execution data.

• 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 (the unified severity/category/repro format). 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 for observations captured by workspace agents during builds. Summarize patterns across recent lessons — recurring errors, solutions that worked, missing documentation.

Ask the user one source at a time. Don't rush — the quality of classification depends on the quality of input.

Automated ingestion (optional): Automated sources — error logs, analytics, 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. Automation augments the interactive sources above; it does not replace them — ingested records are merged with the human input before classification, and the human still reviews each classification.

---

Step 2: Classify Each Observation

Every piece of feedback becomes one of:

Bug

Specified behavior that does not work.

• Action: Create a new story in product-context.yaml with priority: high and status: pending in the current layer, route to /aep-dispatch
• Update: Add the story directly to the stories section of the YAML

Refinement

Working behavior that needs improvement — or existing stories that need to move between layers.

• Action: Create a new story in the next layer with status: pending, add to the stories section of product-context.yaml. Alternatively, promote an existing story from a later layer to an earlier one if learning shows it's needed sooner.
• Update: Include appropriate layer assignment and dependencies

Sub-type — Calibration: A gap between "works correctly" and "feels right" in any quality dimension. The code works as specified and the spec was correct, but the result doesn't match what the human actually wanted.

Classification questions for calibration observations:

1. Does the code work as specified? (Yes → not a bug) 2. Was the spec correct? (Yes → not a discovery) 3. Does the result feel right? (No → calibration need) 4. What dimension feels off? (visual-design / ux-flow / api-surface / data-model / scope-direction / copy-tone / performance-quality)

For heavy dimensions (visual-design, ux-flow, copy-tone): create stories in the next .5 alignment layer with calibration_type: <dimension>. Run /aep-calibrate <dimension> before dispatching.

For light dimensions (api-surface, data-model, scope-direction, performance-quality): route to /aep-calibrate <dimension> directly — may create stories in next integer layer or update product context inline. No .5 layer needed.

Discovery

New requirement or invalidated assumption.

• Action: Revisit product context
• If it's a product assumption → update product section via /aep-envision
• If it's an architecture issue → update architecture section via /aep-map
• Update: Mark the affected assumption in the product section as revised

Opportunity Shift

Fundamentally changes the bet — the original opportunity hypothesis is wrong or has shifted.

• Action: Back to /aep-envision Phase 0
• This is rare but critical to recognize. 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. Examples: permission stalls, signal staleness, missing tooling, agent configuration gaps.

• Action: Document the pattern in lessons-learned/process/<observation>.md. Add a process_learnings entry to the topology.routing section of product-context.yaml.
• Important: If the pattern warrants a skill file change, record it as a proposed amendment in the changelog — do not auto-edit skill files. Skill changes are reviewed and applied by a human.
• For systematic capture and upstream routing of process and tech-stack observations — especially when reviewing multiple downstream project runs — use /aep-workflow-feedback which provides a standardized format and downstream→AEP routing.

Present the classification to the user for each observation. Let them override — they know their product better than any framework.

---

Step 2.5: Re-slice the Map

After classifying all feedback, review the current layer assignments. Release lines are pencil marks — they should shift based on what you learned. This is normal iteration, not a sign that something went wrong.

For each layer that has not yet been built:

1. Review story priorities in light of classified feedback. Do any stories need to move to an earlier layer? Are any stories in the next layer no longer relevant? 2. Promote stories from later layers to earlier ones when learning shows they're needed sooner. Demote stories that turned out to be less critical. 3. Add new stories from classified Refinements to the appropriate layer and activity. 4. Update `product-context.yaml` — change layer assignments in the stories section.

Key rule: Re-slicing does NOT require going back to /aep-envision. You only route there when the backbone (user activities) or product framing changes — not when layer assignments shift. See docs/decisions/release-line-adjustments.md for the full decision framework.

---

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:

• If keep_if condition met → record as passed, advance to next layer
• If otherwise triggered → record as failed, recommend re-slicing: promote stories from later layers, adjust backbone if needed

4. Record the result in the changelog:

   - date: YYYY-MM-DD
     type: outcome_evaluation
     summary: "Layer N outcome contract: [passed/failed] — [metric] was [actual] vs target [target]"

Auto-evaluation (optional, opt-in): The pause above can be skipped per references/telemetry-ingestion.md:

• If topology.routing.auto_outcome_eval: quantitative and the success metric is quantitative (a numeric target measurable from analytics/monitoring) → first run coverage_check([metric]) (references/telemetry-ingestion.md §1.5): if the metric isn't bound to a telemetry source (the /aep-map Telemetry Binding step wasn't done), fall back to the human pause and note "run /aep-map observability step". If covered → fetch the actual value per references/telemetry-ingestion.md, apply keep_if/otherwise mechanically, and record the result in the changelog — no pause. (A fetch failure also falls back to the human pause.)
• Qualitative metrics still pause for the human as described above — unless topology.routing.full_auto: true, in which case the agent evaluates the qualitative metric by its own judgment and applies the decision rule with no pause.
• Default (auto_outcome_eval: none, full_auto: false) preserves the current human-in-the-loop behavior exactly.

If no outcome contract exists for the completed layer, skip this step.

---

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?

Record cost observations and any topology adjustment recommendations.

---

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 to the `changelog` section with a full feedback classification entry:

   - date: YYYY-MM-DD
     type: reflection
     summary: "Post-[feature/layer] reflection"
     feedback:
       bugs:
         - description: "..."
           story_id: "fix-xxx"
       refinements:
         - description: "..."
           story_id: "ref-xxx"
           target_layer: N
       discoveries:
         - description: "..."
           affected_section: "product|architecture"
       opportunity_shifts:
         - description: "..."
     cost_observations: "..."

2. Update `stories` section with new stories (bug fixes get priority: high, refinements go to next layer)

3. Update `product` section if assumptions changed (version the changes)

4. Update `topology` section if routing adjustments are needed

5. Validate YAML (see references/yaml-guardrails.md):

   npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

If this fails, fix the YAML before committing. Common fixes: quote list items containing colons, flatten nested sub-lists, escape embedded double quotes.

6. Commit updates:

   # Resolve $BASE (integration branch) — see git-ref "Integration Branch" (override → develop → main)
   BASE=$(git config --get aep.integration-branch 2>/dev/null || true)
   [ -z "$BASE" ] && { git show-ref --verify --quiet refs/heads/develop \
     || git show-ref --verify --quiet refs/remotes/origin/develop; } && BASE=develop
   BASE=${BASE:-main}

   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"

---

Step 5: Decide Next Action

Based on the reflection, recommend the next step:

---

Step 5.5: Workflow Improvement

Review any observations classified as Process in Step 2. For each:

1. Document the pattern in lessons-learned/process/<observation>.md with:

• What happened (description, frequency, impact)
• Root cause (if known)
• Proposed mitigation

2. Update product context — add a process_learnings entry to topology.routing in product-context.yaml:

   process_learnings:
     - pattern: "<description>"
       mitigation: "<what to do differently>"
       discovered_at: "<date>"

3. Propose skill amendments — if the pattern warrants changes to skill files (e.g., adding a guardrail, changing a phase step), record the proposed amendment in the changelog section:

   - date: YYYY-MM-DD
     type: process-improvement
     summary: "Proposed skill amendment: <description>"
     proposed_changes:
       - skill: "<skill name>"
         change: "<what to add/modify>"
         rationale: "<why>"

Do not auto-edit skill files. Skill changes are sensitive — the human reviews and applies proposed amendments.

---

Key Principles

• Without structured feedback ingestion, the system is open-loop — you ship and hope. This phase makes the loop explicit.
• Feedback classification is the decision — the category determines where the feedback routes. Get the classification right and the routing follows.
• Cost data matters from day one — invisible spending is uncontrollable spending. Track it, review it, act on it.
• Version the product context — the history of changes is itself valuable. It shows how understanding evolved.

---

Next Step

Based on the reflection outcome, proceed to one of:

• /aep-dispatch — pick and execute new stories (bugs or refinements enter the dispatch queue)
• /aep-envision — update product assumptions
• /aep-map — update system architecture
• /aep-calibrate — recalibrate a specific quality dimension (visual design, UX flow, API surface, etc.)
• Next layer execution cycle

Orchestration Patterns

Detailed patterns for the control plane's orchestrator — state management, context assembly, layer gating, and failure handling. Read this when setting up or debugging the execution pipeline.

---

Work Graph as State Machine

The work graph is a live state machine. Every story node holds a status and transitions based on events.

State Transitions

pending     → ready        (all dependency stories reach 'completed')
ready       → in_progress  (orchestrator dispatches to agent)
in_progress → in_review    (agent submits PR)
in_review   → completed    (verification passes)
in_review   → in_progress  (verification fails, retry initiated)
in_progress → failed       (retry limit exceeded, escalated)
pending     → blocked      (a dependency story enters 'failed')
any         → deferred     (user explicitly postpones)

Orchestrator Loop

The orchestrator is event-driven, not polling-based:

1. Event received (story completed, PR submitted, verification result, failure). 2. Update state of the affected story in the work graph. 3. Cascade check: Does this transition unlock new stories? (completed → check dependents). Does it block stories? (failed → mark dependents as blocked). 4. Dispatch: For each newly ready story, run conflict detection, assemble context, dispatch to agent per routing rules. 5. Layer check: Are all stories in the current layer completed? If yes, trigger Integration Gate. 6. Alert check: Any cost anomalies? Any critical path blockages? Notify user if needed.

Concurrency Control

• Maximum parallel agents is configurable. Start with 5–10.
• Two stories with overlapping "Files Likely Affected" must not run in parallel — serialize them.
• If two parallel stories produce merge conflicts, the later PR rebases on the merged one and re-verifies.

---

Context Assembly

The Problem Context Assembly Solves

An agent's output quality is directly proportional to the relevance and precision of its input context. Too little context → the agent guesses. Too much context → the agent gets confused or hits token limits. Context assembly is the art of giving each agent exactly what it needs and nothing more.

Assembly Rules

For each agent role, the Agent Topology document defines a context window composition — the ordered list of what goes in. The orchestrator follows this list mechanically:

1. Read the composition spec for the target agent role. 2. Prune the Context Document to the sections listed in the spec. 3. Extract the relevant System Map slice — the story's module and its adjacent interfaces only. Do not include unrelated modules. 4. Collect dependency artifacts — for each completed dependency, extract the public interface (types, exports, API surface). Do not include internal implementation unless the composition spec explicitly requires it. 5. Validate the package — all required fields present, no references to missing artifacts. 6. Measure the package — if it exceeds the target token budget for the role, escalate for manual pruning or split the story.

Common Assembly Failures

• Missing dependency artifact: A dependency is marked completed but its output artifact is not found. This usually means the previous agent's output contract was not enforced. Fix: add post-completion validation in the handoff contract.
• Stale interface contract: The System Map was amended but the context package still references the old version. Fix: always read interface contracts from the latest System Map, not from cached copies.
• Context overflow: The assembled package exceeds the agent's token budget. Fix: either prune more aggressively (summarize dependency artifacts instead of including full source) or split the story into smaller units.

---

Layer Gating

Gate Design

Each layer has an Integration Gate — tests that verify stories work together. The gate is NOT the sum of individual story tests. It tests emergent behavior at integration boundaries.

Layer 0 gate is the most important test in the pipeline. It executes the exact user journey from the Context Document's Layer 0 MVP Contract. If the walking skeleton doesn't work end-to-end, something is architecturally wrong.

Subsequent layer gates test:

1. All previous layer journeys still work (regression). 2. New capabilities added in this layer work end-to-end. 3. Interface contracts honored under realistic conditions (not just mocks).

Gate Failure Protocol

Gate fails
  → Identify failure boundary (which module interface)
  → Check: implementation vs contract mismatch?
     → Implementation wrong: create fix story → Phase 4
     → Contract wrong: trigger Architecture Review → Phase 2
        → Assess impact on completed stories
        → May require re-execution of affected stories

Gate failure on a contract issue is the most expensive failure in the pipeline because it can invalidate already-completed work. This is why Phase 2 (System Map approval) is a human-reviewed gate — catching contract errors early prevents cascading rework.

---

Failure Handling

Why Fresh-Agent Retry Works

When an agent fails and retries, it carries the full reasoning trajectory from its first attempt. If that trajectory led to a dead end, the retry often follows the same path — the agent is stuck in its own logic. A fresh agent receives only the structured failure log, not the reasoning. It approaches the problem without the stuck trajectory.

The failure log's "what was NOT tried" field is the highest-value signal for the fresh agent. It provides starting points the previous agent considered but did not explore.

Failure Log Schema

{
  story_id: string,
  attempt_number: number,
  agent_role: string,

  approach_summary: string,     // What the agent tried to do
  failure_point: string,        // Which verification step failed
  error_output: string,         // Exact error messages or test failures
  hypothesis: string,           // Agent's best guess about root cause
  not_tried: string[],          // Alternative approaches considered but not attempted

  context_issues?: string,      // Any problems with the context package
  time_spent_seconds: number,
  tokens_used: number
}

Cascade Prevention

When a story fails:

1. Mark direct dependents as blocked. 2. Continue executing non-blocked stories in the same layer. 3. If the failed story is on the critical path → alert user immediately (entire layer is blocked). 4. If NOT on critical path → other work continues. User addresses failure asynchronously. 5. When the failed story is eventually resolved (fixed or deferred), unblock dependents and resume normal dispatch.

Escalation Format

When a story reaches human escalation, present:

1. The story spec (what was being attempted). 2. All failure logs from all attempts (what happened). 3. The fresh agent's failure log specifically (the most informed analysis). 4. Current impact: which stories are blocked, is this on the critical path? 5. Suggested options: fix the story, simplify the story, defer it, or modify the architecture.

---

State Persistence

The orchestrator's state must survive crashes.

Storage Options

• File-based (JSON in repo): Simple, version-controlled. Sufficient for most MVP projects. Limitation: does not support concurrent orchestrators.
• SQLite: Supports querying ("show all failed stories") and concurrent access. Better for larger projects.
• External store (Redis, Postgres): For production-grade orchestration with multiple concurrent sessions.

For MVP-stage projects, start with JSON in the repo. Upgrade when the limitation matters.

State Snapshot Schema

{
  project_id: string,
  current_layer: number,
  stories: {
    [story_id]: {
      status: "pending" | "ready" | "in_progress" | "in_review" | "completed" | "failed" | "blocked" | "deferred",
      assigned_agent?: string,
      attempt_count: number,
      last_updated: ISO8601,
      failure_logs?: FailureLog[],
      pr_url?: string,
      completed_at?: ISO8601
    }
  },
  layer_gates: {
    [layer_number]: {
      status: "not_started" | "running" | "passed" | "failed",
      test_results?: TestResult[],
      completed_at?: ISO8601
    }
  },
  cost_summary: {
    total_cost_usd: number,
    cost_by_layer: { [layer]: number },
    cost_by_role: { [role]: number },
    cost_by_story: { [story_id]: number }
  },
  last_updated: ISO8601
}

State Inspection

The user should be able to query the current state at any time:

• Progress per layer: completed / in_progress / pending / failed / blocked
• Critical path status: what is the next bottleneck?
• Cost breakdown: where is the money going?
• Blocked stories: what is waiting on what?

Provide a simple CLI command or dashboard that reads the state file and renders this overview.

Telemetry Ingestion & Outcome Auto-Evaluation

How /aep-reflect (and /aep-watch) pull real-world signals automatically, and how a layer's quantitative outcome contract is evaluated without a human. This augments the interactive reflect flow — it never replaces human review by default. (Gap G5.)

Authoring note: this file is canonical in

skills/product-context/_shared/references/; scripts/build-skills.sh

materializes it into each consuming skill's references/.

---

1. Automated source ingestion

Pull from read-only sources with bash/curl/jq and reduce each to the normalized observation record the reflect Step 2 classifier consumes:

{
  "source": "error_stream | analytics | monitoring | bug_tracker | dogfood",
  "signal": "one-line description of what was observed",
  "evidence": "url | query | sample (no secrets)",
  "story_ref": "<story-id if attributable, else null>",
  "suggested_class": "bug | refinement | discovery | opportunity_shift | process | null"
}

suggested_class is a hint only — the reflect Step 2 classifier (and the human, unless full_auto) makes the final call. Ingested records are merged with interactive input before classification; automation augments, never replaces.

Source config

Endpoints live under topology.routing.telemetry_sources (a list). Each entry:

telemetry_sources:
  - kind: error_stream # error_stream | analytics | monitoring | bug_tracker
    endpoint: "https://…/api/…?since={since}" # {since} = last-ingest high-water mark
    token_env: SENTRY_TOKEN # NAME of an env var / secret — never the secret itself
    metric_map: # for analytics/monitoring: outcome-metric name → query
      activation_rate: "SELECT … "

Safety: access is read-only; reference credentials by env-var / secret-store name only — never embed secrets in the repo or in `product-context.yaml`.

Dogfood-report adapter (dogfood_report source)

Dogfood runs — local (/aep-build Phase 6), post-deploy (autopilot post-merge guard), or a standalone / ad-hoc live exercise — emit the unified markdown report (## <title> / **Severity:** / **Category:** / **Repro:** / **Observed:** / **Expected:** / **Evidence:**) to .dev-workflow/dogfood-*.md (see patterns/executor/references/dogfood-validation.md → Unified report format). This adapter parses each ## finding into the `/aep-watch` Step 1 finding record (the operative shape Step 3 dedupes and Step 4 turns into a story — _not_ the 5-field telemetry record above, which is the classifier's conceptual input) so the same Step 2 classifier consumes it — closing the G6 self-feeding loop for every dogfood trigger, not just the guard path. It is a file glob, not a network source: self-describing, so coverage_check (§1.5) does not gate it.

Source config (the discriminator key matches the container: type: under watch.sources[], kind: under telemetry_sources[]):

watch:
  sources:
    - type: dogfood_report
      glob: ".dev-workflow/dogfood-*.md" # default; add post-deploy report paths as needed

Per-finding mapping (markdown field → finding field):

suggested_class is a hint only — the Step 2 classifier (and the human, unless full_auto) makes the final call, exactly as for every other source. In particular a finding that reads as calibration / discovery / opportunity-shift / process is not auto-filed; it surfaces to a human (see /aep-watch Step 2).

No high-water mark — dedupe-only. The unified report has no per-finding timestamp, so a dogfood_report source does not advance watch.since (that cursor applies only to time-ordered sources); re-scanning the glob each tick is harmless because idempotency rests entirely on the stable dedupe key. Each finding gets a deterministic external_id = "dogfood:" + slug(report-basename) + ":" + shorthash(slug(title) + "|" + category), so /aep-watch Step 3 dedupes on watch_origin.{source,external_id}: already-filed findings no-op, and a genuinely new finding (new title/category) yields a new id and a new story. The autopilot post-merge guard Path 1 stamps the same external_id on the story it files, so whichever path ingests a given report first wins and the other no-ops — no double-filing.

---

1.5 Deciding which sources to wire (the coverage rule)

You don't list telemetry for its own sake — a source is needed _iff_ some declared signal requires it. The decision is hybrid:

1. Metric-driven (what signals do we need?) — enumerate every quantitative success_metric across product.layers[].outcome_contract plus every topology.routing.post_merge_guard.health_signals entry. That set _is_ the demand for telemetry. 2. Inventory (which tool provides each?) — /aep-scaffold's audit detects the project's observability stack (Sentry, Datadog, PostHog, OpenTelemetry, log drains, /healthz-style endpoints) and records candidate telemetry_sources (kind + endpoint + token_env, no metric_map yet); you can also add candidates by hand. 3. Bind (`/aep-map`) — for each needed signal, attach it to a candidate source by adding a metric_map: { <metric-or-signal>: "<query>" } entry. A needed signal with no measurable source is flagged, not ignored: make the metric qualitative, or record it unmeasured — never leave a quantitative metric silently un-sourced.

coverage_check(needed) — the guard helper

Consumers that rely on telemetry (/aep-watch, /aep-reflect Step 2.75, /aep-autopilot) call this before trusting auto behavior. It is pure config inspection — no network:

coverage_check(needed_signals):
  missing = []
  for sig in needed_signals:           # quantitative success_metric names + health_signals
    if no telemetry_sources[*].metric_map has key == sig
       (and, for a health_signal, no source/endpoint provides it):
      missing.append(sig)
  return { covered: missing == [], missing }

On `covered == false`: surface "telemetry binding incomplete for <missing> — run /aep-map (observability step)" and block the auto path (watch refuses to claim auto-coverage; reflect falls back to the human pause; autopilot pauses). Missing wiring must block auto, never silently no-op — that's the v2 human-in-the-loop default.

---

2. Outcome-contract auto-evaluation

A layer's outcome_contract carries a success_metric (type + target) and a decision_rule (keep_if / otherwise). Precondition: run coverage_check([success_metric]) (§1.5) first — if the metric isn't bound to a source, take the human-pause path (the binding is incomplete; do not auto-eval). When covered, evaluate per topology.routing.auto_outcome_eval:

On a fetch failure or ambiguity, fall back to the human pause (fail safe, not fail open). Record every auto-evaluation in the changelog:

- date: YYYY-MM-DD
  type: outcome_evaluation
  summary: "Layer N: <metric> = <actual> vs target <target> → passed|failed (auto)"

---

3. full_auto interaction (A1)

topology.routing.full_auto (default false) is the master switch. It only changes the qualitative path:

Default keeps humans in the loop; only an explicit full_auto: true removes the qualitative pause.

---

Cross-references

• /aep-reflect Step 1 (Gather Feedback) and Step 2.75 (Evaluate Outcome Contracts)
• /aep-watch (reuses the normalized observation record for its ingest step)
• aep-autopilot references/tick-protocol.md — Step ⑥ Layer Completion (what the

auto-eval lets advance without a pause)

YAML Guardrails for product-context.yaml

Every skill that writes to product-context.yaml must validate the file before committing. Invalid YAML silently breaks the dashboard and blocks all downstream consumers.

Validation Command

Run this after every edit to product-context.yaml:

npx js-yaml product-context.yaml > /dev/null && echo "YAML OK"

If the project has the @agentic-engineering-patterns/api package, use the actual loader for deeper validation (Zod schema + preprocessing):

npx tsx -e "
  const { loadProductContext } = require('@agentic-engineering-patterns/api/lib/product-context-loader');
  loadProductContext(process.env.PRODUCT_CONTEXT_PATH || './product-context.yaml');
  console.log('YAML + schema OK');
"

If validation fails, fix the YAML before committing. Do not commit broken YAML under any circumstances.

Common YAML Pitfalls in product-context.yaml

These are the patterns that most frequently break the parser when agents write to the file.

1. List items ending with a colon

A trailing colon makes YAML interpret the item as a mapping key. If the next lines are indented, YAML expects a value — and fails.

# BROKEN — YAML treats this as a mapping key
acceptance_criteria:
  - Generate page redesigned for multi-step video workflow:
    - Intent prompt input
    - Multi-step progress display

# FIXED — quote the entire item, flatten sub-items
acceptance_criteria:
  - "Generate page redesigned for multi-step video workflow: intent prompt input, multi-step progress display"

Rule: Never end a list item with : followed by indented sub-items. Either quote the item or flatten the sub-list.

2. Embedded double quotes inside list items

YAML interprets "text" as a quoted string boundary. Content after the closing quote is invalid.

# BROKEN — YAML sees "Complete Your Profile" as the full string, then chokes on the rest
- "Complete Your Profile" guard includes link to /profile

# FIXED — wrap in double quotes, use single quotes inside
- "'Complete Your Profile' guard includes link to /profile"

# ALSO FIXED — escape inner quotes
- "\"Complete Your Profile\" guard includes link to /profile"

Rule: If a list item contains embedded double quotes, wrap the entire value in double quotes and use single quotes (or escaped quotes) inside.

3. Colons in the middle of list items

A colon followed by a space (: ) triggers YAML key-value parsing.

# BROKEN — YAML tries to parse "Dashboard" as a key
- Dashboard: creator dashboard showing recent generations

# WORKS (preprocessor handles this) — but quoting is safer
- "Dashboard: creator dashboard showing recent generations"

Rule: The preprocessYaml function in the loader auto-quotes most of these, but when writing new content, prefer explicit quoting for items containing : .

4. Special characters: @, {, }

# BROKEN — @ is a YAML tag indicator, { starts a flow mapping
- @mention the user
- Use {variable} interpolation

# FIXED
- "@mention the user"
- "Use {variable} interpolation"

Rule: Quote list items containing @, {, or }.

5. Nested sub-lists under string items

YAML list items are scalar values — they cannot have children unless the item is a mapping key.

# BROKEN — a string item cannot have sub-items
- Main feature description
  - Sub-feature A
  - Sub-feature B

# FIXED — flatten into one item or use a mapping structure
- "Main feature description: Sub-feature A, Sub-feature B"

Pre-commit Checklist

Before committing any change to product-context.yaml:

1. Run the validation command above 2. If adding acceptance_criteria, description, or any free-text list: scan for colons, quotes, and special characters 3. If the validation command is not available (e.g., no Node.js), at minimum review list items for the patterns above