refactor(skills): split the FSL reference so activation loads 7,102 tokens instead of 19,821 - #942
Merged
Merged
Conversation
Collaborator
Author
|
Authorship note: this branch was produced under my orchestration and is being admin-merged without an independent human review, so it is an authored change rather than a reviewed one. Its evidence is the same-baseline token measurement (main 19,821 → PR 7,102, -64%), 27/27 local links resolving, and |
This was referenced Aug 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Closes #941. Closes #763.
skills/fsl/SKILL.mdは skill が発火するたび全文がコンテキストへ載る。#941 がその量を実測し、19,821 トークン(
reference.mdは読まれると 49,300)であることを示した。SKILL.mdは「spec を書く前に必ずreference.mdを読め」と指示しており、その指示は#763 が示すとおり authoring skill 6件すべてに複製されていた。
2つは同じ PR で動かす必要がある。 指示の重複だけ直しても
reference.mdは巨大な塊のままで、分割だけしても6 skill が「全部読め」と言い続ければ効果が出ない。
Contract change
分野別
references/への分割skills/fsl/reference.md(2,128行)を削除し、skills/fsl/references/の9ファイルへ分割:syntax.mdcommands.mdlayers.mdimpl.mderrors.mdwhen-to-use.mdadvanced.mdnl-to-syntax.mdpractices.mdSKILL.mdは 789行 → 339行、8節(役割振り分け / 実行方法 / 形式化メモ / 標準ワークフロー /最小テンプレート / 構造的落とし穴 / 役割別入口 / Reference index)。索引は
各
references/*.mdが何を答えるファイルかを示す。6 authoring skill の無条件読込を解消(#763)
fsl-business/fsl-design/fsl-requirements/fsl-from-code/fsl-requirements-document/fsl-design-reviewの「reference.mdを必ず読め」を、core の索引から必要な topical reference だけを読む指示に変えた。
言い換え版(
fsl-from-codeの短縮版、fsl-requirements-documentとfsl-design-reviewの言い換え)も含めて6件すべて。
結合面(分割の副作用でゲートを弱めないため)
rust/fslc/tests/literate_docs_contract.rsskills/fsl/reference.mdへの anchor を移動先へ。anchor のテキストは変えていないrust/fslc/tests/causal_docs_contract.rsrust/fslc/tests/mutation_docs_contract.rstools/aggregate_changelog.shis_product_surface_pathにskills/fsl/references/*を追加README.md/skills/README.md/skills/fsl-delivery/SKILL.md/ Claude rules・skillsaggregate_changelog.shの更新が特に重要である。is_product_surface_pathはskills/fsl/reference.mdを製品面として名指ししていたので、更新しなければ分割後は skill reference を変えても changelog fragment が要求されなくなる。
Test evidence
効果(同一 baseline で新旧を比較)
--exclude-dynamic-system-prompt-sectionsを付けた #941 の手順で、同じ baseline (45,814) に対してmainのSKILL.mdと本 PR のSKILL.mdを測った:mainのSKILL.mdSKILL.mdmain側の 19,821 は #941 の報告値と完全一致する。計測手順についての実測(#941 の記述を1点訂正)
#941 は
--exclude-dynamic-system-prompt-sectionsを付ければ「決定的に再現する(k=3 で完全一致)」と書いている。同一セッション内では確かに決定的で、baseline を5回・with を4回測って
すべて同値だった(46,567 / 53,669)。
しかしセッションをまたぐと baseline が変わる(45,814 / 46,066 / 46,567 / 47,745 / 47,769 を
観測)。したがって別々のセッションで測った前後の数字を引き算してはいけない。
本 PR の数字は上記のとおり同一 baseline に対する新旧比較で取っている。
途中で見つけた欠陥: 移動ではなくコピーになっていた
最初の実装では
First, decide whether FSL fitsとRecommended practicesがSKILL.mdとreferences/の両方に同一内容で存在していた。オーケストレーターが計測して9,782(-51%)で目標未達と分かり、本文を照合して重複を特定した。
除去して現在の値になった。計測しなければ「-51% 達成」として通っていた。
検証(すべて exit 0)
python3 tools/check-design-citation-headings.py check— citations=74, findings=0bash ./tools/aggregate_changelog.sh checkcargo test -p fslc-rust --test literate_docs_contract --locked— 6 passedcargo test -p fslc-rust --test causal_docs_contract --locked— 2 passedcargo test -p fslc-rust --test mutation_docs_contract --locked— 3 passedcargo clippy --workspace --all-targets --locked -- -D warningsgit diff --checkローカルリンクの解決をオーケストレーターが全件確認した:
SKILL.mdとreferences/*.mdの 27本すべてが解決、壊れゼロ。移動以外の変更(最小限、全件列挙)
内容は節単位で移動し、変更は移動後に意味が切れないための補正のみ:
reference.md読込 → 索引ルーティングcommands.mdへ移す際、独立して読めるよう「Extended workflow commands」の導入文を追加
above/below/reference.md §Nを、移動先への相対リンクまたは明示名に修正reference.mdは削除し、索引をSKILL.mdに一本化した(2箇所に索引を持たない)未計測の懸念(#941 が挙げているもの)
分割前は「
reference.mdを読む/読まない」の二択なので、読まなければ 0 で済んだ。分割後は「複数ファイルのうち必要なものを読む」になるため、エージェントが必要以上に読めば
総量が増え得る。この筋は未計測である。ファイル単体のサイズ比較では判断できないので、
実タスクでの総トークンで確認する必要がある。
Linked issue
Closes #941, closes #763。