ui/_docs/06_metrics/retro_2026-05-12.md

# Retrospective — 2026-05-12

**Mode**: cycle-end (autodev existing-code Step 17)
**Scope**: Phase B, cycle 1 (`state.cycle = 1`)
**Epic**: AZ-447 (`01-testability-refactoring`)
**Cycle duration**: 2 batches over 1 working day (2026-05-11)
**Previous retro**: N/A — first retrospective for this project

## Implementation Summary

| Metric | Value |
|--------|-------|
| Total tasks | 2 (AZ-485, AZ-486) |
| Total batches | 2 (batch 09, batch 10) |
| Total complexity points | 10 (5 + 5) |
| Avg tasks per batch | 1 |
| Avg complexity per batch | 5 |
| Source files mutated | 28 production + 23 test/colocated + 3 scripts + 4 docs (across both batches) |

Source: `implementation_report_refactor_phase_b_cycle1.md` + `batch_09_report.md` + `batch_10_report.md`.

## Quality Metrics

### Code Review Results

| Verdict | Count | Percentage |
|---------|-------|-----------|
| PASS | 2 | 100 % |
| PASS_WITH_WARNINGS | 0 | 0 % |
| FAIL | 0 | 0 % |

*Cumulative review (K=3 trigger) did NOT fire — cycle had only 2 batches.* Next cumulative review window opens at cycle 2 / batch 3.

### Findings by Severity

| Severity | Count |
|----------|-------|
| Critical | 0 |
| High | 0 |
| Medium | 0 |
| Low | 0 |

### Findings by Category

| Category | Count | Top Files |
|----------|-------|-----------|
| Bug | 0 | — |
| Spec-Gap | 0 | — |
| Security | 0 | — |
| Performance | 0 | — |
| Maintainability | 0 | — |
| Style | 0 | — |
| Scope | 0 | — |

## Structural Metrics

Source: `_docs/06_metrics/structure_2026-05-12.md`.

| Metric | Value | Delta vs baseline (Phase A close) |
|--------|-------|-----------------------------------|
| Component count | 12 | 0 |
| Public-API barrels | 11 / 11 (100 %) | +11 (F4 closed) |
| Commit-time static gates | 31 / 31 PASS | +2 (STC-ARCH-01, STC-ARCH-02) |
| Architecture cycles | 0 | 0 (held) |
| Documented feature→feature edges | 1 (F2 grandfathered through barrel) | 0 |
| Architecture findings open (baseline F1–F9) | 7 of 9 | **−2** (F4, F7 resolved) |
| Newly introduced architecture violations | 0 | 0 |
| Net architecture delta this cycle | **−2** (improvement) | — |
| Wire-contract assertions (`endpoints.test.ts`) | 36 | +36 (new contract surface) |
| Fast-profile suite | 209 PASS / 13 SKIP / 0 FAIL | +46 (+42 this cycle on top of +4 from batch 9) |

### Auto-lesson triggers (per skill Step 1)

- Net Architecture delta > 0? **No** — delta is −2; no `architecture` regression lesson required.
- Structural metric regression > 20 %? **No** — every structural metric improved or held.
- Contract coverage % decreased? **N/A** — no `_docs/02_document/contracts/` directory; project uses code-derived contracts (`endpoints.test.ts`), which expanded by 36 new assertions this cycle.

## Efficiency

| Metric | Value |
|--------|-------|
| Blocked tasks | 0 |
| Tasks requiring fixes after review | 0 |
| Batch with most findings | None — both batches 0 findings |
| Auto-fix loops invoked | 1 (batch 09, classColors circular import; documented as F3-pending exemption) |
| Stuck-agent incidents | 0 |

### Blocker Analysis

| Blocker Type | Count | Prevention |
|--------------|-------|-----------|
| None this cycle | 0 | — |

### Auto-fix root-cause (batch 09)

