>>> [!note] Migrated issue <!-- Drupal.org comment --> <!-- Migrated from issue #3588795. --> Reported by: [ajv009](https://www.drupal.org/user/3653917) >>> <h3 id="summary-problem-motivation">Problem/Motivation</h3> <p>Every skill file is read into the orchestrator's context on every turn. As skill files have grown organically &mdash; new phases, new gotchas, platform notes added across many sessions &mdash; the baseline context cost has risen correspondingly. In a recorded session the context grew from 52K to 249K tokens; the $52 total cost was dominated by cache reads of a monotonically growing context window. The skill file itself is a fixed-size contributor to every single turn's cost &mdash; trimming it or breaking it into lazy-loaded reference files would reduce the per-turn baseline and the overall session cost.</p> <p>Additionally, DRY violations (the same snippet copied under every phase header) make skill files harder to maintain: a change to a shared rule requires updating it in multiple places, and inconsistency between copies is a source of agent confusion. The user has explicitly requested a 4-step gated audit of all skill files over 300 lines: find, evaluate, propose, then (only after user decision) execute.</p> <p>The user's intent is explicit and specific: this is a gated task. The first three steps (find, evaluate, propose) are reconnaissance and writing &mdash; no destructive changes are made until the user reviews the proposals and decides what is worth restructuring. The implementer must stop after step 3, present the proposals, and wait. The lazy-loading goal is that "the agent can load reference files in dire times or only when it needs to understand something MORE than the original scope of the skill" &mdash; a one-line reference in the main skill file ("For detail on X, read <code>.claude/skills/migrate-site/refs/&lt;topic&gt;.md</code>") is the most practical mechanism.</p> <h4 id="summary-steps-reproduce">Steps to reproduce</h4> <p>Not a defect repro. To establish the baseline:</p> <ol> <li>Run <code>find .claude -name "*.md" | xargs wc -l | sort -rn | head -30</code> to see current line counts.</li> <li>Identify which files exceed 300 lines.</li> <li>Open one of those files and scan for repeated per-phase snippets that violate the "one shared note" rule.</li> <li>Observe that every line of every oversized file is read by the orchestrator on every turn &mdash; directly contributing to per-turn token cost.</li> </ol> <h3 id="summary-proposed-resolution">Proposed resolution</h3> <p>This is a 4-step gated task. The implementer must execute in order and STOP after step 3 to await user decision before proceeding to step 4.</p> <p><strong>Step 1 &mdash; Find (reconnaissance, no changes):</strong></p> <pre>find .claude -name "*.md" | xargs wc -l | sort -rn | head -30 find .claude/skills -name "*.md" | xargs wc -l | sort -rn find .claude/agents -name "*.md" | xargs wc -l | sort -rn</pre><p>Record the output in a table: file path, line count, approximate size in KB.</p> <p><strong>Step 2 &mdash; Evaluate (dispatch per-file subagent, no changes):</strong></p> <p>For each file with more than 300 lines, dispatch a separate planning subagent to evaluate the file and produce a restructuring proposal. The subagent's output for each file should answer:</p> <ul> <li>What sections are redundant or overlap with other files?</li> <li>What sections are per-phase copies of the same rule (DRY violation)?</li> <li>What sections could be moved to a reference file and lazy-loaded?</li> <li>What sections must stay in the main file (always needed by the orchestrator)?</li> <li>Proposed new line count after restructuring.</li> </ul> <p>Dispatch one subagent per oversized file in parallel &mdash; the user's verbatim phrasing was "separate sub agents think about EACH skill."</p> <p><strong>Step 3 &mdash; Propose (write proposals document, no changes):</strong></p> <p>Consolidate the per-file subagent outputs into a single proposals document. For each file, write:</p> <ul> <li>Current state: N lines, K KB, top-3 bloat sources.</li> <li>Proposed action: TRIM | EXTRACT_TO_REF | DRY_CONSOLIDATE | KEEP.</li> <li>Proposed new state: estimated new line count and size.</li> <li>Risk level: LOW (cosmetic trim) | MEDIUM | HIGH (affects agent behavior).</li> </ul> <p>Present this proposals document to the user. Set this issue's status to <em>pending-review</em>.</p> <p><strong>GATE: User reviews proposals and decides what to execute.</strong></p> <p><strong>Step 4 &mdash; Execute (only after user sign-off on step 3):</strong></p> <p>For each approved restructuring:</p> <ul> <li>If TRIM: remove the redundant sections, then trace through the migration phase sequence mentally to verify the skill still makes sense end-to-end.</li> <li>If EXTRACT_TO_REF: create the reference file at <code>.claude/skills/&lt;skill&gt;/refs/&lt;topic&gt;.md</code> and replace the section with a one-line "Read <code>.claude/skills/&lt;skill&gt;/refs/&lt;topic&gt;.md</code> if you need more detail on X."</li> <li>If DRY_CONSOLIDATE: move the shared rule to a <code>## Common Rules</code> section at the top of the file and remove all per-phase copies.</li> <li>After each file: trace the migration skill mentally through the phase sequence to confirm no critical instruction was lost.</li> </ul> <h3 id="summary-remaining-tasks">Remaining tasks</h3> <ul> <li>Run the find commands and record a table of all <code>.claude</code> markdown files with their line counts.</li> <li>Filter to files over 300 lines.</li> <li>Dispatch one planning subagent per oversized file (in parallel) for evaluation.</li> <li>Consolidate per-file outputs into a single proposals document.</li> <li>Present proposals to the user and set issue status to <em>pending-review</em>.</li> <li>HARD GATE: wait for user decision before any file modifications.</li> <li>After user sign-off: execute approved restructurings file by file, with mental trace verification after each.</li> </ul> <h3 id="summary-ui-changes">User interface changes</h3> <p>None.</p> <h3 id="summary-api-changes">API changes</h3> <p>None.</p> <h3 id="summary-data-model-changes">Data model changes</h3> <p>New directory structure for lazy-loaded references (only after step 4 user sign-off): <code>.claude/skills/&lt;skill&gt;/refs/&lt;topic&gt;.md</code>. New written artefact at step 3: a per-file proposals document for user review (location TBD with the user &mdash; proposed in the source markdown as <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-6-Skill-Architecture/P2-3-audit-proposals.md</code>).</p> <h3 id="summary-internal-references">Internal references</h3> <ul> <li>Source markdown: <code>RESEARCH-2026-04-28/99-final/ISSUES/Sprint-6-Skill-Architecture/04-P2-3-skill-file-audit-lazy-load-architecture.md</code> (id: P2-3)</li> <li>Consolidated issue: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P2-3 (full evidence including verbatim user quote)</li> <li>Original verbatim user request: <code>RESEARCH-2026-04-28/00-existing-issues/unsorted-issues.md</code> Thread 3</li> <li>DRY rule (memory): <code>feedback_dry_skill_instructions.md</code></li> <li>Context cost source: <code>RESEARCH-2026-04-28/99-final/consolidated-issues.md</code> &sect; P0-5 (Context Window Explosion)</li> <li>Skill evolution history: <code>RESEARCH-2026-04-28/07-cross-cutting/migrate-site-skill-evolution.md</code></li> <li>Actionable summary: <code>RESEARCH-2026-04-28/99-final/actionable-list.md</code> (P2-3 row)</li> </ul> <h3 id="summary-open-questions">Open questions</h3> <ul> <li>Should the 300-line threshold apply to total line count (including blank lines and comments) or to lines of actual instruction text? The user's verbatim quote says "more than 300 lines of text" &mdash; clarify before running the count.</li> <li>Are there skill files in locations outside <code>.claude/skills/</code> and <code>.claude/agents/</code> &mdash; for example in <code>.claude/</code> root? The find command should cover all of <code>.claude/</code> to be thorough.</li> <li>The lazy-loading mechanism: a one-line "Read <code>.claude/skills/&lt;skill&gt;/refs/&lt;topic&gt;.md</code>" reference in the main skill file is the most practical implementation &mdash; the agent loads the file when the topic becomes relevant. Confirm this is the intended mechanism, or whether a different scheme is wanted.</li> <li>Confirm step 2 is dispatched as one planning subagent per oversized file, in parallel &mdash; the user's verbatim phrasing was "separate sub agents think about EACH skill."</li> </ul>