docs(skill-md): TOC + Rules-at-a-glance + dedup Tech Stack / Repo Structure (Optimization PR E)#145
Merged
Merged
Conversation
… PR E) Fifth PR in the .md optimization sequence (Option D). SKILL.md is the long-form rulebook (Rules 1-18 + schema-version table + library matrix). It's referenced on-demand, so size matters less than for CLAUDE.md — but the heavy duplication with CLAUDE.md (§Stack) and AGENTS.md (§Project structure) bloated it for no marginal value. SKILL.md (641 → 574 lines, -10%): Added: - §Contents — table-of-contents with anchor links to every section - §"Rules at a glance" — 1-row-per-rule summary table for Rules 1-18, with "Most-cited from" column so readers can find the source of truth fast (e.g., Rule 16 → CLAUDE.md §Conventions + top5-rotation-audit skill; Rule 18 → CLAUDE.md + WORKFLOW.md + portable-observability-before-wiring skill) Dedup'd to reference canonical sources: - §Required Tech Stack (68 → 39 lines): full Python-libraries block dropped (was duplicating CLAUDE.md §Stack). Kept the phase-specific stretch additions (Kaggle / Modal / Whisper / factor libs) + the optional-dep license table by phase. Added mlfinlab-is-BANNED note (was buried earlier). - §Mandatory Repository Structure (97 → 26 lines): 90-line ASCII file tree duplicated AGENTS.md §Project structure with stale annotations. Replaced with a module-level table that locks the per-phase responsibility breakdown (ingest / features / scoring / valuation / ml / portfolio / output) — the structural contract future phases must respect. Rules 1-18 kept verbatim. Rule numbers are stable inbound-reference anchors — renumbering would break CLAUDE.md / AGENTS.md citations. CLAUDE.md (181 → 181, per-PR lockstep): - §Phase status "Recently merged" — added PR #144 (D archive); dropped #140 (now 4 entries past the bar) - §Phase status — replaced "PR D in flight" tracker with "PR E in flight" note covering SKILL.md restructure scope AGENTS.md (343 → 343, per-PR lockstep): - §Phase + version state — optimization sequence tracker updated: PR D ✅ → PR E in flight, PR F-G remaining Why this matters for Claude effectiveness: - The Rules-at-a-glance table makes "Rule 16" / "Rule 18" lookups one scroll instead of a search. When CLAUDE.md says "see Rule 18", Claude can now find which other docs cite that rule (so a change to Rule 18 wording / interpretation can be propagated correctly). - Dedup'd Tech Stack + Repo Structure sections were dead weight when Claude already has those facts from CLAUDE.md / AGENTS.md. Now SKILL.md adds only what THOSE files don't have (phase-stretch deps with license posture; module-level phase ownership). Next in sequence: PR F (skill description audit ×38 — TRIGGER / SKIP clarity + length normalization) · PR G (PHASE_STATUS.md "Current State" summary at top).
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
dackclup
added a commit
that referenced
this pull request
May 20, 2026
…imization PR F) (#146) Sixth PR in the .md optimization sequence (Option D). Audit of 18 QR-origin skill descriptions found all are well-formed (parseable YAML, TRIGGER + SKIP clauses present, average 888 chars). The critical YAML bug (#119+#121 plain-scalar bug in branch-collision- check and pr-quality-gate) was already fixed in PR A. So PR F's remaining work is light polish, not structural change. Vendored skills (20) FROZEN per the boundary convention — Anthropic skills, mattpocock-* (8), karpathy-guidelines, thananon/9arm-skills (4), karpathy-llm-wiki are all upstream-only edits. Trim targets (cut redundancy, fix drift, add Thai triggers): 1. pr-quality-gate (1207 → ~1015): cut redundant "ALSO use right before flipping Draft→Ready" clause that duplicated the first TRIGGER ("before authorizing the Draft→Ready flip"). Tightened wrapping. 2. pr-iteration-flow (990 → ~890): cut redundant "ALSO use this skill as the default workflow harness any time a PR is open" that duplicated the TRIGGER list. Dropped stale "PR-3c → PR-3d → PR-20" historical reference. Added Thai trigger phrases "เช็ค CI" / "ดู PR" since the user invokes this skill in Thai. 3. phase-status-bump (918 → ~840): dropped two historical examples ("PR 3d → tag v0.6.0-phase3d" and "3a→3b, 3c→3d") that anchored the description to one shipped phase. Wording now phase-agnostic. 4. verify-production-output (1086 → ~870): compressed the "Surfaces..." enumeration of Section A-H content (was 8 detailed items; now 8 short items) without losing dispatch specificity. Added Thai trigger phrases "ตรวจ output" / "เช็ค production". Folded "ALSO use" into first TRIGGER as one phrase. YAML moved from plain scalar to `description: >` (folded block) on the 3 plain-scalar descriptions edited (pr-iteration-flow, phase-status-bump, verify-production-output) — same safety pattern PR A applied. Prevents the ' #' comment-eating bug from re-emerging if anyone adds a `#issue` reference later. Net token impact: ~-650 chars × ~0.25 tokens/char ≈ -162 tokens per session-start. Modest but compounds. Why not aggressive trim: - Each TRIGGER phrase + SKIP clause IS dispatch-useful — verified by sampling. Aggressive 50% cuts would risk dispatch quality. - Remaining 14 QR-origin skills already at 700-900 chars with no redundancy to remove. CLAUDE.md (181 → 181, lockstep): §Phase status — added PR #145 (E) to "Recently merged"; replaced "PR E in flight" with "PR F in flight" note explaining the audit found health. AGENTS.md (343 → 343, lockstep): §Phase + version state — optimization sequence tracker updated: PR E ✅, PR F in flight, PR G remaining. Next: PR G (PHASE_STATUS.md "Current State" summary at top + chronological table below). Co-authored-by: Claude <noreply@anthropic.com>
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
2 participants
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
PR E in the
.mdoptimization sequence (Option D). SKILL.md is the long-form rulebook (Rules 1-18 + schema-version table + library matrix). Referenced on-demand, so size matters less than for CLAUDE.md — but heavy duplication with CLAUDE.md §Stack and AGENTS.md §Project structure bloated it for no marginal value.Numbers
What this PR adds
§Contents — table-of-contents with anchor links to every section. Makes "Rules" / "Schema" / "Anti-Patterns" lookups one click.
§Rules at a glance — 1-row-per-rule summary for Rules 1-18, with a "Most-cited from" column so readers can find the source of truth:
(Rules 1-8, 10-15, 17 also listed but with no cross-doc citation — they're SKILL.md-canonical.)
What this PR dedup's
mlfinlab is BANNED(Hudson & Thames commercial)3 active vetoes/_EIGHT_K_DEFENSES_ENABLED = False)What this PR does NOT touch
pre-merge-prod-sim.ymlwon't trigger.Why this matters for Claude effectiveness
Cumulative results across PRs A-E
Next in sequence (NOT this PR)
Test plan
pre-merge-prod-sim.ymldoes not triggerhttps://claude.ai/code/session_015649aRyi2bvciQYZVNACd2
Generated by Claude Code