Tooling sweep after a shared-path fix: identify ALL consumers of a dispatch surface

[braboj]

Source: me-fuji session 148 (2026-06-14).

Observation

When a dispatch / pipeline change lands, multiple downstream tools consume the dispatch output. Each tool manages one artifact type:

• svg.py writes *.svg
• log.py writes digitization-log.md
• review.py writes *-review.html + overlay PNG
• extract.py writes Tier 2 production logs
• diagnose.py writes per-stage diagnostic bundles

After me-fuji PR #1158 fixed the ridge dispatch, the SVG was still stale because nobody ran svg.py. The maintainer reviewing the committed SVG to verify the fix saw pre-fix values and said "I do not see the SVG updated." The fix was actually working; the artifact didn't reflect it.

A second tool (log.py) was crashing on the new chart family and needed a port (PR #1161) before its logs could refresh.

Pattern

When a change touches a shared dispatch / pipeline surface, identify ALL tools that consume the dispatch output. For each: confirm it can run on the affected charts (no crashes), run it, verify the committed artifact reflects reality. Document the list of consuming tools alongside the dispatch surface in the architecture docs so a future maintainer can apply the sweep without rediscovering them.

User impact when missed

The stale artifact misleads anyone (maintainer, reviewer, future agent) who looks at it to verify the fix. Filed as a P3 "known limitation" can hide the user-blocking nature: when an artifact is what someone uses to verify behavior, stale = blocking, not minor.

Proposed home

templates/base/workflow/ai-workflow.md — add to Lessons Learned section, OR add a new "Tooling sweep" subsection under "Practices for Agent Effectiveness."

Suggested wording

Tooling sweep after a shared-path fix.

When a dispatch / pipeline / shared-surface change lands, identify ALL tools that consume the surface output. Each consuming tool manages one artifact type; the committed artifacts only reflect the fix after their tool runs.

Build the consumer list once and document it alongside the dispatch surface (architecture doc, README, or the surface's docstring). Future maintainers extend the list as new consumers land; the sweep stays cheap.

When an artifact someone uses to verify behavior is stale, that's user-blocking, not "known limitation." Frame priority accordingly.

Anti-pattern

PR #1158 filed log.py predates ADR-044 multi-aperture as a P3 follow-up (#1160), calling it "known limitation." The maintainer was actually blocked by the stale SVG (a different tool: svg.py, which was already multi-aperture-aware — nobody ran it). The "known limitation" framing hid both the priority AND the actual blocker. Fixed by running svg.py separately and porting log.py properly in PR #1161.