@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/skills/distilled/distilled-finishing-a-development-branch.md

@@ -0,0 +1,213 @@
+---
+name: distilled-finishing-a-development-branch
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: finishing-a-development-branch (score 4/5)'
+keywords:
+  - finishing
+  - development
+  - branch
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/obra/superpowers.git
+    license: MIT
+    commit: f2cbfbefebbfef77321e4c9abc9e949826bea9d7
+    paths:
+      - finishing-a-development-branch/SKILL.md
+distilled_at: '2026-06-15T00:51:18.934Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 4
+it_universal_dims:
+  d1: 1
+  d2: 0.5
+  d3: 0.5
+  d4: 1
+  d5: 1
+it_universal_rationale: >-
+  Language-neutral git workflow with environment-detection and structured options; only minor
+  worktree-path conventions need adapting per harness.
+---
+
+# Finishing a Development Branch
+
+## When to use
+- Implementation is complete and you need to integrate or dispose of the work
+- You are on a feature/fix branch and all tests pass
+- You need to choose between merge, PR, keep, or discard in a structured way
+- Working with git worktrees and must avoid phantom-state cleanup mistakes
+
+## Core idea
+
+Before presenting any option to the user, always verify tests pass—broken code must not be merged or pushed. Next, detect the git workspace state (normal repo vs. named-branch worktree vs. detached HEAD) because this controls which options are valid and how cleanup works. Present exactly 4 options (or 3 for detached HEAD) so the conversation stays concrete. Execute in safe order: merge first, remove worktree second, delete branch last. Apply worktree cleanup only for merge/discard paths and only for worktrees your tooling created (provenance check), never for harness-owned workspaces.
+
+## Steps
+
+### 1 — Verify tests
+
+Run the project's test suite before anything else:
+
+```bash
+# Pick the right command for your stack:
+npm test          # Node/JS
+cargo test        # Rust
+pytest            # Python
+go test ./...     # Go
+# etc.
+```
+
+If tests fail, stop. Show the failures and do not proceed to menu.
+
+### 2 — Detect workspace state
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+| State | Menu | Worktree cleanup? |
+|---|---|---|
+| `GIT_DIR == GIT_COMMON` (normal repo) | 4 options | No worktree exists |
+| `GIT_DIR != GIT_COMMON`, named branch | 4 options | Provenance-based (Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | 3 options | No (externally managed) |
+
+### 3 — Determine base branch
+
+```bash
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+If ambiguous, ask: "This branch split from `main` — is that correct?"
+
+### 4 — Present options
+
+**Normal repo / named-branch worktree → exactly 4 options:**
+
+```
+Implementation complete. What would you like to do?
+
+1. Merge back to <base-branch> locally
+2. Push and create a Pull Request
+3. Keep the branch as-is (I'll handle it later)
+4. Discard this work
+
+Which option?
+```
+
+**Detached HEAD → exactly 3 options:**
+
+```
+Implementation complete. You're on a detached HEAD (externally managed workspace).
+
+1. Push as new branch and create a Pull Request
+2. Keep as-is (I'll handle it later)
+3. Discard this work
+
+Which option?
+```
+
+Keep the menu concise — no extra explanation inline.
+
+### 5 — Execute the chosen option
+
+#### Option 1 — Merge locally
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+# Re-run tests on merged result; stop if they fail
+```
+
+After tests pass on merged result → run Step 6 cleanup, then:
+
+```bash
+git branch -d <feature-branch>
+```
+
+#### Option 2 — Push and create PR
+
+```bash
+git push -u origin <feature-branch>
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+- <bullet 1>
+- <bullet 2>
+
+## Test Plan
+- [ ] <verification step>
+EOF
+)"
+```
+
+**Do NOT clean up the worktree** — user needs it for PR iteration.
+
+#### Option 3 — Keep as-is
+
+Report: "Keeping branch `<name>`. Worktree preserved at `<path>`."
+Do nothing else.
+
+#### Option 4 — Discard
+
+First confirm with the user:
+
+```
+This will permanently delete:
+- Branch <name>
+- All commits: <list>
+- Worktree at <path> (if applicable)
+
+Type 'discard' to confirm.
+```
+
+Wait for the exact word `discard`. Then:
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+# Run Step 6 cleanup first, then:
+git branch -D <feature-branch>
+```
+
+### 6 — Worktree cleanup (Options 1 and 4 only)
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+- **`GIT_DIR == GIT_COMMON`**: Normal repo, no worktree. Done.
+- **Worktree path is under your tooling's managed directories** (e.g. `.worktrees/`, `worktrees/`, or your harness's configured path): you own cleanup.
+
+  ```bash
+  MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+  cd "$MAIN_ROOT"
+  git worktree remove "$WORKTREE_PATH"
+  git worktree prune   # self-healing: remove stale registrations
+  ```
+
+- **Otherwise**: The host harness owns this workspace. Do **not** remove it. Use the harness's workspace-exit mechanism if available; otherwise leave it in place.
+
+## Quick-reference matrix
+
+| Option | Merge | Push | Keep worktree | Delete branch |
+|---|---|---|---|---|
+| 1 Merge locally | ✓ | — | no | yes (soft) |
+| 2 Create PR | — | ✓ | **yes** | — |
+| 3 Keep as-is | — | — | **yes** | — |
+| 4 Discard | — | — | no | yes (force) |
+
+## Anti-patterns
+
+- **Skipping test verification** — never offer the menu before tests pass
+- **Open-ended "what next?"** — always present the numbered menu, not a free-form question
+- **Cleaning up worktree for PR path** — user needs it alive for review feedback
+- **Deleting branch before removing worktree** — `git branch -d` will fail; remove worktree first
+- **Running `git worktree remove` from inside the worktree** — always `cd` to main repo root first
+- **Removing harness-owned worktrees** — provenance check required; only remove what your tooling created
+- **Merging without re-running tests** — always verify tests on the merged result, not just the feature branch
+- **Skipping discard confirmation** — require the typed word `discard`; do not proceed on "yes"
+
+## References
+- Upstream: https://github.com/obra/superpowers.git

package/dist/skills/distilled/distilled-frontend-design.md

@@ -0,0 +1,118 @@
+---
+name: distilled-frontend-design
+version: 0.2.0-distilled
+description: 'Distilled IT-universal skill: frontend-design (score 4.5/5)'
+keywords:
+  - frontend
+  - design
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/anthropics/skills.git
+    license: Apache-2.0
+    commit: 690f15cac7f7b4c055c5ab109c79ed9259934081
+    paths:
+      - frontend-design/SKILL.md
+distilled_at: '2026-06-15T01:09:37.059Z'
+distilled_by: claude-code skill-distiller agent
+it_universal_score: 4.5
+it_universal_dims:
+  d1: 0.5
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: >-
+  Pure design-methodology skill covering HTML/CSS/JS/React/Vue with no repo-specific paths, no
+  IDE/CI lock-in, and transferable aesthetic doctrine applicable to any web UI project.
+---
+
+# Production-Grade Frontend Design (Avoiding Generic AI Aesthetics)
+
+## When to use
+- Building any web UI: components, pages, dashboards, landing pages, posters, or full apps
+- Styling or beautifying an existing interface
+- Generating HTML/CSS/JS, React, Vue, or other frontend artifacts
+- When the goal is a memorable, polished result rather than "functional but forgettable"
+
+## Core idea
+Before writing a single line of code, commit to a **bold, intentional aesthetic direction** and execute it with precision. The biggest failure mode in AI-generated UI is converging on the same generic choices (purple gradients, Inter font, evenly-distributed pastels, predictable card layouts). Instead, pick an extreme — brutally minimal, maximalist chaos, retro-futuristic, editorial, industrial — and pursue it without hedging. Production-quality comes from cohesion and intentionality, not complexity. A restrained minimal design is as valid as an elaborate maximalist one, provided every detail serves the chosen direction. The one rule: no two designs should look the same.
+
+## Steps
+
+### 1. Design Thinking (before coding)
+Answer four questions explicitly:
+- **Purpose**: What problem does this UI solve? Who are the users?
+- **Tone**: Choose a specific aesthetic extreme (see palette below). Name it; commit to it.
+- **Constraints**: Framework requirements, performance targets, accessibility needs.
+- **Differentiator**: What is the single most memorable thing about this design?
+
+**Aesthetic palette to choose from (non-exhaustive):**
+Brutally minimal · Maximalist chaos · Retro-futuristic · Organic/natural · Luxury/refined · Playful/toy-like · Editorial/magazine · Brutalist/raw · Art deco/geometric · Soft/pastel · Industrial/utilitarian · Vaporwave · Swiss grid · Dark gothic · Cottagecore · Bauhaus
+
+### 2. Typography
+- Select **two** fonts: a distinctive display font + a refined body font. Pair them with contrast (serif + grotesque, slab + geometric sans, etc.).
+- Avoid: Arial, Roboto, Inter, system-ui, and any font that reads as "AI default".
+- Use large, expressive type scales — big headings create hierarchy without extra elements.
+- Letter-spacing, line-height, and font-weight are as important as font choice.
+
+### 3. Color & Theme
+- Define a **dominant color** + one or two **sharp accent** colors via CSS custom properties (`--color-*`).
+- Avoid timid, evenly-distributed palettes. High contrast between dominant and accent creates energy.
+- Alternate between dark-background and light-background themes across generations — never default to white.
+- All color decisions should flow from `var(--*)` tokens for easy theming.
+
+```css
+:root {
+  --bg: #0c0c0c;
+  --surface: #1a1a1a;
+  --accent: #e8ff5a;        /* sharp, single accent */
+  --text: #f0ede8;
+  --text-muted: #888;
+}
+```
+
+### 4. Motion & Animation
+- Prefer **CSS-only** animations for HTML artifacts; use Motion/Framer Motion for React when available.
+- Focus effort on **one well-orchestrated moment**: a staggered page load with `animation-delay` creates more delight than many scattered micro-interactions.
+- Use scroll-triggered reveals and hover states that **surprise** the user.
+- Animations should reinforce the aesthetic (brutalist: snappy/hard cuts; luxury: slow eases; playful: bouncy springs).
+
+```css
+/* Staggered reveal pattern */
+.item { opacity: 0; transform: translateY(20px); animation: reveal 0.5s ease forwards; }
+.item:nth-child(1) { animation-delay: 0.1s; }
+.item:nth-child(2) { animation-delay: 0.2s; }
+/* ... */
+@keyframes reveal { to { opacity: 1; transform: none; } }
+```
+
+### 5. Spatial Composition
+- Break grid monotony: use asymmetry, overlapping elements, diagonal flow, or grid-breaking accents.
+- Alternate between generous negative space (minimalist) and controlled density (maximalist).
+- Avoid equal-weight columns and predictable card grids unless the aesthetic calls for strict structure.
+
+### 6. Backgrounds & Visual Atmosphere
+Go beyond solid colors. Choose contextually:
+- **Gradient meshes** (radial-gradient composited at multiple positions)
+- **Noise/grain textures** (SVG `feTurbulence` or CSS `backdrop-filter`)
+- **Geometric patterns** (repeating SVG or CSS `background-image: repeating-linear-gradient(...)`)
+- **Layered transparencies** with `rgba` + `backdrop-filter: blur()`
+- **Dramatic shadows** as design elements, not just depth cues
+- **Decorative borders / ruled lines** for editorial aesthetics
+
+### 7. Implementation discipline
+- Match code complexity to aesthetic vision. Maximalist → elaborate animations and effects. Minimalist → restraint, precise spacing, subtle details.
+- Ship working code, not wireframes. All interactive states (hover, focus, active, disabled) must be designed.
+- Use semantic HTML; keep accessibility a baseline, not an afterthought (`aria-*`, focus rings, contrast ratios).
+
+## Anti-patterns
+- ❌ Inter / Roboto / Arial / system-ui as the "default" font
+- ❌ Purple-gradient-on-white-background as the "default" color scheme
+- ❌ Predictable card-grid layouts with equal gutters everywhere
+- ❌ Timid, evenly-distributed pastel palettes
+- ❌ Space Grotesk or similar "popular AI pick" fonts repeated across designs
+- ❌ Animations on every element rather than one orchestrated focal moment
+- ❌ Generating the same aesthetic twice — vary theme (light/dark), font pairing, and spatial logic each time
+
+## References
+- Upstream: https://github.com/anthropics/skills.git

package/dist/skills/distilled/distilled-harness-engineering.md

@@ -0,0 +1,242 @@
+---
+name: distilled-harness-engineering
+version: 0.1.0-distilled
+description: 'Distilled IT-universal skill: harness-engineering (score 5/5)'
+spawn_agent: safety-net-implementer
+keywords:
+  - harness
+  - engineering
+  - legacy
+  - 遗留代码
+  - 特征测试
+  - characterization
+  - 重构
+  - refactor
+  - 改造
+  - 老代码
+rubric_version: 2
+distilled_from:
+  - upstream: https://github.com/winspan/claude-forge.git
+    license: MIT
+    commit: 7d96b86c
+    paths:
+      - official/official-harness-engineering.md
+distilled_at: '2026-05-27T02:00:47.967Z'
+distilled_by: claude-sonnet-4-6
+it_universal_score: 5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: Characterization-tests-first refactor; SDLC universal.
+---
+
+## 触发条件
+
+- 需要修改缺少测试覆盖的现有代码（遗留代码、接手的陌生代码库）
+- 代码复杂度高，直接改动风险大，担心破坏现有行为
+- 计划进行大规模重构或模块迁移
+- 接手高风险核心模块，需要在理解行为后再动手
+- 现有代码有隐含假设或副作用，需要先记录再修改
+
+---
+
+## 核心原则
+
+1. **先保护，后修改** — 在任何改动之前，用测试固化现有行为，确保改动有安全网兜底。
+2. **特征测试记录现实，不评判对错** — 测试描述"代码现在做什么"，即使存在 bug 也先如实记录，避免在理解阶段引入主观判断。
+3. **小步前进，即时验证** — 每次只改一处，改完立即运行测试套件；测试失败立即回滚，不积累未验证的变更。
+4. **行为一致性是重构的唯一成功标准** — 重构完成后，外部可观测行为必须与原始行为文档一致；新功能用新测试覆盖，不混入重构过程。
+5. **与 TDD 的边界清晰** — TDD 用于新功能（先写测试再实现）；Harness Engineering 用于改动现有代码（先理解再保护再修改），两者目的不同，不可混用。
+
+---
+
+## 工作流
+
+**复杂度判断（入口）**
+
+| 复杂度 | 描述 | 流程 |
+|--------|------|------|
+| 简单 | 改动范围小、依赖少 | 跳过阶段 1，直接从阶段 2 开始 |
+| 中等 | 多模块依赖、有副作用 | 完整四阶段 |
+| 复杂 | 核心模块、跨层依赖、高风险迁移 | 完整四阶段 + 额外人工审查 |
+
+---
+
+**阶段 1 — 理解（Understand）**
+
+1. 阅读目标代码，识别关键逻辑、边界条件和隐含假设。
+2. 绘制依赖关系图：哪些调用方依赖这段代码，哪些外部资源（数据库、网络、文件系统）被访问。
+3. 找到所有入口点（公开接口、事件触发点）和输出点（返回值、副作用、写操作）。
+4. 输出**行为文档**：以自然语言或表格记录当前实际行为，作为后续阶段的基准。
+
+---
+
+**阶段 2 — 特征测试（Characterize）**
+
+5. 针对行为文档中的每条行为编写特征测试（Characterization Tests），覆盖正常路径、边界条件和已知异常路径。
+6. 运行测试套件，确保**全部通过**（目标覆盖率 > 80%）。若测试失败，说明行为文档有遗漏，先补文档再补测试，不修改被测代码。
+7. 全绿后方可进入下一阶段。
+
+---
+
+**阶段 3 — 安全重构（Refactor）**
+
+8. 按优先级逐步重构：消除重复 → 提取函数/模块 → 改善命名 → 简化复杂逻辑。每次只改一处，改完立即运行完整 harness；测试失败立即回滚。
+
+---
+
+**阶段 4 — 验证（Verify）**
+
+在阶段 3 完成后执行：运行完整测试套件；对照原始行为文档逐条确认行为一致性；进行代码审查；新增行为用新测试覆盖，旧特征测试在确认无用后逐步退役。
+
+---
+
+## 反模式
+
+1. **边理解边修改** — 在行为文档和特征测试建立之前就动手改代码，导致无法判断改动是否破坏了原有行为。
+2. **特征测试写"应该怎样"而非"现在怎样"** — 将期望行为写入特征测试，掩盖了现有 bug，后续重构时误以为行为已修复。
+3. **大步重构，延迟运行测试** — 一次性改动多处后才运行测试，失败时无法定位是哪一步引入的问题。
+4. **测试失败后继续前进** — 不回滚、不修复，带着红色测试继续重构，导致安全网失效。
+5. **将重构与新功能开发混在同一次提交** — 行为变更和结构变更混合，代码审查和问题定位都变得困难。
+
+---
+
+## 验证标准
+
+完成 Harness Engineering 流程后，逐项确认：
+
+- [ ] 行为文档已输出，覆盖所有已知入口点、输出点和边界条件
+- [ ] 特征测试覆盖率 ≥ 80%，且在重构开始前全部通过（全绿）
+- [ ] 重构过程中每一步改动后测试均保持全绿；出现红色时已立即回滚
+- [ ] 重构完成后，外部可观测行为与行为文档逐条一致
+- [ ] 新增行为有独立的新测试覆盖，未混入特征测试
+- [ ] 代码审查已完成，无遗留的 TODO / 临时注释
+- [ ] 旧特征测试中已无用的部分已标记退役或删除
+
+---
+
+## 适用范围
+
+本技能适用于以下通用层次，与具体技术栈无关：
+
+- **后端服务** — 业务逻辑层、API 处理层、中间件
+- **持久化层** — 数据库访问、文件读写、缓存操作
+- **CLI 工具** — 命令解析、子命令处理、输出格式化
+- **前端** — 组件逻辑、状态管理、数据转换工具函数
+- **调度器 / 后台任务** — 定时任务、队列消费者、事件处理器
+- **知识库 / 配置加载** — 配置解析、数据初始化、静态资源处理
+
+> 任何存在"不敢改、不了解、没有测试"的代码模块，均适用本技能。
+
+---
+
+## 上游对照
+
+本技能从单一上游的 harness-engineering 规范（来源见 frontmatter）提炼，核心方法论源自 Michael Feathers《Working Effectively with Legacy Code》的特征测试思想。上游文档包含特定 Agent 调用建议（`researcher` / `tester` / `refactor-specialist`），已泛化为通用流程步骤，适配任意项目的工具链和团队分工。
+
+---
+
+## 示例（伪代码）
+
+场景：对一个缺少测试的"用户权限校验"模块进行重构。
+
+### 阶段 1 — 理解
+
+```
+// 阅读 auth_check 模块，记录行为文档
+behavior_doc = {
+  inputs:  [user_id, resource_id, action],
+  outputs: [bool: allowed, side_effect: audit_log_write],
+  paths: [
+    "user not found → return false",
+    "resource not found → raise NotFoundError",
+    "user.role == 'admin' → return true (skip resource check)",
+    "user.permissions includes action → return true",
+    "otherwise → return false + write audit log"
+  ],
+  hidden_deps: ["reads from cache first, falls back to DB", "audit log is async"]
+}
+```
+
+### 阶段 2 — 特征测试
+
+```python
+# Python
+def test_admin_always_allowed():
+    assert auth_check(admin_user, any_resource, "delete") == True
+
+def test_unknown_user_denied():
+    assert auth_check(unknown_id, resource, "read") == False
+
+def test_missing_resource_raises():
+    with raises(NotFoundError):
+        auth_check(user, nonexistent_resource, "read")
+
+def test_permitted_action_allowed():
+    assert auth_check(user_with_read, resource, "read") == True
+
+def test_denied_action_writes_audit():
+    auth_check(user_no_perms, resource, "write")
+    assert audit_log.last_entry.action == "write"
+```
+
+```typescript
+// TypeScript
+test("admin always allowed", () => {
+  expect(authCheck(adminUser, anyResource, "delete")).toBe(true);
+});
+test("unknown user denied", () => {
+  expect(authCheck(unknownId, resource, "read")).toBe(false);
+});
+test("missing resource raises", () => {
+  expect(() => authCheck(user, nonexistentResource, "read")).toThrow(NotFoundError);
+});
+```
+
+```go
+// Go
+func TestAdminAlwaysAllowed(t *testing.T) {
+    result, _ := authCheck(adminUser, anyResource, "delete")
+    assert.True(t, result)
+}
+func TestUnknownUserDenied(t *testing.T) {
+    result, _ := authCheck(unknownID, resource, "read")
+    assert.False(t, result)
+}
+```
+
+> 运行测试套件 → 全绿 → 进入阶段 3。
+
+### 阶段 3 — 安全重构（小步示例）
+
+```
+// 步骤 A：提取 "admin shortcut" 为独立函数
+function isAdminShortcut(user, action) → bool
+
+// 运行 harness → 全绿 → 提交
+
+// 步骤 B：提取 "permission lookup" 为独立函数
+function hasPermission(user, resource, action) → bool
+
+// 运行 harness → 全绿 → 提交
+
+// 步骤 C：将 audit log 写入改为显式调用，消除隐式副作用
+// 运行 harness → 某测试红色 → 立即 git revert 步骤 C → 分析原因
+```
+
+### 阶段 4 — 验证
+
+```
+// 对照行为文档逐条验证
+✓ "admin → true"              — test_admin_always_allowed 通过
+✓ "user not found → false"    — test_unknown_user_denied 通过
+✓ "resource not found → raise"— test_missing_resource_raises 通过
+✓ "permitted → true"          — test_permitted_action_allowed 通过
+✓ "denied → audit log"        — test_denied_action_writes_audit 通过
+
+// 新增行为（重构后 audit log 改为显式）→ 新增独立测试覆盖
+// 旧特征测试中针对隐式副作用的断言 → 标记退役
+```

package/dist/skills/distilled/distilled-karpathy-guidelines.md

@@ -0,0 +1,104 @@
+---
+name: distilled-karpathy-guidelines
+version: 0.2.0-distilled
+description: "Karpathy 4 条 LLM 编程铁律 — moved as-is, not re-distilled (already a distillation of multica-ai/andrej-karpathy-skills)"
+keywords:
+  - karpathy
+  - guidelines
+  - 编程原则
+  - 编程铁律
+  - simplicity
+  - surgical
+  - goal-driven
+  - 简洁优先
+  - 外科手术
+  - 目标可验证
+  - 行数预算
+  - 可验证判据
+  - 事前思考
+  - think before coding
+distilled_from:
+  - upstream: https://github.com/multica-ai/andrej-karpathy-skills
+    license: MIT
+    commit: as-is-moved
+    paths:
+      - "andrej-karpathy-skills/SKILL.md (via local official-karpathy-guidelines.md)"
+distilled_at: '2026-05-27T01:02:33.000Z'
+distilled_by: "as-is-copy (Q8 spec 0849; not re-distilled to avoid lossy compression)"
+it_universal_score: 5
+it_universal_dims:
+  d1: 1
+  d2: 1
+  d3: 1
+  d4: 1
+  d5: 1
+it_universal_rationale: "Karpathy 4 principles are themselves an IT-universal distillation; re-distilling would be lossy."
+move_provenance: "copied as-is from upstream per spec 0849 Q8"
+---
+
+# Karpathy 编程铁律（4 条）
+
+源自 Andrej Karpathy 总结的 LLM 常见踩坑（multica-ai/andrej-karpathy-skills，
+MIT），转成事前提示 + 自查清单。这 4 条与「任何项目」开发流程中常见的「自检 →
+Plan-then-Implement → Agent 委托」模式一致；本 skill 把它们提炼成任何任务开始
+前可快速过一遍的具体动作。
+
+## 1. Think Before Coding（事先思考）
+
+把**模糊**换成**明确**，把**隐式假设**换成**显式问题**。
+
+实操：
+- 任务里有不确定的地方 → 在 spec / agent prompt / commit message 里**写出来**
+- 强烈推荐采用 Plan-then-Implement 工作流（先出 spec → review → 实施），
+  本身就是这条原则的强制路径
+- 自查："这个改动假设了什么？任何一个假设错了会怎样？"
+- 触发 → 用 planner-type agent 出 spec；spec 必须包含 "Open questions" 段
+
+## 2. Simplicity First（简洁优先）
+
+LLM 倾向于过度设计：加抽象层、写"以后可能用"的代码、引入新依赖。**默认拒绝**。
+
+实操：
+- 3 行重复优于 1 个早熟抽象
+- 不要为"未来可能的需求"留 hook
+- 改动**行数预算**：bug fix ≤ 50 行 / feature ≤ 200 行 / 超出 → 拆分
+- 重写优于打补丁：旧代码改动 > 60% 时，整段重写比逐处 patch 更易读
+- 对应通用原则："Do what has been asked; nothing more, nothing less"
+
+## 3. Surgical Changes（外科手术式修改）
+
+只改用户**明确**要求的代码。保留：
+- 现有 dead code（不在你 scope 内）
+- 现有命名风格（一致性 > 个人审美）
+- 现有"看起来糟糕但能跑"的代码
+
+实操：
+- 改 1 个函数的 bug，不要顺手"清理"邻居函数
+- 用 `git diff` 自查改动范围：超出 scope → 拆分另一个 commit
+- 涉及 ≥2 文件 → 推荐 spawn 专门 agent 处理；agent prompt 写明
+  "DO NOT touch X, Y, Z"
+- 反模式："顺手把这块也优化了" → 多半要回滚 + 拆 PR
+
+## 4. Goal-Driven Execution（目标可验证）
+
+**不要**写不可验证的目标。LLM 在不可验证目标上倾向"自我宣告成功"。
+
+❌ 反例：
+- "修复 X bug" / "性能更好" / "代码更清晰" / "完整修复"
+
+✅ 正例：
+- "后台服务重启 → 100 个工具调用全部入事件表 → SELECT COUNT(*) > 0"
+- "tasks-routes.test.ts 21/21 通过 + agent_detail.subagent_type === 'researcher'"
+- "DB 文件大小 275MB → 50MB；events 表行数 42k → 30k"
+
+实操：
+- 任何 spec 必须有 `## Success criteria` 段（planner-type agent 应强制）
+- 判据要可执行（命令 / SQL / 测试名 / 浏览器步骤 / 数字阈值）
+- 主线程交付前自查："这条判据能 run 吗？" 不能 → 改写
+
+## 触发条件
+
+本 skill 适合在以下任务前注入：
+- 新功能 / 重构 / Bug 修复（任何 ≥3 文件改动）
+- Plan-then-Implement 流程的 spec 撰写阶段
+- 主线程委托 sub-agent 前（让 agent prompt 引用本 skill 4 条）