Skip to content

fix(skill): size extraction chunks by output, not just file count#1938

Open
STiFLeR7 wants to merge 1 commit into
Graphify-Labs:v8from
STiFLeR7:fix/issue-1758-chunk-sizing-output-budget
Open

fix(skill): size extraction chunks by output, not just file count#1938
STiFLeR7 wants to merge 1 commit into
Graphify-Labs:v8from
STiFLeR7:fix/issue-1758-chunk-sizing-output-budget

Conversation

@STiFLeR7

Copy link
Copy Markdown

Summary

Fixes #1758 — Part B2 semantic-extraction subagents can silently crash past the ~64k output-token per-turn limit on large/deep-mode chunks, and the missing chunk file is misdiagnosed.

Root cause

Step B1 sizes chunks purely by input file count (20-25), with no accounting for expected output volume — which varies a lot with --mode deep (more INFERRED edges per file) and document density. Each subagent must write its entire chunk's extraction in a single Write call within a single turn; a chunk whose output exceeds the model's per-turn output-token ceiling doesn't get truncated — the turn simply ends before Write happens, so the chunk file never appears on disk at all, and that chunk's extraction is silently lost. Step B3's existing diagnosis for a missing chunk file only considers one cause ("subagent was likely dispatched as read-only"), which is indistinguishable from an over-the-limit crash purely from the missing file.

Fix

Two of tools/skillgen/fragments/core/'s per-platform fragments dispatch subagents this way — core.md (claude and everything else that shares it) and devin.md:

  • Reduce chunk size to 10-15 files when DEEP_MODE=true.
  • Note the per-turn output ceiling explicitly in Step B1, with guidance for the subagent to keep extraction proportionate on unusually dense corpora even at the reduced chunk size.
  • Give Step B3 a second diagnosis branch: a missing chunk file could be either read-only dispatch or an output-limit crash, and both need surfacing.
  • Update the pre-dispatch timing/agent-count estimate to account for the smaller deep-mode chunk size.

Not touched: aider.md's Step B2 is sequential, single-context file-by-file processing (no parallel subagent dispatch, no single-turn-single-Write-call constraint), so this failure mode doesn't apply there and I didn't want to add misleading guidance to a mechanism that doesn't have the bug.

Not attempted: the issue's suggestion 3 (incremental writes across multiple Write/Edit calls so a chunk degrades to "wrote N of M nodes" instead of losing the whole chunk) — flagged in the issue itself as "more invasive." That would need actual subagent-prompt-protocol changes, not just a chunking/diagnosis tweak, and is a judgment call for a maintainer.

Verification

Regenerated all derived artifacts via python -m tools.skillgen --bless and confirmed python -m tools.skillgen --check passes clean ("134 artifact(s) match committed output and expected/"). Verified the diff scope via git diff --stat (not just git status, which flags many more files due to autocrlf line-ending bookkeeping with no real content change on this Windows checkout) — the real content diff touches exactly the two edited fragments plus the 15 platform-specific renders that depend on core.md (skill.md + 14 skill-<platform>.md files) and their expected/ snapshots. skill-aider.md and its snapshot are correctly untouched.

Disclosure

Prepared with AI assistance (Claude Code). I traced the actual chunking/dispatch/diagnosis logic in the fragment sources (not the rendered graphify/skill.md, which turned out to be a generated artifact — I initially hand-edited it directly, caught that the regeneration pipeline would overwrite it, and redid the edit against the real fragment sources instead) before making this change, and used the repo's own tools.skillgen --check/--bless drift guard to verify the derived artifacts are consistent rather than hand-editing them.

Part B2 dispatches Claude/Devin Agent-tool subagents to extract a
chunk's semantic graph and write it in one Write call within a single
turn. Step B1 sized chunks purely by input file count (20-25), with no
accounting for expected output volume -- which is much higher with
--mode deep (more INFERRED edges per file). A chunk whose output
exceeds the ~64k-output-token turn limit doesn't get truncated: the
subagent's turn simply ends before the Write call happens, so the
chunk file never appears on disk at all, and that chunk's extraction
is silently lost entirely.

Step B3's existing diagnosis for a missing chunk file only considered
one cause (Explore-type read-only dispatch), which is indistinguishable
from an over-the-limit crash from the orchestrator's side.

Changes (core.md and devin.md fragments -- the two platforms that
dispatch subagents this way; aider.md's Step B2 is sequential
single-context processing with no per-turn Write-call ceiling, so it
isn't affected and wasn't touched):
- Reduce chunk size to 10-15 files when DEEP_MODE=true.
- Note the per-turn output ceiling explicitly, with guidance to keep
  extraction proportionate for unusually dense corpora.
- Give Step B3 a second diagnosis branch for missing chunk files.
- Update the pre-dispatch timing/agent-count estimate to account for
  the smaller deep-mode chunk size.

Regenerated all derived skill.md/skill-<platform>.md artifacts and
expected/ snapshots via `python -m tools.skillgen --bless`; `python -m
tools.skillgen --check` passes clean. Only the platforms whose
fragment source changed (core.md, devin.md) have real content diffs --
verified via `git diff --stat` after blessing, not just `git status`
(which flags many more files due to autocrlf line-ending bookkeeping
with no actual content change).

Fixes Graphify-Labs#1758
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant