Skip to content

feat(skills): Add dependency-redundancy analysis to the user plugin - #14

Merged
Hzfengsy merged 2 commits into
mainfrom
feat/dep-redundancy-skill
Aug 25, 2026
Merged

Hzfengsy merged 2 commits into
mainfrom
feat/dep-redundancy-skill

Conversation

@lyfne123

@lyfne123 lyfne123 commented Aug 24, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The user plugin can now explain where a run's time went, but not whether the
graph it executed carried orderings nothing needed. dependency-redundancy
adds that audit over deps.json: which edges a longer path already implies,
which of those are safe to drop, and — the part the tool does not say on its
own — when its answer is uninformative and must not be reported as "already
minimal".

Changes

  • plugins/pypto-user/skills/dependency-redundancy/: the skill. It orders the
    work so uninformative cases are excluded before a mode is chosen — read the
    edge-source mix and the graph depth first, then select — and covers the four
    edge modes, the validation gates, and an interpretation table naming the
    action each outcome licenses.
  • plugins/pypto-user/lib/dfx/capture.md: note that a structural analysis
    consumes deps.json alone, so the two analyses sharing that file do not both
    have to capture timing.
  • plugins/pypto-user/.codex-plugin/plugin.json: the long description covers
    the fifth workflow. No version bump — that belongs to the release workflow.
  • tests/: register the skill in EXPECTED_USER_SKILLS.

No behavior change to any existing skill; the new skill is additive.

Why the ordering matters

Census over 64 dependency graphs captured with --enable-dep-gen across
tests/st/a2a3/{tensormap_and_ringbuffer,host_build_graph} on real silicon:

edges structurally redundant reduced reports reduced_dataflow reports
all 64 graphs 43784 5839 722 (12%) 2709 (46%)
batch paged attention 6128 2032 0 992
paged attention unroll 1280 256 0 0
dep-gen chain (n=391) 783 391 391 391
64×64 explicit fanin 4096 0 0 0

The mechanism works — the chain cases prove it finds and prints real redundant
edges. What it cannot do is say when its own answer is uninformative. Creator
protection is per-pair, and Step-A creator retention emits a creator row for
exactly the pairs a dataflow dependency also covers, so a mixed-source graph is
no safer than an all-creator one: every one of batch paged attention's 2032
redundant pairs is creator-annotated, and the documented default mode reports
removed 0 on a graph where 992 edges are provably droppable.

18 of the 29 graphs that contain redundancy report 0 from every mode, because
their redundant pairs have INPUT consumers while the byte-level proof only
licenses INOUT. Those edges are correctly retained — they hold a creator
alive — but nothing in the output distinguishes that from an already-minimal
graph. The skill turns this into a rule: never report from reduced alone, and
when both modes return zero, say "nothing removable" rather than "nothing
redundant".

Verification

  • python -m unittest discover -s tests: 232 tests, OK. Run inside the push
    transaction at each pushed commit with ruff check tests,
    ruff format --check tests, and pyright — all clean, 0 errors.
  • On-device corpus. The census above: the full a2a3 scene-test suite run
    under the shared device queue with --enable-dep-gen, then every graph
    audited by following the skill literally. The per-mode counts come from the
    shipped CLI; the structural column comes from running the same reduction with
    the creator protection bypassed.
  • Mode semantics on a minimal graph. A three-task chain with a direct
    1 -> 3 edge: reduced and omitted both identify and print 1 -> 3;
    flipping that edge's source to creator makes both report 0, reproducing the
    trap at a scale small enough to read.
  • Cycle handling. A cyclic graph warns on standard error, emits the full
    graph, and exits 0 — which is why the skill tells the reader not to take the
    exit status as proof a reduction ran.
  • Output naming confirmed: a reduction writes deps_viewer_<mode>.txt rather
    than overwriting a full-graph render beside it.

lyfne123 and others added 2 commits August 24, 2026 01:42
The user plugin can now explain where a run's time went, but not whether the
graph it executed carried orderings nothing needed. The dependency viewer
already computes that — an edge is redundant when a longer path implies it —
and exposes it through four edge modes. What it does not do is tell a reader
when its own answer is uninformative, and that is where the analysis goes
wrong.

Add `dependency-redundancy` to the user plugin. It orders the work so the
uninformative cases are excluded before a mode is chosen: read the edge-source
mix and the graph depth first, then select. A graph of depth 1 cannot contain a
redundant edge at all. A graph whose edges are all `creator` cannot report one
either, because structural reduction protects tensor-lifetime references
unconditionally — so a zero there is a property of the mode, not a fact about
the graph.

That distinction is not theoretical. Walking the tool over real captures from
this project's own scene tests, a 1280-edge attention graph reported `removed 0
redundant edge(s)` while 256 of its edges — a fifth of the graph — were
transitively implied and retained only as lifetime references. A reader who ran
one mode and stopped would have recorded "already minimal". The skill routes
that case to the dataflow modes and, when those also return zero, requires the
result to be stated as "nothing removable" rather than "nothing redundant".

The rest is the same shape as the critical-path skill: validation before
interpretation — a cycle disables the selected mode, warns on standard error,
and still exits 0, so the exit status is no evidence a reduction ran — then an
interpretation table that names the action each outcome licenses. Removing a
redundant edge drops scheduling bookkeeping, never execution order, so the
skill forbids describing it as an ordering change or promising a speedup no run
measured.

Note in the capture contract that a structural analysis consumes `deps.json`
alone, so the two analyses now sharing that file do not both have to capture
timing.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A census over 64 dependency graphs, captured across this project's a2a3 scene
tests rather than the three the skill was written from, moved the boundary the
skill draws.

The skill treated an all-`creator` graph as the shape where a structural
reduction cannot report anything, implying a mixed-source graph could be
trusted. It cannot. Protection is per-pair, and Step-A creator retention emits
a creator row for exactly the pairs a dataflow dependency also covers, so the
two sources land on the same edge as a rule rather than by accident. Measured:
a graph of 5120 `creator` plus 1008 `tensormap` edges had every one of its 2032
redundant pairs creator-annotated. `reduced` reported 0 there; the dataflow mode
removed 992.

Across the census the documented mode surfaces 722 of 5839 structurally
redundant edges, and the dataflow mode 2709. So the source mix explains a gap
between the modes but never licenses skipping one, and the skill now says so as
a rule: never report from `reduced` alone.

Correct the closing table row with it. Two modes returning zero establishes
that nothing is *removable*; redundant-but-retained edges are invisible to
every mode, so it was wrong to let that outcome be reported as a minimal graph.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Hzfengsy
Hzfengsy merged commit af1d7a0 into main Aug 25, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants