AX: Agent Experience initiative — tracking issue

[manwithacat]

Tracking issue — Agent Experience (AX) initiative

Following the v0.67.118–125 high-velocity sprint, we have a structured way to discover AX bottlenecks: scripts/stall_log_mine.py (74a6b6d) mines Claude Code JSONL transcripts for confusion signals and produces a friction-ranked report.

This issue tracks the AX programme as a whole.

Programme goals

1. Reduce agent friction on the top-N hot zones by ~50% measured by re-running stall_log_mine.py quarterly.
2. Maintain the HTMX/Alpine/Fragment substrate as the empirical baseline. Stack-comparison work is deferred; longitudinal "this codebase vs itself last quarter" tells us if AX work is moving the number.
3. Promote successful patterns into CLAUDE.md as durable guidance.

Child issues

• AX: bump-cycle formatter race — 1,400 friction-points across pyproject/CLAUDE.md/homebrew/CHANGELOG #1063 — Bump-cycle formatter race (shipped v0.67.126 + v0.67.127)
• AX: decompose src/dazzle/render/fragment/renderer.py (3,784 lines, friction 190) #1064 — renderer.py decomposition — complete, 3,784 → 364 lines (-90%) across 9 PRs (v0.67.136–v0.67.144)
• AX: decompose src/dazzle/back/runtime/renderers/region_adapter.py (2,871 lines, friction 168) #1065 — region_adapter.py decomposition — complete, 2,871 → 164 lines (-94%) across 8 PRs (v0.67.128–v0.67.135)
• AX: add file-organisation README to route_generator.py (4,257 lines, friction 148) #1066 — route_generator.py section-map docstring (shipped v0.67.126)
• AX: forward-pointer comments on transit-point files (page_routes, parser/workspace) #1067 — forward-pointer comments on transit-point files (shipped v0.67.126)

All children closed ✓

