Skip to content

Diagnostic Legibility

Agents accountable for helping to maintain human understanding.

A sister plugin to ai-literacy-superpowers and model-cards in the same marketplace.

The Challenge of Putting Back the Hunches

AI has fundamentally changed the relationship between creating software and understanding it. Developers can now generate large amounts of code while missing a living theory of how it works. Developers remain accountable for software created with AI, and the need for understanding has not gone away just because the process that used to generate that understanding has changed. While reviewing the code can help, it does not put back the experiential intuition that has gone missing. Developers need hunches: the intuitive sense of what to do, where to look, and what to try.

Charter

Make maintaining human hunches a first-class design goal supported by the agents. Rather than expecting humans to recover understanding by reviewing generated code, agents are accountable for designing for diagnostic legibility and helping to maintain human understanding. The agents construct diagnostic affordances that help the humans gain hunches by poking and seeing: interacting with the software, observing what happens, and developing experiential intuition about how it works. As the human learns, they offer their hunches as feedback, and the agent revises the design for conceptual clarity--an approach we call hunch-oriented telemetry.

Current Scope

The plugin's purpose is to host agents that are accountable for maintaining human understanding of complex systems. The inaugural agent builds two models of a codebase scope — one for architectural moving parts, one for domain concepts — subjects each to a challenge–refine cycle, then uses them to cross-check and correct each other, producing mutually-corrected models that can be surfaced on demand to a human.

The framing is deliberately broad: codebase legibility is the first instance, but the discipline (two-model + cross-check + on-demand surfacing) generalises to other domains. Future agents may apply it to governance artefacts, decision records, or other complex systems.

Status: v0.11.0 — task-scoped pipeline maps with change-site prediction

The plugin ships the diagnostic-legibility agent and two human-facing commands. The agent builds an architectural model and a domain model against the LegibilityElement schema, runs a retained-challenge cycle (Phase B — five questions per element), then cross-checks the collections against each other (Phase C). /diagnose <scope> drives that pipeline for a code area you hand it and renders the corrected models as a readable report.

Since then the task-scoped pipeline map (ConceptualPipelineMap) has been added: instead of handing in a scope, you state a work task and the agent derives the bounded slice it touches (mode: scope-resolution, v0.7.0), traces the control flow within it (mode: pipeline, v0.8.0), cross-checks the flow against the architectural and domain models (three-way, v0.9.0), and predicts which nodes the task will edit (mode: change-prediction, v0.11.0). The /pipeline-map "<task>" command (v0.10.0) renders all of this as a self-contained HTML flow map, and /pipeline-map "<task>" --predict-change adds the change-site prediction. New here? Start with Explore the scope and impact of a change.

The full carpaccio decomposition is now shipped:

  • ✅ #331 — S2: Two-model agent (shipped v0.3.0)
  • ✅ #332 — S3: Cross-check mechanism (shipped v0.4.0)
  • ✅ #333 — S4: Surfacing interface — the /diagnose command (shipped v0.5.0)

The carpaccio slicing that produced this decomposition is recorded at docs/superpowers/slices/diagnostic-legibility-plugin.md and traces back to parent issue #327.

Quadrant pages