From d12be3f0209865a0b39256c412e7f39c137812b8 Mon Sep 17 00:00:00 2001 From: Yelban Date: Mon, 16 Feb 2026 22:09:17 +0800 Subject: [PATCH] Improve SKILL.md v1.1.0: token budgeting, model allocation, Mermaid, language-agnostic Co-Authored-By: Claude Opus 4.6 --- SKILL.md | 27 +++++++++++++++++++++------ 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/SKILL.md b/SKILL.md index f28a80e..02b88ec 100644 --- a/SKILL.md +++ b/SKILL.md @@ -9,8 +9,8 @@ description: | branch does". Produces a structured markdown spec covering problem statement, product requirements, architecture, technical design, file inventories, testing strategy, rollout plan, and risks. author: Codex -version: 1.0.0 -date: 2026-02-15 +version: 1.1.0 +date: 2026-02-16 tags: [documentation, git, branch-analysis, spec, reverse-engineering] --- @@ -46,8 +46,16 @@ git diff --stat ...HEAD # 3. Count the scale git diff --stat ...HEAD | tail -1 + +# 4. Estimate diff token budget (chars / 4 ≈ tokens) +git diff ...HEAD | wc -c ``` +**Agent scaling by token budget:** +- **<50k tokens** → single agent (read all diffs directly) +- **50k–200k tokens** → 2–3 agents +- **200k+ tokens** → 3–4 agents, max ~150k tokens per agent + From the diff stats, categorize files into groups: - **Core implementation** (new modules, business logic) - **Integration points** (modified selectors, reducers, hooks, components) @@ -60,6 +68,11 @@ From the diff stats, categorize files into groups: Launch 2-4 parallel exploration agents, each focused on a different file group. This is critical for efficiency — reading 50+ files sequentially is too slow. +**Model allocation:** Use `subagent_type: "Explore"` with `model: "sonnet"` for all +exploration agents. Sonnet handles file reading and analysis (best cost/capability ratio). +The orchestrating model (Opus) plans assignments, synthesizes reports, and infers product +motivation — it should never read diff files directly. + **Agent 1: Core Implementation** - All new files (the heart of the feature) - Focus on: purpose, key types, exported functions, data flow, inter-module connections @@ -87,8 +100,8 @@ Each agent prompt should ask for: After agents return, diff the analyzed files against the full file list: ```bash -# List all non-test changed files -git diff --stat ...HEAD -- '*.ts' '*.tsx' | awk '{print $1}' | sort +# List all changed files (language-agnostic) +git diff --name-only ...HEAD | sort # Show small diffs for any files not yet analyzed git diff ...HEAD -- @@ -128,10 +141,12 @@ What is and isn't included. ## 4. Architecture ### 4.1 System Diagram -ASCII diagram showing component relationships and data flow. +Mermaid `graph TB` diagram showing component relationships and data flow. +(Mermaid renders natively on GitHub/GitLab — prefer over ASCII.) ### 4.2 Data Lifecycle -Step-by-step flow from initial state through steady state. +Mermaid `sequenceDiagram` or step-by-step description showing flow +from initial state through steady state. ## 5. Technical Design Subsections for each major design decision: