iteration-observability

name	iteration-observability
description	Use this project-local skill when asked to improve agent/dev workflow, analyze iteration speed, explain validation choices, backfill local session telemetry, or turn Bakery session data into process improvements. It uses the repository's `bun run report:iteration` and `bun run project:notes` commands without printing raw prompt/tool contents.

Iteration Observability

Use this skill to make workflow recommendations from local evidence instead of intuition.

Safety and context discipline

• Treat telemetry as local-first and content-sensitive.
• Do not print raw prompts, raw tool outputs, secrets, or large JSONL contents.
• Prefer summaries: counts, durations, paths, command labels, artifact directories, and recommendations.
• If a command output is likely to be large, redirect it to a temp file or run a narrower command first.
• Use bun run project:notes before broad PROJECT_LOG.md reads.
• Avoid broad raw searches over session directories and avoid reading screenshot/image payloads unless visual review explicitly requires the image itself.

Quick start

From the repository root:

bun run project:notes
bun run report:iteration --agent-actions --recommend
bun run report:iteration --session-context
bun run report:iteration --session-history
bun run report:iteration --session-history --days 2 --roi
bun run report:iteration --session-history --latest-sessions 10 --exclude-current-session

Use --session-context for the current/most recent session and --session-history to backfill available local JSONL session logs. Use --session-history --days 2 --roi for a repeatable today/yesterday optimization review; recent-day filtering uses local-calendar day boundaries and session log mtime. Use --latest-sessions 10 --exclude-current-session when you want recent-history evidence without counting the active conversation.

Stacked slice workflow

For multi-commit cleanup or engineering-opportunity stacks, keep the process evidence-based and sequential:

1. Plan the stack once, then work one slice at a time.
2. Validate and commit each slice before editing the next slice.
3. Prefer the parent session as the single writer; use subagents for focused planning/review/oracle gates.
4. Ask review subagents for blocker/important findings only, plus validation gaps. Broad reviewer output is a context cost.
5. Use a smoke-first rhythm: focused unit/static check, then bun run report:iteration --recommend <changed files>, then selected focused harnesses.
6. If reviewer feedback lands after broad selected validation, fix the issue and rerun the narrow affected check first; rerun the selected harness list only when the fix crosses those surfaces.
7. Run fixed-port UI harness scenarios serially unless the harness explicitly supports parallel execution.

Choosing validation commands

Before validating code changes, ask the selector for changed files:

bun run report:iteration --recommend <changed files>

In handoffs, include the report's ## Validation decision block or summarize:

• changed files;
• exact commands run;
• optional escalation;
• whether full bun run test:web-perf was selected, escalated to, or intentionally skipped.

Follow the selector's focused-first command list in order and stop to fix the first failure. Treat full bun run test:web-perf as an explicit escalation, not the default: run it when protocol/session lifecycle behavior changed, broad UI interaction paths changed, focused validation fails unexpectedly, or the selector selects it.

When a focused ui-harness scenario fails, do not immediately rerun the same command. First locate the newest artifact with bun run report:iteration --latest-artifact <scenario>, inspect the listed artifact directory and relevant logs/screenshots, identify one failing assertion or cause, patch the smallest cause, then rerun only that focused scenario. If bun run report:iteration --recommend ... or --session-history labels the latest artifact as degraded or missing, regenerate that same focused scenario once to capture useful failure logs/screenshots before deeper debugging; do not escalate to broad validation just to replace a bad artifact. In the handoff, include the artifact path, artifact quality when reported, and explain why any repeated failed scenario reruns were necessary.

For a non-trivial slice, avoid validating in the most expensive order. Run a cheap focused check first, then reviewer/oracle if useful, then the selected harness list after review-driven fixes. This reduces repeated broad validation when reviewers catch issues.

Reading current-session telemetry

Run:

bun run report:iteration --session-context

Look for:

• compact Action summary totals for tool calls/results, validation reruns, edit failures, unique read/bash inputs, largest result size, and event-span timing;
• large context contributors in Largest tool results;
• repeated reads or repeated bash commands;
• validation reruns and failures, especially the Rerun opportunity and repeated failed focused-harness counts;
• edit/write failure clusters;
• model usage and max reported input/cache reads;
• mobile artifact-handoff recommendations when mobile-layout appears.

Turn these into concrete process changes, for example:

• replace broad log reads with bun run project:notes plus targeted read offsets;
• prefer focused harness scenarios over full-suite runs when the selector says the full suite is not required;
• stop after a failing focused scenario, check artifact quality, inspect usable artifacts/logs/screenshots, patch once, and rerun that scenario instead of cycling validation blindly;
• patch high-churn files with smaller exact replacements;
• include key harness screenshot PNG paths in mobile/UI handoffs;
• narrow large reconnaissance subagent tasks, use output: false or explicit temp/file-only outputs, and summarize instead of pasting broad reports into parent context;
• if repeated validation is high, document which future check should move earlier/later in the slice rhythm.

Backfilling historical session telemetry

Run:

bun run report:iteration --session-history
bun run report:iteration --session-history --days 2 --roi

Use the date-windowed command for today/yesterday reviews. Session-history date filters are mtime-based; --days 2 means local-calendar today and yesterday through now, while explicit --since/--until windows are available for exact ranges.

Use the aggregate sections to identify recurring optimization opportunities:

• Validation command summary: commands/scenarios with high run or failure counts;
• Edit/write attempts: files where agents often retry exact edits;
• Top read paths and Top bash commands: recurring context sinks;
• Action summary: cross-session totals for tool calls/results, validation reruns, edit failures, unique read/bash inputs, largest result size, and summed event spans;
• Largest sessions and Largest tool results: sessions/commands worth studying for workflow friction;
• Sessions with edit failures: candidate files for refactors, helper extraction, or smaller edit islands.

Caveats:

• Deleted/unlogged sessions cannot be recovered.
• Human intent for reruns cannot be reconstructed unless written in the transcript.
• The report is metadata-only; it intentionally avoids printing raw content.

Recommendation format

When asked how to improve the workflow, produce:

1. Evidence: cite the telemetry sections and counts that matter.
2. Candidate improvements: list the top 1-3 slices in priority order.
3. Default next slice: recommend one small vertical slice.
4. Likely files to change.
5. Validation plan with exact commands.
6. Manual testing notes, including whether browser refresh or backend restart is needed.

Keep recommendations practical and repository-specific. Prefer measurable process/tooling changes over generic coaching.