5 of 5 closed across 27 versions (v0.67.118 → v0.67.144). The two large decompositions (#1064 + #1065) established the canonical mixin-per-family pattern — two reference implementations now exist, one with dict-based dispatch (region_adapter) and one with match-based dispatch (renderer).

Validation

Next monthly scripts/stall_log_mine.py sweep will quantify the friction-score impact. Expected changes vs. April baseline:

• pyproject.toml / CLAUDE.md / homebrew / CHANGELOG (AX: bump-cycle formatter race — 1,400 friction-points across pyproject/CLAUDE.md/homebrew/CHANGELOG #1063) → out of top-5.
• region_adapter.py (AX: decompose src/dazzle/back/runtime/renderers/region_adapter.py (2,871 lines, friction 168) #1065) → off the friction list (now 8 smaller files).
• renderer.py (AX: decompose src/dazzle/render/fragment/renderer.py (3,784 lines, friction 190) #1064) → off the friction list (now 9 smaller files).
• route_generator.py (AX: add file-organisation README to route_generator.py (4,257 lines, friction 148) #1066) → ~50% drop in repeat-read count.

Issue can be closed once that sweep confirms the predictions. Until then keep open as the measurement anchor.

Measurement protocol

• Re-run python scripts/stall_log_mine.py --days 30 at end of each month.
• Diff the friction-ranked top-15 month-over-month.
• A row dropping out of the top-15 = confirmed win. A row climbing = regression or new touch-zone.

Limitations of the current data

1. Sample bias: window dominated by recent high-velocity work. Patterns reflect what was being worked on.
2. Heuristic weights: repeat_reads + 3·edit_failures + 5·errors is a guess.
3. Doesn't catch all stalls: agents giving up and asking the user, or stalling on a non-tool reasoning loop, leave no signal in the transcript tool stream.

[github-actions]

Thanks for opening this issue, @manwithacat!

A maintainer will review this shortly. If this is a bug or feature request, please use our issue templates for faster processing.

[manwithacat]

Cycle 1 measurement complete — closing with mixed verdict

Re-ran scripts/stall_log_mine.py --days 30 on 2026-05-15 (full report: dev_docs/agent-stall-mining-2026-05-15.md). The 30-day window now includes ~one month of post-decomposition sessions.

What worked

Decomposition wins confirmed:

• AX: decompose src/dazzle/render/fragment/renderer.py (3,784 lines, friction 190) #1064 (renderer.py) — old monolith score 190 is from pre-decomposition sessions still in the window. The new _emit.py shell shows just 95 (rank 14). When the historical sessions roll off the window in another ~3 weeks, the old renderer.py will disappear entirely from the report.
• AX: decompose src/dazzle/back/runtime/renderers/region_adapter.py (2,871 lines, friction 168) #1065 (region_adapter.py) — old monolith score 168 is also historical (one session, 105 repeat reads from the decomposition work itself). The new mixin-per-family package files don't appear in the top 15. Same rolling-window dynamic.
• Merge dazzle_back + dazzle_ui into a single dazzle/ package #1055 (dazzle_back + dazzle_ui merge) — old src/dazzle_back/runtime/workspace_rendering.py shows 192 (from 7 sessions, historical). New src/dazzle/back/runtime/workspace_rendering.py shows 89 (from 5 sessions, current). Roughly 53% friction-score reduction on the same logical file under its new home.

Bump-cycle fix (#1063) — CHANGELOG.md friction dropped 224 → 213 over the month. Not the dominant move I predicted, but a measurable improvement.

What was wrong about the original prediction

"Expected changes vs. April baseline: pyproject.toml / CLAUDE.md / homebrew / CHANGELOG (#1063) → out of top-5."

These are still in the top 4. The prediction's mental model was flawed. These files aren't friction targets that can be refactored away — they're ship-cycle hot files: every release touches all four in lockstep (version bump + changelog entry + homebrew formula). The friction is inherent to having releases, not a code smell.

Score trajectory will be flat-ish on these regardless of code work — they only ever drop if (a) we ship less, or (b) the bump skill itself becomes more efficient (the v0.67.127 atomic-sed approach was a step there; v0.67.146's documentation pre-flight repair was another).

"route_generator.py (#1066) → ~50% drop in repeat-read count."

Still 135 — flat. The docstring-only fix (#1066) was never going to move repeat-reads; only a decomposition would. Wrong intervention class for the predicted outcome.

Revised model — recommend keeping or closing?

The new understanding the data gives us:

File class	Friction shape	Right intervention
Refactor targets (renderer.py, region_adapter.py, big runtime modules)	Repeat-reads drop sharply after decomposition; old-path scores are sticky in the rolling window	Decomposition — confirmed working. Keep applying.
Ship-cycle hot files (pyproject, CLAUDE.md, CHANGELOG, homebrew, ROADMAP, core.toml)	Score is proportional to release count, not file complexity	Bump-skill efficiency (#1063 helped) + version-string consolidation. Cannot displace from top-5 while shipping at current cadence.
Discovery friction (repeated greps like __pycache__, ^FAILED)	Agent doesn't know where things live	CLAUDE.md pointers + knowledge-graph entries (cycle 113's API-surface audit is one shape)

Recommend close

Closing this tracking issue. The decomposition arc paid off — the two big targets are de-frictioned and the historical scores will roll off the window naturally. The "ship-cycle hot files" insight is the more useful lesson: those four files are baked into the release process; future AX work should focus elsewhere.

If we want monthly cadence on the stall-mine sweep, that's a calendar item not a GitHub issue. Re-running scripts/stall_log_mine.py --days 30 in another month would let us watch:

1. Whether the historical src/dazzle_back/* paths roll off entirely
2. Whether new touch-zones from current work emerge in the top 15
3. Whether the ship-cycle hot-file scores keep climbing (a signal the bump skill needs more efficiency work)

If a real friction-class emerges, file a new issue with concrete targets. Don't keep the umbrella indefinitely open as a measurement anchor — that breeds tracking-issue rot.