- **Symptom**: `tests/detection_classes.test.tsx` failed with `TypeError: Cannot read properties of undefined (reading 'map')` after `FALLBACK_CLASS_NAMES` was migrated to import through the `06_annotations` barrel.
- **Root cause**: barrel-induced runtime circular import (`AnnotationsPage → DetectionClasses → 06_annotations barrel → AnnotationsPage`).
- **Resolution**: structural exemption (NOT a re-order hack) — `classColors` removed from the `06_annotations` barrel, exemption documented in 5 coupled locations (barrel file, consumer file, static-check script regex, `module-layout.md` Rule #3, architecture test exemption case). Exemption clears when F3 moves the file to its physical/logical owner.
- **Lesson seed**: documented under §Top 3 Improvement Actions #2 and reflected in LESSONS.md (architecture).

## Trend Comparison

*No previous retrospective — this is the project's first cycle retro. Baseline metrics established above will form the comparison surface for cycle 2.*

## Top 3 Improvement Actions

1. **Establish a "micro-cumulative" review for cycles with < K batches.**
   Cycle 1 closed in 2 batches, below the implement skill's K=3 cumulative-review trigger. No aggregate cross-batch review fired at cycle close — only the two per-batch self-reviews. Both were clean, so it cost nothing this time, but the gap exists by design and silently widens for any tightly-scoped cycle. Recommend adding a lightweight "end-of-cycle micro cumulative" pass (Phase 6 + Phase 7 only) when `cycle_batch_count < K`, gated to ≤ 30 minutes.
   - Impact: medium — catches cross-batch consistency drift that single-batch self-review misses.
   - Effort: low — extend implement skill Step 14.5 with a `cycle_close` branch; no new tooling.

2. **Codify the `STC-ARCH-*` single-script-multi-mode pattern as the standard architecture-gate recipe.**
   Both gates this cycle (STC-ARCH-01 / STC-ARCH-02) share one script (`scripts/check-arch-imports.mjs`) with a `--mode` flag, one symmetric test harness (`tests/architecture_imports.test.ts` with fixture-driven fail-on-synthetic + pass-on-migrated cases), and a uniform 5-place exemption-documentation discipline. The next architecture gate (e.g., STC-ARCH-03 for F6's `src/shared/` move, or a future cross-layer prohibition) should follow the same shape rather than reinventing.
   - Impact: high — halves the drift surface for every future architecture gate; the pattern is already battle-tested for two gates.
   - Effort: low — promote the pattern explicitly in `_docs/02_document/module-layout.md` (currently described per-rule) and reference it from `coderule.mdc` or a new architecture-gates rule file.

3. **Promote the autodev state-reconciliation rule as a canonical example.**
   The session that closed AZ-486 started by detecting that `state.cycle` / `state.step` disagreed with the working tree (most of AZ-486 was already implemented but uncommitted). The autodev orchestrator surfaced the disagreement as a Choose block — option A "continue the in-progress work" was selected — and the session resumed cleanly with no auto-fix loops on the resume itself.
   - Impact: process — confirms the rule in `state.md` "trust folders over state file" works in practice; recording it in `_docs/LESSONS.md` (and possibly as an example block under `state.md`) makes it discoverable.
   - Effort: very low — LESSONS.md entry + one optional example block.

## Suggested Rule / Skill Updates

| File | Change | Rationale |
|------|--------|-----------|
| `.cursor/skills/implement/SKILL.md` (Step 14.5) | Add a `cycle_close && batch_count < K` branch that runs a Phase-6 + Phase-7 only "micro-cumulative" review. | §Top 3 Improvement Action #1. |
| `_docs/02_document/module-layout.md` (after Layout Rules) | Add a short "Architecture Gate Recipe" section: one script + `--mode` dispatcher + fixture-driven test pair + 5-place exemption discipline. Cross-reference STC-ARCH-01 and STC-ARCH-02 as the canonical examples. | §Top 3 Improvement Action #2. |
| `_docs/LESSONS.md` (top) | Append the 3 lessons in §LESSONS Append below. | Skill Step 4. |

## LESSONS Append (top 3, single-sentence, tagged)

1. **[architecture]** When adding an architecture gate (STC-ARCH-*), extend the existing single-script dispatcher with a new `--mode` flag instead of forking a second script; same walker, same comment-skip, same test harness — half the drift surface.
2. **[architecture]** When a barrel re-export causes a runtime circular import, treat the carve-out as a structural exemption documented in five coupled places (barrel, consumer, script regex, layout doc, gate test), not as a re-order hack — the exemption clears when the deeper structural fix lands and never silently drifts in the meantime.
3. **[process]** When autodev detects state ↔ working-tree disagreement on session resume (`state.cycle` / `state.step` ≠ on-disk artifact set), ALWAYS surface as a Choose block before resuming work — never silently merge or restart; the rule in `state.md` "trust folders over state file" worked end-to-end on the AZ-486 resume.