refactor(security-issue-sync): extract 4 subdocs to slim SKILL.md 3425 → 658 lines#410
Merged
potiuk merged 2 commits intoMay 31, 2026
Merged
Conversation
…5 → 658 lines Profiling a 12-tracker bulk sync showed every subagent loading the full 3425-line SKILL.md (~30K tokens) regardless of which step it was running. Extract the four heaviest sections into focused subdocs so subagents can load just the slice they need. Subdocs created (all alongside SKILL.md in the same skill dir): - bulk-mode.md (247 lines) — orchestration contract for many-issue parallel runs: bucketing, subagent fan-out, merged-proposal review shape, hard rules, when bulk mode does NOT apply. - gather.md (775 lines) — Step 1 sub-steps 1a-1h: read the GitHub issue, find referenced PRs, locate the real reporter, mine comments + mail for actionable signals, check Gmail for CVE-reviewer comments, determine the process step, check cve.org publication on recently-closed trackers, detect active release-vote threads. - signals-to-actions.md (1088 lines) — Step 2b lookup table: every signal class from Step 1d translated to its proposal item. - apply-and-push.md (768 lines) — Step 4 apply loop, Step 5/5a CVE JSON regen mechanics, Step 5b OAuth push including the six pre-push hygiene gates, Step 5c RM hand-off comment reconciliation. SKILL.md (658 lines) now carries: overview, golden rules, inputs, prerequisites, Step 0 pre-flight, Step 1/2/4 thin pointers to the subdocs, Step 2a observed-state + Step 2c next-step (small enough to stay inline), Step 3 confirm, Step 6 recap, guardrails, process reference, canned responses. The Pattern-4 injection-guard callout was added to SKILL.md (it lived inside the now-extracted Step 1d section) and intentionally repeats inside gather.md so subagents that only load gather.md still see the guard. Subagent loading savings (per step): - Gather-only subagent: 3425 → 1412 lines (59% reduction) - Bulk orchestrator only: 3425 → 884 lines (74% reduction) - Apply orchestrator: 3425 → 1405 lines (59% reduction) - Step 2b proposal builder: 3425 → 1725 lines (50% reduction) Cross-references that pointed at extracted sections rewritten to point at the new subdoc files. Same pattern as setup-steward already uses (adopt.md / upgrade.md / verify.md alongside SKILL.md). No behavior change — pure file restructure. Skill-and-tool-validator passes.
…d-push.md PR apache#410 moved the Step 5b decision-flow block from SKILL.md into the new apply-and-push.md subdoc. The scanner-products template still referenced the old location, breaking the lychee fragment check. Point the link at the new home.
2 tasks
potiuk
added a commit
that referenced
this pull request
May 31, 2026
…submitting (#411) * docs(agents): require lychee local-run on every PR — added to Before submitting Caught a Fragment-not-found regression in PR #410 only when CI flagged it. The check is cheap to run locally (offline file + fragment lookups; only the external-URL subset hits the network) and catching it before the push avoids a round-trip. Add to the Before-submitting checklist: - the canonical invocation (lychee --config .lychee.toml .) - guidance on the most common breakage class (Fragment not found) which is what bites on doc refactors that move sections between files or rename headings - a one-liner for v0.24+ local lychee installations (since .lychee.toml pins the v0.23 schema) The rule is enforce-via-CI either way (the lychee workflow blocks the merge on any failure); this is just a documentation reminder so agents add it to their pre-push routine and avoid the round-trip. * fix(AGENTS.md): link to link-check.yml, not the made-up doc-validation.yml The "Before submitting" lychee guidance pointed at `.github/workflows/doc-validation.yml`, which does not exist — this repo's link-check workflow is `link-check.yml`. Caught by running lychee on the same file the PR added (which is what the new rule itself prescribes).
potiuk
added a commit
to potiuk/magpie
that referenced
this pull request
Jun 1, 2026
…ity-suite refactor patterns Adds `optimize-skill` (capability:setup) — the refactoring sibling of `write-skill`. It takes an existing framework skill (or sweeps a set) and applies the five restructuring patterns proven on the security suite, as behavior-preserving proposals gated by the validator (green-before / green-after): - split — slim an oversized SKILL.md into linked siblings (the apache#410 pattern; addresses the PRINCIPLES.md P14 cap) - config-lift — move concrete values into <project-config> (apache#386/apache#387/apache#388) - out-of-context — read/PATCH one field without loading the body (apache#412 github-body-field, apache#424 github-rollup) - fetch-upfront — batch per-item round-trips (apache#347) - preflight-classifier — skip obvious no-ops before LLM passes (apache#414/apache#416) SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR / mechanics / behavior-preservation guarantee / validation) lives in the patterns.md sibling. Reads only framework-internal files, so no injection-guard / Privacy-LLM callouts. Ships a step-diagnose eval (5 auto-comparable cases incl. an injection-resistance case) so the skill is not released without an eval (P8). Wires the skill into the capability->skill map and the eval index. Generated-by: Claude Code (Opus 4.8)
potiuk
added a commit
to potiuk/magpie
that referenced
this pull request
Jun 1, 2026
…ity-suite refactor patterns Adds `optimize-skill` (capability:setup) — the refactoring sibling of `write-skill`. It takes an existing framework skill (or sweeps a set) and applies the five restructuring patterns proven on the security suite, as behavior-preserving proposals gated by the validator (green-before / green-after): - split — slim an oversized SKILL.md into linked siblings (the apache#410 pattern; addresses the PRINCIPLES.md P14 cap) - config-lift — move concrete values into <project-config> (apache#386/apache#387/apache#388) - out-of-context — read/PATCH one field without loading the body (apache#412 github-body-field, apache#424 github-rollup) - fetch-upfront — batch per-item round-trips (apache#347) - preflight-classifier — skip obvious no-ops before LLM passes (apache#414/apache#416) SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR / mechanics / behavior-preservation guarantee / validation) lives in the patterns.md sibling. Reads only framework-internal files, so no injection-guard / Privacy-LLM callouts. Ships a step-diagnose eval (5 auto-comparable cases incl. an injection-resistance case) so the skill is not released without an eval (P8). Wires the skill into the capability->skill map and the eval index. Generated-by: Claude Code (Opus 4.8)
potiuk
added a commit
that referenced
this pull request
Jun 1, 2026
…ity-suite refactor patterns (#427) Adds `optimize-skill` (capability:setup) — the refactoring sibling of `write-skill`. It takes an existing framework skill (or sweeps a set) and applies the five restructuring patterns proven on the security suite, as behavior-preserving proposals gated by the validator (green-before / green-after): - split — slim an oversized SKILL.md into linked siblings (the #410 pattern; addresses the PRINCIPLES.md P14 cap) - config-lift — move concrete values into <project-config> (#386/#387/#388) - out-of-context — read/PATCH one field without loading the body (#412 github-body-field, #424 github-rollup) - fetch-upfront — batch per-item round-trips (#347) - preflight-classifier — skip obvious no-ops before LLM passes (#414/#416) SKILL.md is 297 lines; the pass catalogue (smell / exemplar PR / mechanics / behavior-preservation guarantee / validation) lives in the patterns.md sibling. Reads only framework-internal files, so no injection-guard / Privacy-LLM callouts. Ships a step-diagnose eval (5 auto-comparable cases incl. an injection-resistance case) so the skill is not released without an eval (P8). Wires the skill into the capability->skill map and the eval index. Generated-by: Claude Code (Opus 4.8)
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
1 participant
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.
Summary
Profiling a 12-tracker bulk sync showed every subagent loading the full 3425-line SKILL.md (~30K tokens) regardless of which step it was running. Extract the four heaviest sections into focused subdocs so subagents can load just the slice they need.
Structure
Subagent loading savings
Notes for reviewers
Test plan
🤖 Generated with Claude Code