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.