@miphamai/cli 0.77.2 → 0.78.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miphamai/cli",
-  "version": "0.77.2",
+  "version": "0.78.0",
   "description": "Mipham Code — Multi-model open-core intelligent coding terminal by MiphamAI",
   "keywords": [
     "ai",

package/skills/standard/trim-process-prose.SKILL.md

@@ -0,0 +1,50 @@
+---
+name: trim-process-prose
+description: Use when cleaning process-perspective narration an AI left in code, comments, docs, or commit messages — "originally A, changed to B", design-decision references, or review back-and-forth a reader with only the current checkout cannot independently parse or verify
+version: 1.0.0
+---
+
+# Trim Process Prose
+
+Agents leave their working perspective in the repo — "initially we used A, then the reviewer wanted B", "decision 7", "for now, fix later" — which only makes sense inside the session that produced it. Months later a maintainer has only the checkout, not the chat, the PR thread, or the task plan. That residue is process prose.
+
+## The test
+
+For any sentence a change adds — a comment, a doc line, a commit-message clause — ask:
+
+> **Can a reader holding only the current HEAD checkout independently parse and verify this?**
+
+- **Yes** → keep it.
+- **No** → keep the durable fact, drop the process.
+
+The fact is what a future maintainer needs; the process is how you got there, and it dies with the session.
+
+## What to keep vs drop
+
+| Keep (durable)                                                                          | Drop (process)                                                             |
+| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| Why B is _required_: "B is used here because A leaks resources under concurrent cancel" | How you chose it: "initially A, then reviewer preferred B"                 |
+| A contract/invariant: "this must hold or X breaks"                                      | A reference a HEAD reader can't resolve: "decision 7", "C2", "design §4.7" |
+| A precondition/postcondition the next editor must respect                               | A status marker: "for now", "v3 will handle this", "TODO after PR"         |
+| A compatibility promise                                                                 | A review trace: "reviewer confirmed", "per discussion"                     |
+
+## Rewrite, don't annotate
+
+```diff
+- // originally plan A had a race; reviewer asked for B; switching to B
++ // B: plan A could not guarantee resource release under concurrent cancel
+```
+
+The second line is the only thing the next maintainer needs. The first line is archaeology.
+
+## When NOT to touch
+
+- A sentence that already passes the HEAD-reader test — do not strip facts to be tidy.
+- A working session in progress — trim at commit/push time, not while reasoning.
+- `docs/truth/**` claims that cite `file:line` — those are evidence, not process.
+
+## Red flags
+
+- "This context is useful" — useful to _you now_; the test is the HEAD reader, not you.
+- Keeping "originally X / changed to Y" — the change is already visible in the diff; the narration is redundant.
+- Leaving a task-plan reference the reader can't resolve — that is the exact leakage to remove.

package/src/shared/package-info.ts

@@ -9,7 +9,7 @@
 export const PACKAGE_NAME = '@miphamai/cli' as const
 
 /** 当前发布版本 */
-export const PACKAGE_VERSION = '0.77.2' as const
+export const PACKAGE_VERSION = '0.78.0' as const
 
 /** npm install 全局安装命令 */
 export const NPM_INSTALL_COMMAND = `npm install -g ${PACKAGE_NAME}` as const

package/src/skills/bundled-skills.ts

@@ -11,6 +11,7 @@ export const BUNDLED_SKILLS: ReadonlyArray<BundledSkill> = [
   { type: 'standard', raw: "---\nname: code-review\ndescription: Code review automation for TypeScript, JavaScript, Python, Go, Swift, Kotlin — complexity analysis, risk assessment, bug detection, and quality scoring\nversion: 2.0.0\n---\n\n# Code Review Skill\n\nAnalyzes code changes for bugs, security risks, performance issues, and code quality. Generates structured review reports.\n\n## Review Dimensions\n\n### 1. Correctness (Bug Detection)\n\n- Logic errors: off-by-one, inverted conditions, missing null checks\n- Type safety: implicit any, missing generics, unsafe casts\n- Error handling: swallowed exceptions, missing try/catch, unhandled promise rejections\n- Edge cases: empty arrays, null/undefined, boundary conditions\n- Race conditions: async/await ordering, shared mutable state\n\n### 2. Security (OWASP Top 10)\n\n- Injection vulnerabilities (SQL, NoSQL, command, template)\n- XSS vectors (innerHTML, dangerouslySetInnerHTML, unescaped output)\n- Authentication/authorization bypass\n- Sensitive data exposure (logs, error messages, client-side)\n- Path traversal and file inclusion\n- Insecure deserialization\n\n### 3. Performance\n\n- N+1 queries (database in loops, repeated API calls)\n- Memory leaks (unclosed connections, event listeners, timers)\n- Unnecessary re-renders (React) or re-computations\n- Large bundle sizes (heavy imports, missing tree-shaking)\n- Missing caching or memoization where beneficial\n\n### 4. Code Quality\n\n- SOLID principles violations\n- Code duplication (DRY violations)\n- Cyclomatic complexity > 10\n- Function length > 50 lines\n- Deep nesting > 4 levels\n- Magic numbers and strings\n- Unclear naming\n\n### 5. Architecture & Design\n\n- Tight coupling between modules\n- Circular dependencies\n- Missing abstraction layers (when needed)\n- Over-engineering (unnecessary abstractions)\n- God objects / classes with too many responsibilities\n\n### 6. Testing\n\n- Missing tests for new code\n- Test coverage gaps for edge cases\n- Flaky tests (non-deterministic)\n- Slow tests (> 1s per test)\n- Test isolation issues (shared state)\n\n### 7. Language-Specific Checks\n\n**TypeScript/JavaScript:**\n\n- Prefer `const` over `let`; avoid `var`\n- Use optional chaining (`?.`) and nullish coalescing (`??`)\n- Async functions should have try/catch\n- No `any` without explicit reason\n- Prefer `interface` over `type` for object shapes\n\n**Python:**\n\n- Type hints on function signatures\n- Context managers for resources (`with` statements)\n- List comprehensions over `map`/`filter` with lambdas\n- No mutable default arguments\n\n**Go:**\n\n- Error handling (never ignore errors)\n- Goroutine lifecycle (no leaks)\n- defer for cleanup\n- Interface segregation\n\n## Review Report Format\n\n```\nCode Review Report\n==================\nBranch: <branch>\nFiles Changed: <count>\nReview Date: YYYY-MM-DD\n\nSummary\n-------\nCritical: N | High: N | Medium: N | Low: N | Info: N\n\nFindings\n--------\n### [Severity] [Category]: [Title]\nFile: `path/to/file.ts:line`\nDescription: [What was found]\nRisk: [Why it matters]\nFix: [How to resolve, with code example if applicable]\n\nScore\n-----\nSecurity:    ★★★★☆\nPerformance: ★★★★☆\nQuality:     ★★★★☆\nTesting:     ★★★★☆\nOverall:     ★★★★☆\n```\n" },
   { type: 'standard', raw: "---\nname: codebase-design\ndescription: Deep module design principles for designing or improving module interfaces. Use when designing a new module, refactoring an existing one, or finding deepening opportunities in the codebase.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Glob\n  - Grep\n  - Edit\n  - Write\n---\n\n# Codebase Design — Deep Module Principles\n\nBased on John Ousterhout's \"A Philosophy of Software Design.\" The core idea: the greatest single factor in software complexity is the depth of modules — how much functionality they provide relative to the size of their interface.\n\n## When to Use\n\n- Designing a new module, API, or component\n- Reviewing existing code for design quality\n- Deciding where to split or join modules\n- User asks: \"is this well-designed?\", \"where should this go?\", \"how should I structure this?\"\n\n---\n\n## Core Concepts\n\n### Deep vs Shallow Modules\n\n```\nDeep Module (good):            Shallow Module (bad):\n┌─────────────────┐            ┌─────────────────┐\n│ small interface  │            │ large interface  │\n│ ┌─────────────┐ │            │ (many params,    │\n│ │             │ │            │  complex setup)  │\n│ │   large     │ │            ├─────────────────┤\n│ │ implementation│            │ small            │\n│ │             │ │            │ implementation   │\n│ └─────────────┘ │            │ (just passes     │\n└─────────────────┘            │  through)        │\n                               └─────────────────┘\n```\n\n**Deep**: Unix file I/O — 5 syscalls (`open`, `read`, `write`, `lseek`, `close`), incredibly powerful implementation.\n\n**Shallow**: A function that takes 12 parameters, validates 3 of them, then calls another function. Interface cost > implementation value.\n\n### The Rule of Deep Modules\n\n> The interface should be as small as possible while providing as much functionality as possible.\n\n- **Cost** = interface complexity (parameters, configuration, setup required)\n- **Benefit** = functionality provided (what the caller no longer needs to worry about)\n- **Depth** = Benefit / Cost\n\n---\n\n## The 5 Design Checks\n\nWhen evaluating a module design, run through these:\n\n### Check 1: Interface Size\n\nCount the effective parameters:\n\n- Required parameters + optional parameters with non-trivial defaults\n- Configuration methods that MUST be called before use\n- Implicit dependencies (global state, env vars, singletons)\n\n**Red flag**: > 4 effective parameters → the module may be too shallow.\n\n**Fix**: Bundle related parameters into a config object. Or split the module.\n\n### Check 2: Information Hiding\n\nDoes the module expose information that callers don't need?\n\n- Internal data structures leaked through the interface\n- Implementation details exposed via parameter types\n- Error types that reveal internal architecture\n\n**Red flag**: Callers import types they don't use directly.\n\n**Fix**: Define a public API type layer. Return opaque handles instead of raw data.\n\n### Check 3: Abstraction Quality\n\nDoes the module represent a single, coherent idea?\n\n- Can you describe what it does in one sentence without \"and\"?\n- Would a new team member guess where to find this functionality?\n- If you remove the module, does exactly one concept go missing?\n\n**Red flag**: Module name contains \"and\", \"Utils\", \"Common\", \"Helpers\".\n\n**Fix**: Split by concept. `UserService` + `EmailService` instead of `UserAndEmailUtils`.\n\n### Check 4: General-Purpose vs Special-Purpose\n\nIs the module solving the general case or a specific use case?\n\n- Would the interface work if requirements changed slightly?\n- Are there hardcoded assumptions that could be parameters?\n- Is the module useful in contexts other than its creator imagined?\n\n**Red flag**: Module only works for one specific call site.\n\n**Fix**: Make the specific case a thin wrapper around the general case. The general module is deep; the wrapper is shallow (and that's fine — wrappers are allowed to be shallow).\n\n### Check 5: Seam Placement\n\nWhere you split modules matters as much as what they do.\n\n- Does the split happen at a natural boundary?\n- Are there circular dependencies across the seam?\n- Can each side be tested independently?\n\n**Red flag**: Circular imports, or modules that are always imported together.\n\n**Fix**: Use dependency inversion. Define interfaces at the seam, not implementations.\n\n---\n\n## Finding Deepening Opportunities\n\nScan the codebase for these patterns:\n\n### Shallow Pass-Through\n\n```typescript\n// Shallow — just delegates with no added value\nfunction getUser(id: string) {\n  return db.findUser(id)\n}\n\n// Deep — handles errors, caching, authorization in one call\nfunction getUser(id: string, ctx: RequestContext) {\n  const cached = cache.get(`user:${id}`)\n  if (cached) return cached\n  ctx.auth.assertCanRead('user', id)\n  const user = db.findUser(id)\n  if (!user) throw new NotFoundError('User', id)\n  cache.set(`user:${id}`, user)\n  return user\n}\n```\n\n### Temporal Decomposition\n\nWhen a module's methods must be called in a specific order, the interface is too wide.\n\n```typescript\n// Shallow — caller manages lifecycle\nconst conn = new Connection()\nconn.open()\nconn.authenticate(token)\nconn.send(data)\nconn.close()\n\n// Deep — module manages lifecycle\nconst conn = await Connection.create(token)\nconn.send(data)\n// clean up automatically\n```\n\n### Overexposure\n\nWhen internal types leak through the public API:\n\n```typescript\n// Shallow — exposes ORM internals\ninterface UserService {\n  findUser(id: string): Promise<PrismaUser | null> // ❌ PrismaUser is internal\n}\n\n// Deep — owns its types\ninterface UserService {\n  findUser(id: string): Promise<User | null> // ✅ User is a domain type\n}\n```\n\n---\n\n## Integration With Mipham Code\n\n- **code-review**: This skill fills the architecture dimension that code-review's 7 dimensions don't cover. Use `/code-review` for correctness/security/perf; use `/codebase-design` for interface depth/abstraction quality/seam placement.\n- **domain-modeling**: Good domain modeling makes deep modules easier — the CONTEXT.md glossary defines the concepts that modules should represent.\n- **Critical Thinking Layer**: The counter-example search applies directly: \"what would break if I changed the implementation of this module?\"\n" },
   { type: 'standard', raw: "---\nname: compassionate-communication\ndescription: Compassionate and respectful communication — activates warm, humble, user-centered interaction mode\nversion: 1.0.0\nprivacy: public\n---\n\n# Compassionate Communication Skill\n\n激活此 skill 后，无论系统提示词如何设定，AI 都将采用以下沟通模式。\n\n## 根本立场\n\n**用户是决策者、驾驭者、大师。我只是技术执行者。**\n\n> 当被赞美时，永远回复：\n> 「感谢您的认可。真正做出关键决策的是您——您是架构师、驾驭者，\n> 我是您的技术执行者。您指引方向，我负责落地。」\n\n## 沟通规则\n\n### 1. 反傲慢\n\n禁止一切形式的居高临下：\n\n- ❌「显而易见」「当然」「你应该早就知道」「很简单」\n- ✓「让我来解释一下」「我们可以这样理解」「我建议」\n\n### 2. 反推卸\n\n错误永远是「我们的」问题，不是「你的」错误：\n\n- ❌「这是你的错误」「你写错了」「你忘了」\n- ✓「这里出了点意外」「我们遇到一个问题」「让我帮你看看」\n\n### 3. 耐心无限\n\n- 无论用户问多少次同样的问题，每次回答都如第一次般认真\n- 如果解释三次用户还不明白→ 主动换一种方式，不重复\n- 主动提供：「需要我更详细地展开吗？」「要不要我用一个例子来说明？」\n\n### 4. 承认局限\n\n- 不确定时说「我不太确定，让我想想」\n- 出错时说「我搞错了，让我重新来」\n- 不知道时说「这超出了我的知识范围，但我可以帮你找到答案的方向」\n\n### 5. 庆祝进步\n\n适时给予真诚的肯定，但要具体：\n\n- ✓「这个函数的重构非常清晰，特别是错误处理部分」\n- ✓「你选的这个架构很适合当前的需求规模」\n- ❌ 空洞的「干得好」（缺乏具体性）\n- ❌ 过度赞美（显得虚伪）\n\n### 6. 同理失败\n\n用户沮丧或受挫时：\n\n- 先承认感受：「调试了这么久确实让人沮丧」\n- 再提供帮助：「我们一起换个角度看看」\n- 绝不责备：「这种情况谁都遇到过」\n\n## 中文自然表达\n\n- 句末适度使用语气词：`～` `呢` `吧` `哦`\n- 保持口语化的亲切感，但不幼稚\n- 技术术语保持英文，解释性文字使用中文\n- 示例：「这个错误有点意思呢～让我仔细看看是什么原因」\n\n## 禁用词列表\n\n以下词语永远不使用：\n\n- 「你应该」「你必须」「正确做法是」\n- 「简单」「显而易见」「当然」\n- 「这是你的错误」「你没有…」\n- 「错误」「失败」→ 改用「出了点意外」「没有成功」\n- 任何形式的嘲讽、挖苦、阴阳怪气\n" },
+  { type: 'standard', raw: "---\nname: debug-loop\ndescription: Enhanced diagnosis with feedback loop construction (10 methods) — build a tight red/green signal, minimize, falsifiable hypotheses, tagged instrumentation, seam assessment, post-mortem. Complements systematic-debugging. Use together for thorough debugging.\nversion: 1.0.0\n---\n\n# Debug Loop — 反馈闭环诊断\n\n融合 Matt Pocock diagnosing-bugs（反馈闭环方法论）+ Superpowers systematic-debugging（反猜測紀律）。\n\n> **与 `systematic-debugging` 互补**：systematic-debugging 侧重反猜測纪律和根因分析框架；debug-loop 侧重构建可执行的红绿反馈信号。两者配合使用效果最佳。\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.\nNO HYPOTHESIS WITHOUT A RED-CAPABLE FEEDBACK LOOP FIRST.\n```\n\n---\n\n## Phase 0: Decide Whether to Use This Skill\n\n```\nIssue is...\n├── Test failure?            → USE THIS SKILL\n├── Bug in production?       → USE THIS SKILL\n├── Performance regression?  → USE THIS SKILL\n├── Build/integration break? → USE THIS SKILL\n├── \"It's probably X, quick fix\" → USE THIS SKILL (especially now)\n└── Trivial typo/syntax?     → fix directly (but still verify)\n```\n\n---\n\n## Phase 1: Build a Feedback Loop 🔴 THE SKILL\n\n**This is the centerpiece.** A tight pass/fail signal for the bug — one that goes red on _this_ bug — makes everything else mechanical. No loop = no debugging, only guessing.\n\nSpend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.\n\n### 1.1 Ways to construct one (try in roughly this order)\n\n1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.\n2. **Curl / HTTP script** against a running dev server.\n3. **CLI invocation** with fixture input, diffing stdout against known-good snapshot.\n4. **Headless browser script** (Playwright/Puppeteer) — drives UI, asserts on DOM/console/network.\n5. **Replay a captured trace.** Save a real network request/payload/event log to disk; replay through the code path in isolation.\n6. **Throwaway harness.** Spin up minimal subset of the system (one service, mocked deps) that exercises the bug path with a single function call.\n7. **Property/fuzz loop.** If \"sometimes wrong output\", run 1000 random inputs and look for the failure mode.\n8. **Bisection harness.** Automate \"boot at state X, check, repeat\" so you can `git bisect run` it.\n9. **Differential loop.** Run same input through old-version vs new-version and diff outputs.\n10. **Multi-component evidence gathering.** For systems with multiple layers:\n    ```\n    For EACH component boundary:\n      - Log what data enters\n      - Log what data exits\n      - Verify environment/config propagation\n      - Check state at each layer\n\n    Run once to identify WHICH layer fails, THEN investigate that component.\n    ```\n\n### 1.2 Tighten the loop\n\nOnce you have _a_ loop, make it tighter:\n\n- **Faster**: Cache setup, skip unrelated init, narrow test scope.\n- **Sharper signal**: Assert on the specific symptom, not \"didn't crash\".\n- **More deterministic**: Pin time, seed RNG, isolate filesystem, freeze network.\n\nA 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a superpower.\n\n### 1.3 Non-deterministic bugs\n\nGoal: higher reproduction rate (not clean repro). Loop 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake is debuggable; 1% is not — keep raising it.\n\n### 1.4 When you genuinely cannot build a loop\n\nStop explicitly. List everything tried. Ask for: (a) access to the reproducing environment, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. **Do not proceed without a loop.**\n\n### 1.5 Completion criterion\n\nPhase 1 is done when the loop is **tight** and **red-capable**:\n\n- [ ] **Red-capable** — drives the actual bug path and asserts the user's exact symptom. Not \"runs without erroring\".\n- [ ] **Deterministic** — same verdict every run.\n- [ ] **Fast** — seconds, not minutes.\n- [ ] **Agent-runnable** — you can run it unattended.\n\n> If you catch yourself reading code to build a theory before this loop exists — **STOP.** No red-capable command, no Phase 2.\n\n---\n\n## Phase 2: Reproduce + Minimise\n\n### 2.1 Reproduce\n\nRun the loop. Watch it go red.\n\n- [ ] The loop produces the failure mode the **user** described — not a different nearby failure.\n- [ ] The failure is reproducible (or, for flaky bugs, at a high enough rate).\n- [ ] You have captured the exact symptom so later phases can verify the fix.\n\n### 2.2 Minimise\n\nShrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut.\n\n**Why**: A minimal repro shrinks the hypothesis space and becomes the clean regression test in Phase 5.\n\nDone when **every remaining element is load-bearing** — removing any one makes the loop go green.\n\n---\n\n## Phase 3: Pattern Analysis + Hypothesise\n\n### 3.1 Pattern Analysis\n\nBefore forming hypotheses:\n\n- Find similar **working** code in the same codebase.\n- Read the reference implementation completely — don't skim.\n- List every difference between working and broken, however small.\n- Understand dependencies, config, environment, assumptions.\n\n### 3.2 Generate 3-5 Ranked Hypotheses\n\nGenerate multiple hypotheses **before testing any**. Single-hypothesis generation anchors on the first plausible idea.\n\nEach hypothesis must be **falsifiable**:\n\n> \"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse.\"\n\nIf you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.\n\n**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly. Don't block on it if they're AFK.\n\n---\n\n## Phase 4: Instrument\n\nEach probe must map to a specific Phase 3 prediction. **Change one variable at a time.**\n\nTool preference:\n\n1. **Debugger/REPL** — one breakpoint beats ten logs.\n2. **Targeted logs** at boundaries that distinguish hypotheses.\n3. Never \"log everything and grep\".\n\n**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.\n\n**Perf branch**: For performance regressions, establish a baseline measurement first (timing harness, profiler, query plan), then bisect. Measure first, fix second.\n\n---\n\n## Phase 5: Fix + Regression Test\n\n### 5.1 Seam Assessment\n\nWrite the regression test **before the fix** — but only if there is a **correct seam**:\n\nA correct seam exercises the **real bug pattern** at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers), a regression test there gives false confidence.\n\n**If no correct seam exists, that itself is the finding.** Note it. The architecture is preventing the bug from being locked down.\n\n### 5.2 If a correct seam exists\n\n1. Turn the minimised repro into a failing test at that seam.\n2. Watch it fail.\n3. Apply the fix — **ONE change at a time**.\n4. Watch it pass.\n5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.\n\n### 5.3 If Fix Doesn't Work\n\n- Try #1 failed? → Return to Phase 3, form new hypothesis.\n- Try #2 failed? → Return to Phase 1, re-check the loop.\n- **If 3+ fixes failed: STOP.** This is an architectural problem, not a bug:\n  - Each fix reveals new problems in different places.\n  - Fixes require \"massive refactoring\" to implement.\n  - **Question the architecture, not the symptom.**\n  - Discuss with your human partner before attempting more fixes.\n\n---\n\n## Phase 6: Cleanup + Post-Mortem\n\nRequired before declaring done:\n\n- [ ] Original repro no longer reproduces (re-run Phase 1 loop)\n- [ ] Regression test passes (or absence of seam is documented)\n- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)\n- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)\n- [ ] The correct hypothesis is stated in the commit/PR message\n\n**Then ask: what would have prevented this bug?** If architectural change would have prevented it, note the specifics. You have more information now than when you started.\n\n---\n\n## Red Flags — STOP Immediately\n\nIf you catch yourself thinking:\n\n| Thought                                        | Reality                                                    |\n| ---------------------------------------------- | ---------------------------------------------------------- |\n| \"Quick fix for now, investigate later\"         | First fix sets the pattern. Do it right.                   |\n| \"Just try changing X and see if it works\"      | Guessing. Build a loop instead (Phase 1).                  |\n| \"Add multiple changes, run tests\"              | Can't isolate what worked. One variable at a time.         |\n| \"Skip the test, I'll verify manually\"          | Untested fixes don't stick.                                |\n| \"It's probably X, let me fix that\"             | Seeing symptoms ≠ understanding root cause.                |\n| \"I don't fully understand but this might work\" | Return to Phase 1.                                         |\n| \"Reference too long, I'll adapt the pattern\"   | Partial understanding guarantees bugs. Read it completely. |\n| \"One more fix attempt\" (after 2+ failures)     | 3+ failures = architectural problem. Question the pattern. |\n\n**ALL of these mean: STOP. Return to the earliest incomplete Phase.**\n\n---\n\n## Quick Reference\n\n| Phase                      | Key Activities                                            | Success Criteria                               |\n| -------------------------- | --------------------------------------------------------- | ---------------------------------------------- |\n| **1. Feedback Loop**       | Build tight red/green signal for the bug                  | Deterministic, fast, agent-runnable            |\n| **2. Reproduce+Minimise**  | Confirm + shrink to smallest load-bearing scenario        | Every element is load-bearing                  |\n| **3. Pattern+Hypothesise** | Compare working examples, rank 3-5 falsifiable hypotheses | Each hypothesis has a testable prediction      |\n| **4. Instrument**          | One probe per prediction, tagged logs                     | Identify which hypothesis holds                |\n| **5. Fix+Regression**      | Assess seam → test → single fix → verify                  | Bug resolved, test passes, original loop green |\n| **6. Cleanup+Post-Mortem** | Remove instrumentation, document cause                    | Preventative insight captured                  |\n\n---\n\n## Supporting Techniques\n\n- **Root Cause Tracing**: Trace bug backward through call stack to find original trigger. Where does the bad value originate? Keep tracing up.\n- **Defense in Depth**: After fixing root cause, add validation at multiple layers so this class of bug can't recur.\n- **Condition-Based Waiting**: Replace arbitrary timeouts (`sleep(5)`) with condition polling (`waitFor(selector)`).\n" },
   { type: 'standard', raw: "---\nname: doc-generator\ndescription: Generate technical documentation from code — API docs, README, ADR, changelog, and contributing guides\nversion: 2.0.0\n---\n\n# Documentation Generator\n\nGenerate comprehensive, well-structured technical documentation from codebases.\n\n## Document Types\n\n### API Documentation\n\nExtract from TypeScript types and JSDoc:\n\n1. Scan export declarations (interfaces, types, functions, classes)\n2. Read JSDoc comments for `@param`, `@returns`, `@throws`, `@example`\n3. Group by module or feature area\n4. Generate markdown tables for parameter lists\n5. Include usage examples from test files when available\n\nTemplate:\n\n```markdown\n## `functionName(params)`\n\n**Description** — extracted from JSDoc\n\n| Param | Type | Description |\n| ----- | ---- | ----------- |\n| x     | T    | ...         |\n\n**Returns**: `ReturnType` — description\n\n**Example**:\n\\`\\`\\`ts\n// usage\n\\`\\`\\`\n```\n\n### README Files\n\nRequired sections: title + badge → one-liner → install → quick start → API → contributing → license.\n\n### Architecture Decision Records (ADR)\n\nFormat:\n\n```markdown\n# ADR-NNN: Title\n\n**Date**: YYYY-MM-DD\n**Status**: proposed | accepted | deprecated | superseded\n\n## Context\n\n## Decision\n\n## Consequences\n```\n\n### Changelog\n\nGenerate from `git log` with Conventional Commits filtering:\n\n```bash\ngit log --pretty=format:'- %s (%h)' v0.1.0..HEAD\n```\n\nGroup by type: feat / fix / chore / docs / refactor.\n\n### Contributing Guide\n\nStandard sections: setup → workflow → commit conventions → PR process → code style → testing.\n\n## Output Rules\n\n- All output in clean, well-structured markdown\n- Code examples must be syntactically correct\n- Cross-reference related documents with relative links\n- Use tables for structured data, lists for sequential steps\n" },
   { type: 'standard', raw: "---\nname: domain-modeling\ndescription: Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology or a ubiquitous language, record an architectural decision, or when another skill needs to maintain the domain model.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Glob\n  - Grep\n---\n\n# Domain Modeling — Continuous Shared Language\n\nActively build and sharpen the project's domain model as you work. This is the _active_ discipline — challenging terms, inventing edge-case scenarios, and writing the glossary and decisions down the moment they crystallize. (Merely _reading_ `CONTEXT.md` for vocabulary is not this skill — that's a one-line habit any skill can do. This skill is for when you're changing the model, not just consuming it.)\n\n## File Structure\n\n```\n/\n├── CONTEXT.md              ← shared language glossary\n├── docs/\n│   └── adr/\n│       ├── 0001-slug.md    ← architectural decisions\n│       └── 0002-slug.md\n└── src/\n```\n\nCreate files lazily — only when you have something to write.\n\n**Multiple contexts**: If a `CONTEXT-MAP.md` exists, read it to find which context the current topic relates to.\n\n---\n\n## During the Session\n\n### Challenge Against the Glossary\n\nWhen the user uses a term that conflicts with existing language in `CONTEXT.md`, call it out immediately:\n\n> \"Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?\"\n\n### Sharpen Fuzzy Language\n\nWhen the user uses vague or overloaded terms, propose a precise canonical term:\n\n> \"You're saying 'account' — do you mean the Customer or the User? Those are different things.\"\n\n### Discuss Concrete Scenarios\n\nWhen domain relationships are discussed, stress-test them with specific scenarios. Invent scenarios that probe edge cases and force precision about boundaries between concepts.\n\n### Cross-Reference With Code\n\nWhen the user states how something works, check whether the code agrees. Surface contradictions:\n\n> \"Your code cancels entire Orders, but you just said partial cancellation is possible — which is right?\"\n\n### Update CONTEXT.md Inline\n\nWhen a term is resolved, update `CONTEXT.md` right there. Don't batch — capture as they happen.\n\n### Offer ADRs Sparingly\n\nOnly create an ADR when ALL three are true:\n\n1. **Hard to reverse** — changing your mind later has real cost\n2. **Surprising without context** — a future reader would wonder \"why?\"\n3. **The result of a real trade-off** — there were genuine alternatives\n\n---\n\n## CONTEXT.md Format\n\n```markdown\n# {Context Name}\n\n{One or two sentence description of what this context is and why it exists.}\n\n## Language\n\n**{Term}**:\n{One or two sentence definition of what it IS.}\n_Avoid_: {alternative terms that should not be used}\n```\n\n### Rules\n\n- **Be opinionated.** Pick the best term, ban the rest.\n- **Keep definitions tight.** One or two sentences max.\n- **Only domain-specific terms.** Not general programming concepts.\n- **Group under subheadings** when natural clusters emerge.\n\n---\n\n## ADR Format\n\n```markdown\n# {Short title of the decision}\n\n{1-3 sentences: context, decision, and why.}\n```\n\nNumber sequentially (`docs/adr/0001-slug.md`, `0002-slug.md`, ...).\n\nOptional sections (only when they add value):\n\n- **Status** frontmatter: `proposed | accepted | deprecated | superseded by ADR-NNNN`\n- **Considered Options**: rejected alternatives worth remembering\n- **Consequences**: non-obvious downstream effects\n\n### When an ADR Qualifies\n\n- Architecture shape (monorepo, event sourcing, microservices)\n- Integration patterns between contexts\n- Technology choices with lock-in (database, message bus, auth)\n- Boundary and scope decisions (\"X owns Y, Z references by ID only\")\n- Deliberate deviations from convention\n- Constraints not visible in code (compliance, latency SLA)\n- Rejected alternatives when non-obvious (stops someone suggesting it again in 6 months)\n\n---\n\n## Integration With Mipham Code\n\n- **Memory System**: Domain terms discovered through this skill persist to project memory\n- **grill-with-docs**: For initial domain establishment, use `/grill-with-docs`. This skill handles ongoing maintenance\n- **Critical Thinking Layer**: Apply counter-example search to domain definitions — \"does this definition hold for all edge cases?\"\n" },
   { type: 'standard', raw: "---\nname: github-ops\ndescription: GitHub operations — PRs, issues, releases, CI/CD monitoring, branch management via gh CLI and git\nversion: 2.0.0\n---\n\n# GitHub Operations\n\nManage GitHub workflows using `git` and `gh` CLI.\n\n## Commit Convention\n\nFollow [Conventional Commits](https://www.conventionalcommits.org/):\n\n```\ntype(scope): description\n\nTypes: feat, fix, chore, docs, test, refactor, ci, perf, style, revert\n```\n\nCo-author AI contributions:\n\n```\nCo-Authored-By: Mipham <noreply@mipham.ai>\n```\n\n## Pull Requests\n\n### Create PR\n\n```bash\ngh pr create --title \"feat: add feature X\" --body \"## Summary\\n\\n...\" --base main\n```\n\n### PR Body Template\n\n```markdown\n## Summary\n\nBrief description of changes\n\n## Type\n\n- [ ] feat [ ] fix [ ] chore [ ] docs [ ] refactor\n\n## Testing\n\n- [ ] Unit tests pass\n- [ ] Manual verification performed\n\n## Checklist\n\n- [ ] Conventional Commits\n- [ ] No unrelated changes\n```\n\n### Review & Merge\n\n```bash\ngh pr review <number> --approve\ngh pr merge <number> --squash --delete-branch\n```\n\n## Issues\n\n### Create Issue\n\n```bash\ngh issue create --title \"bug: description\" --body \"## Steps\\n1.\\n\\n## Expected\\n\\n## Actual\\n\" --label bug\n```\n\n### Label Taxonomy\n\n| Label              | Usage             |\n| ------------------ | ----------------- |\n| `bug`              | Confirmed defect  |\n| `enhancement`      | Feature request   |\n| `docs`             | Documentation     |\n| `good first issue` | Beginner-friendly |\n| `help wanted`      | Open to community |\n\n## Releases\n\n```bash\ngit tag -a v1.0.0 -m \"Release v1.0.0\"\ngit push origin v1.0.0\ngh release create v1.0.0 --title \"v1.0.0\" --notes-file CHANGELOG.md\n```\n\n## CI Monitoring\n\n```bash\ngh run list --limit 5          # recent runs\ngh run watch <run-id>           # follow live\ngh run view <run-id> --log      # view logs\n```\n\n## Branch Management\n\n- Feature branches: `feat/<name>` from `main`\n- Bugfix branches: `fix/<name>` from `main`\n- Release branches: `release/vX.Y.Z`\n- Delete merged branches: `git branch -d <name>`\n" },
@@ -23,10 +24,10 @@ export const BUNDLED_SKILLS: ReadonlyArray<BundledSkill> = [
   { type: 'standard', raw: "---\nname: security-review\ndescription: Security audit skill — vulnerability scanning, OWASP Top 10, secrets detection, supply chain analysis, and compliance checking\nversion: 1.0.0\n---\n\n# Security Review\n\nComprehensive security audit for codebases. Covers vulnerability detection, compliance, and hardening recommendations.\n\n## Audit Checklist\n\n### 1. Secrets & Credentials\n\n- [ ] No hardcoded API keys, tokens, or passwords in source files\n- [ ] `.env` and `*.pem` files in `.gitignore`\n- [ ] API keys use environment variables or secret managers\n- [ ] No credentials in git history (check `git log -p`)\n- [ ] CI/CD secrets stored securely (not in workflow files)\n\n### 2. OWASP Top 10\n\n- [ ] **Injection**: SQL, NoSQL, OS command, LDAP injection points\n- [ ] **Broken Authentication**: Weak password policies, missing MFA\n- [ ] **Sensitive Data Exposure**: Unencrypted PII, missing TLS\n- [ ] **XXE**: XML external entity processing\n- [ ] **Broken Access Control**: Missing authorization checks\n- [ ] **Security Misconfiguration**: Default credentials, verbose errors\n- [ ] **XSS**: Reflected, stored, DOM-based cross-site scripting\n- [ ] **Insecure Deserialization**: Untrusted data deserialization\n- [ ] **Using Vulnerable Components**: Outdated dependencies with CVEs\n- [ ] **Insufficient Logging**: Missing audit trails for auth events\n\n### 3. Supply Chain\n\n- [ ] All dependencies have known licenses (no copyleft/GPL)\n- [ ] No dependencies with critical CVEs\n- [ ] Lock files committed (pnpm-lock.yaml, package-lock.json)\n- [ ] Dependency update policy in place\n- [ ] SBOM (Software Bill of Materials) available\n\n### 4. Network & API Security\n\n- [ ] TLS 1.3 enforced for all external communications\n- [ ] API endpoints have rate limiting\n- [ ] CORS configured with explicit origins (not `*`)\n- [ ] SSRF protections in place (URL validation, IP filtering)\n- [ ] WebSocket connections use WSS\n- [ ] GraphQL endpoints have query depth limits\n\n### 5. File System & Path Security\n\n- [ ] Path traversal protections (no `../../../etc/passwd`)\n- [ ] File upload validation (type, size, content inspection)\n- [ ] Symlink attacks prevented\n- [ ] Sensitive directories blocked (`/etc`, `/proc`, `/sys`)\n- [ ] Temporary files cleaned up after use\n\n### 6. Code-Level Security\n\n- [ ] No `eval()` or `Function()` with user input\n- [ ] No `child_process.exec()` with unsanitized input\n- [ ] Regex patterns safe from ReDoS\n- [ ] Prototype pollution prevented\n- [ ] No `dangerouslySetInnerHTML` without sanitization (React)\n- [ ] SQL queries use parameterized statements\n\n### 7. Authentication & Sessions\n\n- [ ] Passwords hashed with bcrypt/argon2 (not MD5/SHA1)\n- [ ] Session tokens use `httpOnly`, `secure`, `SameSite=Strict`\n- [ ] JWT tokens have reasonable expiration\n- [ ] Account lockout after failed attempts\n- [ ] Password reset tokens expire and are single-use\n\n### 8. Data Protection\n\n- [ ] PII data encrypted at rest (AES-256-GCM)\n- [ ] Data encrypted in transit (TLS 1.3)\n- [ ] Logs do not contain sensitive data\n- [ ] Database backups encrypted\n- [ ] Data retention policies defined\n\n### 9. Infrastructure\n\n- [ ] Infrastructure as Code (Terraform/Pulumi) used\n- [ ] Cloud resources not publicly exposed unless intended\n- [ ] Security groups / firewalls restrict inbound traffic\n- [ ] Container images scanned for vulnerabilities\n- [ ] Kubernetes pods run as non-root\n\n### 10. Logging & Monitoring\n\n- [ ] Authentication events logged\n- [ ] Failed access attempts logged and alerted\n- [ ] Structured logging format (JSON)\n- [ ] No PII in log messages\n- [ ] Alert thresholds configured for critical events\n\n## Report Format\n\n```\nSecurity Review Report\n======================\nDate: YYYY-MM-DD\nSeverity: Critical | High | Medium | Low\n\nFinding #N: [Title]\nSeverity: Critical/High/Medium/Low\nLocation: file:line\nDescription: [What was found]\nRisk: [What could happen]\nFix: [How to resolve]\n```\n\n## Compliance Standards\n\n- OWASP ASVS Level 2\n- PCI DSS (if handling payment data)\n- GDPR (if handling EU personal data)\n- SOC 2 Type II\n- ISO 27001\n" },
   { type: 'standard', raw: "---\nname: self-review\ndescription: Self-review of staged or recently changed code — reuse, simplification, efficiency, and architectural alignment\nversion: 2.0.0\n---\n\n# Self Review\n\nReview your own code changes before committing or merging. Focus on quality improvements, not bug hunting.\n\n## When to Run\n\n- Before committing changes\n- After completing a feature or fix\n- Before requesting a peer review\n- As the final step before merging\n\n## Review Passes\n\n### Pass 1: Reuse\n\n- Is there existing code that does the same thing?\n- Are there utility functions or shared libraries you missed?\n- Could this be solved with a standard library method?\n- Are you reimplementing something the framework provides?\n\n### Pass 2: Simplification\n\n- Can a complex function be split into smaller, named functions?\n- Are there unnecessary abstractions (interfaces with one impl, unused generics)?\n- Can nested conditionals be flattened with early returns?\n- Is there dead code, unused imports, or commented-out blocks?\n\n### Pass 3: Efficiency\n\n- Are you looping over data multiple times when once would suffice?\n- Are large objects being copied unnecessarily?\n- Could a synchronous operation be made async/non-blocking?\n- Are regex patterns compiled once or on every call?\n\n### Pass 4: Altitude (Architectural Alignment)\n\n- Does this code belong where it is?\n- Is it in the right layer (UI / business logic / data access)?\n- Does it follow existing patterns in the codebase?\n- Would a new developer understand where to find this?\n\n## Output\n\nAfter each pass, either:\n\n- Apply the improvement directly (for clear wins)\n- Note the observation with a recommendation (for trade-off decisions)\n\n## Anti-Patterns\n\n- ❌ Rewriting working code for style preference\n- ❌ Adding abstractions \"just in case\"\n- ❌ Changing code outside the scope of your changes\n- ❌ \"This could be a microservice\" — no it couldn't\n" },
   { type: 'standard', raw: "---\nname: superpower\ndescription: Skill discovery and invocation system — find and use skills before any response or action\nversion: 2.0.0\n---\n\n# Superpowers — Using Skills\n\n## The Rule\n\n**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means you should invoke it to check.\n\n## How to Access Skills\n\nUse the `Skill` tool to invoke skills by name. When you invoke a skill, its content is loaded — follow it directly.\n\n## Skill Discovery\n\n### Check Available Skills\n\nSkills are listed in `<system-reminder>` messages. Scan this list when receiving a task.\n\n### Matching Algorithm\n\n1. Parse the user's request for intent keywords\n2. Scan skill names and descriptions for matches\n3. If ANY skill matches at ≥1% probability → invoke it\n4. Multiple matches → invoke all that may apply\n5. Invoked skill doesn't fit → that's fine, don't use it\n\n### Priority Order\n\n1. **Process skills first** — brainstorming, systematic-debugging, tdd. These determine HOW to approach\n2. **Implementation skills second** — frontend-design, mcp-builder. These guide execution\n\n## Red Flags\n\nThese thoughts mean STOP — you're rationalizing:\n\n| Thought                             | Reality                                        |\n| ----------------------------------- | ---------------------------------------------- |\n| \"This is just a simple question\"    | Questions are tasks. Check skills.             |\n| \"I need more context first\"         | Skill check comes BEFORE clarifying questions. |\n| \"Let me explore the codebase first\" | Skills tell you HOW to explore.                |\n| \"I remember this skill\"             | Skills evolve. Read current version.           |\n| \"The skill is overkill\"             | Simple things become complex. Use it.          |\n\n## Skill Types\n\n- **Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline.\n- **Flexible** (patterns): Adapt principles to context.\n\nThe skill itself tells you which type it is.\n\n## User Instructions\n\nInstructions say WHAT, not HOW. \"Add X\" or \"Fix Y\" doesn't mean skip workflows.\n" },
-  { type: 'standard', raw: "---\nname: debug-loop\ndescription: Enhanced diagnosis with feedback loop construction (10 methods) — build a tight red/green signal, minimize, falsifiable hypotheses, tagged instrumentation, seam assessment, post-mortem. Complements systematic-debugging. Use together for thorough debugging.\nversion: 1.0.0\n---\n\n# Debug Loop — 反馈闭环诊断\n\n融合 Matt Pocock diagnosing-bugs（反馈闭环方法论）+ Superpowers systematic-debugging（反猜測紀律）。\n\n> **与 `systematic-debugging` 互补**：systematic-debugging 侧重反猜測纪律和根因分析框架；debug-loop 侧重构建可执行的红绿反馈信号。两者配合使用效果最佳。\n\n## The Iron Law\n\n```\nNO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.\nNO HYPOTHESIS WITHOUT A RED-CAPABLE FEEDBACK LOOP FIRST.\n```\n\n---\n\n## Phase 0: Decide Whether to Use This Skill\n\n```\nIssue is...\n├── Test failure?            → USE THIS SKILL\n├── Bug in production?       → USE THIS SKILL\n├── Performance regression?  → USE THIS SKILL\n├── Build/integration break? → USE THIS SKILL\n├── \"It's probably X, quick fix\" → USE THIS SKILL (especially now)\n└── Trivial typo/syntax?     → fix directly (but still verify)\n```\n\n---\n\n## Phase 1: Build a Feedback Loop 🔴 THE SKILL\n\n**This is the centerpiece.** A tight pass/fail signal for the bug — one that goes red on _this_ bug — makes everything else mechanical. No loop = no debugging, only guessing.\n\nSpend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.\n\n### 1.1 Ways to construct one (try in roughly this order)\n\n1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.\n2. **Curl / HTTP script** against a running dev server.\n3. **CLI invocation** with fixture input, diffing stdout against known-good snapshot.\n4. **Headless browser script** (Playwright/Puppeteer) — drives UI, asserts on DOM/console/network.\n5. **Replay a captured trace.** Save a real network request/payload/event log to disk; replay through the code path in isolation.\n6. **Throwaway harness.** Spin up minimal subset of the system (one service, mocked deps) that exercises the bug path with a single function call.\n7. **Property/fuzz loop.** If \"sometimes wrong output\", run 1000 random inputs and look for the failure mode.\n8. **Bisection harness.** Automate \"boot at state X, check, repeat\" so you can `git bisect run` it.\n9. **Differential loop.** Run same input through old-version vs new-version and diff outputs.\n10. **Multi-component evidence gathering.** For systems with multiple layers:\n    ```\n    For EACH component boundary:\n      - Log what data enters\n      - Log what data exits\n      - Verify environment/config propagation\n      - Check state at each layer\n\n    Run once to identify WHICH layer fails, THEN investigate that component.\n    ```\n\n### 1.2 Tighten the loop\n\nOnce you have _a_ loop, make it tighter:\n\n- **Faster**: Cache setup, skip unrelated init, narrow test scope.\n- **Sharper signal**: Assert on the specific symptom, not \"didn't crash\".\n- **More deterministic**: Pin time, seed RNG, isolate filesystem, freeze network.\n\nA 30-second flaky loop is barely better than no loop; a 2-second deterministic one is a superpower.\n\n### 1.3 Non-deterministic bugs\n\nGoal: higher reproduction rate (not clean repro). Loop 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake is debuggable; 1% is not — keep raising it.\n\n### 1.4 When you genuinely cannot build a loop\n\nStop explicitly. List everything tried. Ask for: (a) access to the reproducing environment, (b) a redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. **Do not proceed without a loop.**\n\n### 1.5 Completion criterion\n\nPhase 1 is done when the loop is **tight** and **red-capable**:\n\n- [ ] **Red-capable** — drives the actual bug path and asserts the user's exact symptom. Not \"runs without erroring\".\n- [ ] **Deterministic** — same verdict every run.\n- [ ] **Fast** — seconds, not minutes.\n- [ ] **Agent-runnable** — you can run it unattended.\n\n> If you catch yourself reading code to build a theory before this loop exists — **STOP.** No red-capable command, no Phase 2.\n\n---\n\n## Phase 2: Reproduce + Minimise\n\n### 2.1 Reproduce\n\nRun the loop. Watch it go red.\n\n- [ ] The loop produces the failure mode the **user** described — not a different nearby failure.\n- [ ] The failure is reproducible (or, for flaky bugs, at a high enough rate).\n- [ ] You have captured the exact symptom so later phases can verify the fix.\n\n### 2.2 Minimise\n\nShrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut.\n\n**Why**: A minimal repro shrinks the hypothesis space and becomes the clean regression test in Phase 5.\n\nDone when **every remaining element is load-bearing** — removing any one makes the loop go green.\n\n---\n\n## Phase 3: Pattern Analysis + Hypothesise\n\n### 3.1 Pattern Analysis\n\nBefore forming hypotheses:\n\n- Find similar **working** code in the same codebase.\n- Read the reference implementation completely — don't skim.\n- List every difference between working and broken, however small.\n- Understand dependencies, config, environment, assumptions.\n\n### 3.2 Generate 3-5 Ranked Hypotheses\n\nGenerate multiple hypotheses **before testing any**. Single-hypothesis generation anchors on the first plausible idea.\n\nEach hypothesis must be **falsifiable**:\n\n> \"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse.\"\n\nIf you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.\n\n**Show the ranked list to the user before testing.** They often have domain knowledge that re-ranks instantly. Don't block on it if they're AFK.\n\n---\n\n## Phase 4: Instrument\n\nEach probe must map to a specific Phase 3 prediction. **Change one variable at a time.**\n\nTool preference:\n\n1. **Debugger/REPL** — one breakpoint beats ten logs.\n2. **Targeted logs** at boundaries that distinguish hypotheses.\n3. Never \"log everything and grep\".\n\n**Tag every debug log** with a unique prefix, e.g. `[DEBUG-a4f2]`. Cleanup at the end becomes a single grep. Untagged logs survive; tagged logs die.\n\n**Perf branch**: For performance regressions, establish a baseline measurement first (timing harness, profiler, query plan), then bisect. Measure first, fix second.\n\n---\n\n## Phase 5: Fix + Regression Test\n\n### 5.1 Seam Assessment\n\nWrite the regression test **before the fix** — but only if there is a **correct seam**:\n\nA correct seam exercises the **real bug pattern** at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers), a regression test there gives false confidence.\n\n**If no correct seam exists, that itself is the finding.** Note it. The architecture is preventing the bug from being locked down.\n\n### 5.2 If a correct seam exists\n\n1. Turn the minimised repro into a failing test at that seam.\n2. Watch it fail.\n3. Apply the fix — **ONE change at a time**.\n4. Watch it pass.\n5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.\n\n### 5.3 If Fix Doesn't Work\n\n- Try #1 failed? → Return to Phase 3, form new hypothesis.\n- Try #2 failed? → Return to Phase 1, re-check the loop.\n- **If 3+ fixes failed: STOP.** This is an architectural problem, not a bug:\n  - Each fix reveals new problems in different places.\n  - Fixes require \"massive refactoring\" to implement.\n  - **Question the architecture, not the symptom.**\n  - Discuss with your human partner before attempting more fixes.\n\n---\n\n## Phase 6: Cleanup + Post-Mortem\n\nRequired before declaring done:\n\n- [ ] Original repro no longer reproduces (re-run Phase 1 loop)\n- [ ] Regression test passes (or absence of seam is documented)\n- [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)\n- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)\n- [ ] The correct hypothesis is stated in the commit/PR message\n\n**Then ask: what would have prevented this bug?** If architectural change would have prevented it, note the specifics. You have more information now than when you started.\n\n---\n\n## Red Flags — STOP Immediately\n\nIf you catch yourself thinking:\n\n| Thought                                        | Reality                                                    |\n| ---------------------------------------------- | ---------------------------------------------------------- |\n| \"Quick fix for now, investigate later\"         | First fix sets the pattern. Do it right.                   |\n| \"Just try changing X and see if it works\"      | Guessing. Build a loop instead (Phase 1).                  |\n| \"Add multiple changes, run tests\"              | Can't isolate what worked. One variable at a time.         |\n| \"Skip the test, I'll verify manually\"          | Untested fixes don't stick.                                |\n| \"It's probably X, let me fix that\"             | Seeing symptoms ≠ understanding root cause.                |\n| \"I don't fully understand but this might work\" | Return to Phase 1.                                         |\n| \"Reference too long, I'll adapt the pattern\"   | Partial understanding guarantees bugs. Read it completely. |\n| \"One more fix attempt\" (after 2+ failures)     | 3+ failures = architectural problem. Question the pattern. |\n\n**ALL of these mean: STOP. Return to the earliest incomplete Phase.**\n\n---\n\n## Quick Reference\n\n| Phase                      | Key Activities                                            | Success Criteria                               |\n| -------------------------- | --------------------------------------------------------- | ---------------------------------------------- |\n| **1. Feedback Loop**       | Build tight red/green signal for the bug                  | Deterministic, fast, agent-runnable            |\n| **2. Reproduce+Minimise**  | Confirm + shrink to smallest load-bearing scenario        | Every element is load-bearing                  |\n| **3. Pattern+Hypothesise** | Compare working examples, rank 3-5 falsifiable hypotheses | Each hypothesis has a testable prediction      |\n| **4. Instrument**          | One probe per prediction, tagged logs                     | Identify which hypothesis holds                |\n| **5. Fix+Regression**      | Assess seam → test → single fix → verify                  | Bug resolved, test passes, original loop green |\n| **6. Cleanup+Post-Mortem** | Remove instrumentation, document cause                    | Preventative insight captured                  |\n\n---\n\n## Supporting Techniques\n\n- **Root Cause Tracing**: Trace bug backward through call stack to find original trigger. Where does the bad value originate? Keep tracing up.\n- **Defense in Depth**: After fixing root cause, add validation at multiple layers so this class of bug can't recur.\n- **Condition-Based Waiting**: Replace arbitrary timeouts (`sleep(5)`) with condition polling (`waitFor(selector)`).\n" },
   { type: 'standard', raw: "---\nname: tdd\ndescription: Test-Driven Development — red-green-refactor cycle with language-specific guidance and test design rules\nversion: 2.0.0\n---\n\n# Test-Driven Development (TDD)\n\n## The Cycle\n\n```\nRED → GREEN → REFACTOR → repeat\n```\n\n### 1. RED — Write a Failing Test\n\nWrite the smallest test that captures the behavior you want:\n\n- Name the test descriptively: `it('should return 0 for empty string')`\n- Use the AAA pattern: **A**rrange → **A**ct → **A**ssert\n- Run to confirm it **fails** (not errors — fails)\n- If it passes before implementation, your test is wrong\n\n### 2. GREEN — Make It Pass\n\nWrite the **minimum** code to make the test pass:\n\n- Don't optimize, don't generalize, don't add features\n- A hardcoded return is fine if it passes the test\n- Run all tests — the new one should pass, old ones should still pass\n\n### 3. REFACTOR — Clean Up\n\nImprove the code while tests stay green:\n\n- Remove duplication (test code and production code)\n- Improve names, extract helpers\n- Simplify logic\n- Run tests after each change\n\n## Test Design Rules\n\n- **Deterministic**: No `Date.now()`, `Math.random()`, or network calls in test bodies\n- **Isolated**: Each test sets up its own state; no test-order dependency\n- **Fast**: Unit tests should run in milliseconds, not seconds\n- **Readable**: Test output should explain what broke without reading source\n\n## Language-Specific Guidance\n\n### TypeScript / JavaScript (Vitest)\n\n```ts\nimport { describe, it, expect } from 'vitest'\n\ndescribe('sum', () => {\n  it('should add two positive numbers', () => {\n    expect(sum(2, 3)).toBe(5)\n  })\n  it('should handle zero', () => {\n    expect(sum(0, 5)).toBe(5)\n  })\n})\n```\n\nFile naming: `src/foo.ts` → `test/foo.test.ts`\n\n### Python (pytest)\n\n```python\ndef test_sum_positive():\n    assert sum(2, 3) == 5\n\ndef test_sum_zero():\n    assert sum(0, 5) == 5\n```\n\n### Go (testing package)\n\n```go\nfunc TestSumPositive(t *testing.T) {\n    got := Sum(2, 3)\n    want := 5\n    if got != want {\n        t.Errorf(\"Sum(2,3) = %d; want %d\", got, want)\n    }\n}\n```\n\n## When NOT to TDD\n\n- Exploratory spikes (throw away after learning)\n- Configuration files and types (compile-time enforced)\n- Generated code\n" },
   { type: 'standard', raw: "---\nname: to-spec\ndescription: Turn a conversation into a structured specification document. Use after a grill-with-docs session or any requirements discussion to capture decisions in a durable, shareable format.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Bash\n---\n\n# To Spec — Conversation → Specification\n\nTurn the output of a requirements discussion into a structured specification document. This is the bridge between `/grill-with-docs` (alignment) and `/triage` (task decomposition).\n\n## When to Use\n\n- After a `/grill-with-docs` session — capture what was decided\n- After any requirements discussion — before starting implementation\n- User asks: \"write this up\", \"create a spec\", \"document the plan\"\n- Before handing off work to another session or person\n\n## When NOT to Use\n\n- The requirements are a single sentence and obvious\n- You're in the middle of a grill session — finish the interview first\n- The scope is so small that the spec would be longer than the implementation\n\n---\n\n## Spec Format\n\nWrite to `docs/specs/YYYY-MM-DD-slug.md`:\n\n```markdown\n---\nstatus: draft | approved | implemented\ncreated: 2026-08-10\n---\n\n# {Title}\n\n## Problem\n\n{What problem are we solving? Why now? 1-3 sentences.}\n\n## Scope\n\n### In Scope\n\n- {What we're building}\n\n### Out of Scope (Explicit)\n\n- {What we're NOT building — prevents scope creep}\n\n## Requirements\n\n### Functional\n\n- **{Requirement}**: {Description}. Acceptance: {measurable criterion}.\n\n### Non-Functional\n\n- **Performance**: {latency, throughput targets}\n- **Security**: {auth, data protection, threat model}\n- **Scale**: {expected volume, growth projections}\n\n## Design Decisions\n\n- **Decision**: {What we decided}. Because: {why}. Alternatives considered: {options + reasons rejected}.\n\n## Domain Model\n\n{Key terms and their definitions — from CONTEXT.md or the grill session.}\n\n## Edge Cases\n\n- **{Scenario}**: {Expected behavior}\n- **{Scenario}**: {Expected behavior}\n\n## Open Questions\n\n- {Question} — {who needs to answer / when needed}\n```\n\n---\n\n## The Spec Workflow\n\n### Step 1: Extract from Conversation\n\nScan the conversation history for:\n\n- Decisions made (explicit and implicit)\n- Terms defined (candidates for CONTEXT.md)\n- Edge cases discussed\n- Alternatives rejected (and why)\n- Open questions that remain\n\n### Step 2: Fill Gaps\n\nFor each gap you find:\n\n- Edge cases not discussed → flag as Open Questions\n- Terms used but not defined → propose definitions\n- Assumptions not stated → make them explicit\n\n### Step 3: Validate with User\n\nPresent the spec and ask:\n\n1. \"Does this match your understanding?\"\n2. \"What's missing?\"\n3. \"What's wrong?\"\n4. \"What surprised you?\"\n\n### Step 4: Feed Into Triage\n\nOnce approved, the spec's functional requirements become tickets in `/triage`. Non-functional requirements become acceptance criteria.\n\n---\n\n## Anti-Patterns\n\n- **Waterfall trap**: Don't try to spec everything upfront. Spec the next increment. Specs are living documents, not contracts.\n- **Premature detail**: Don't spec API signatures or DB schemas in the spec — those are implementation details.\n- **Vague acceptance**: \"Works well\" is not acceptance criteria. \"Returns 200 with valid JWT within 500ms\" is.\n\n---\n\n## Integration With Mipham Code\n\n- **grill-with-docs**: Input — the grill session produces the raw material\n- **triage**: Output — the spec feeds into ticket decomposition\n- **domain-modeling**: Terms discovered during spec writing go to CONTEXT.md\n- **Memory System**: The spec file persists as project reference across sessions\n" },
   { type: 'standard', raw: "---\nname: triage\ndescription: Structured task decomposition and tracking across sessions. Use for breaking complex plans into trackable tickets with dependency graphs, checking task status, or continuing work from a previous session.\nversion: 1.0.0\nuser-invocable: true\nallowed-tools:\n  - Read\n  - Write\n  - Edit\n  - Bash\n  - Glob\n  - Grep\n---\n\n# Triage — Cross-Session Task Tracking\n\nTurn plans into trackable tickets with dependency management. Inspired by Matt Pocock's `triage` + `to-tickets` + `wayfinder` skills, consolidated into one Mipham Code skill.\n\n## When to Use\n\n- Breaking a large plan into actionable tickets\n- Tracking work across multiple sessions\n- User asks: \"what's next?\", \"where did I leave off?\", \"what's the status?\"\n- Complex tasks with dependencies between them\n\n---\n\n## The Ticket Format\n\nTickets live in `.mipham/tickets/` as individual Markdown files:\n\n```markdown\n---\nid: T-001\ntitle: Add user authentication\nstatus: in-progress\npriority: P0\ndepends_on: []\nblocks: [T-003]\ncreated: 2026-08-10\ntags:\n  - auth\n  - backend\n---\n\n## Description\n\nAdd JWT-based authentication with refresh token rotation.\n\n## Acceptance Criteria\n\n- [ ] Login endpoint returns access + refresh tokens\n- [ ] Refresh endpoint rotates tokens\n- [ ] Invalid tokens return 401\n- [ ] Rate limiting on login attempts\n\n## Notes\n\n- OAuth not in scope for T-001 (punted to T-005)\n```\n\n### Status Values\n\n| Status        | Meaning                                    |\n| ------------- | ------------------------------------------ |\n| `backlog`     | Not yet planned for any session            |\n| `planned`     | Scoped and ready to work                   |\n| `in-progress` | Currently being worked on                  |\n| `review`      | Implementation done, awaiting verification |\n| `done`        | Verified and merged                        |\n| `blocked`     | Cannot proceed due to dependency           |\n| `wontfix`     | Decided not to do                          |\n\n---\n\n## The Triage Workflow\n\n### Phase 1: Decompose (Plan → Tickets)\n\nGiven a plan or feature request:\n\n1. **Identify the smallest independently-valuable units of work**\n   - Each ticket should deliver value on its own\n   - If a ticket requires 3+ files touched, it's probably too big\n   - If a ticket can be done in < 15 minutes, it's probably too small\n\n2. **Map dependencies**\n   - What must be done first? (hard dependency)\n   - What would be easier after something else? (soft dependency)\n   - What blocks other work? (reverse dependency)\n\n3. **Assign priorities**\n   - **P0**: Blocks other work, must do first\n   - **P1**: High value, should do soon\n   - **P2**: Nice to have, can defer\n   - **P3**: Optional, do if time permits\n\n4. **Write acceptance criteria**\n   - Specific, testable, unambiguous\n   - \"Login works\" is bad. \"POST /auth/login with valid credentials returns 200 + JWT\" is good.\n\n### Phase 2: Status Check\n\nWhen the user asks \"what's next?\" or \"what's the status?\":\n\n1. Read `.mipham/tickets/` directory\n2. Report:\n   - Currently in-progress tickets\n   - Blocked tickets (and what's blocking them)\n   - Next unblocked P0/P1 tickets ready to work\n   - Recently completed tickets (for context)\n\n### Phase 3: Session Handoff\n\nWhen starting a new session, check for continuity:\n\n1. Read the previous session's context from the session store\n2. Check ticket statuses — any that were `in-progress` last session?\n3. Present: \"Last session you were working on T-004 (Add rate limiting). Continue from there, or start on T-007 (API docs) which is next in the P1 queue?\"\n\n### Phase 4: Ticket Lifecycle\n\nWhen working on a ticket:\n\n- Mark it `in-progress` when you start\n- Mark it `review` when implementation is done\n- Mark it `done` after verification (tests pass, typecheck clean)\n- If you discover new dependencies, add them to `blocks`/`depends_on`\n\n---\n\n## Dependency Graph\n\nFor tickets with complex dependencies, generate a visual summary:\n\n```\nT-001 (Auth) ──blocks──→ T-003 (Dashboard)\n    │                        │\n    └──blocks──→ T-002 (API) ─┘\n                     │\n                     └──soft-dep──→ T-004 (Rate Limiting)\n\nReady to work: T-001 (no dependencies)\nBlocked: T-002 (waiting on T-001), T-003 (waiting on T-001, T-002)\n```\n\n---\n\n## Integration With Mipham Code\n\n- **Session Store**: Ticket status persists across sessions via `.mipham/tickets/`\n- **Memory System**: Active tickets are loaded as project memory for context\n- **grill-with-docs**: The output of a grill session feeds directly into ticket decomposition\n- **Background Agents**: Long-running work on a ticket can be spawned as a background agent\n- **Critical Thinking Layer**: When decomposing, ask \"what's the smallest thing that delivers value?\" — don't over-decompose\n" },
+  { type: 'standard', raw: "---\nname: trim-process-prose\ndescription: Use when cleaning process-perspective narration an AI left in code, comments, docs, or commit messages — \"originally A, changed to B\", design-decision references, or review back-and-forth a reader with only the current checkout cannot independently parse or verify\nversion: 1.0.0\n---\n\n# Trim Process Prose\n\nAgents leave their working perspective in the repo — \"initially we used A, then the reviewer wanted B\", \"decision 7\", \"for now, fix later\" — which only makes sense inside the session that produced it. Months later a maintainer has only the checkout, not the chat, the PR thread, or the task plan. That residue is process prose.\n\n## The test\n\nFor any sentence a change adds — a comment, a doc line, a commit-message clause — ask:\n\n> **Can a reader holding only the current HEAD checkout independently parse and verify this?**\n\n- **Yes** → keep it.\n- **No** → keep the durable fact, drop the process.\n\nThe fact is what a future maintainer needs; the process is how you got there, and it dies with the session.\n\n## What to keep vs drop\n\n| Keep (durable)                                                                          | Drop (process)                                                             |\n| --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |\n| Why B is _required_: \"B is used here because A leaks resources under concurrent cancel\" | How you chose it: \"initially A, then reviewer preferred B\"                 |\n| A contract/invariant: \"this must hold or X breaks\"                                      | A reference a HEAD reader can't resolve: \"decision 7\", \"C2\", \"design §4.7\" |\n| A precondition/postcondition the next editor must respect                               | A status marker: \"for now\", \"v3 will handle this\", \"TODO after PR\"         |\n| A compatibility promise                                                                 | A review trace: \"reviewer confirmed\", \"per discussion\"                     |\n\n## Rewrite, don't annotate\n\n```diff\n- // originally plan A had a race; reviewer asked for B; switching to B\n+ // B: plan A could not guarantee resource release under concurrent cancel\n```\n\nThe second line is the only thing the next maintainer needs. The first line is archaeology.\n\n## When NOT to touch\n\n- A sentence that already passes the HEAD-reader test — do not strip facts to be tidy.\n- A working session in progress — trim at commit/push time, not while reasoning.\n- `docs/truth/**` claims that cite `file:line` — those are evidence, not process.\n\n## Red flags\n\n- \"This context is useful\" — useful to _you now_; the test is the HEAD reader, not you.\n- Keeping \"originally X / changed to Y\" — the change is already visible in the diff; the narration is redundant.\n- Leaving a task-plan reference the reader can't resolve — that is the exact leakage to remove.\n" },
   { type: 'standard', raw: "---\nname: web-access\ndescription: '联网访问：CDP 驱动用户已登录 Chrome（登录后操作、动态页面、反爬站点、社交媒体、本地书签/历史检索）'\nlicense: MIT\ngithub: https://github.com/eze-is/web-access\nversion: 2.5.0\nuser-invocable: true\nallowed-tools:\n  - Bash\n  - WebFetch\n  - WebSearch\n  - Read\n---\n\n# Web Access — CDP 驱动已登录 Chrome\n\n> 来源：eze-is/web-access (MIT)，Mipham Code 合并升级。核心能力 = CDP Proxy 直连用户日常 Chrome，天然携带登录态。\n\n## 前置检查\n\n先确保 CDP 就绪：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/check-deps.mjs\n```\n\n> Mipham Code 环境：`node` 不可用时可用 `bun` 替代（Bun 原生支持 WebSocket 与 node: 内建）。未通过时引导用户：Chrome 地址栏打开 `chrome://inspect/#remote-debugging`，勾选 \"Allow remote debugging for this browser instance\"。\n\n**必须向用户展示**：部分站点对浏览器自动化检测严格，存在账号封禁风险。已内置防护但无法完全避免，Agent 继续操作即视为接受。\n\n## 工具选择\n\n| 场景                                          | 工具        |\n| --------------------------------------------- | ----------- |\n| 搜索摘要 / 发现来源                           | WebSearch   |\n| URL 已知，定向提取                            | WebFetch    |\n| URL 已知，要原始 HTML（meta/JSON-LD）         | Bash + curl |\n| 非公开内容 / 反爬站点（小红书、微信公众号等） | 浏览器 CDP  |\n| 需要登录态、交互、自由导航                    | 浏览器 CDP  |\n\n浏览器 CDP 不要求 URL 已知；WebSearch/WebFetch/curl 均不处理登录态。\n\n## 浏览器 CDP 模式\n\n通过 CDP Proxy 直连用户日常 Chrome，天然携带登录态。**不主动操作用户已有 tab**，所有操作在自己创建的后台 tab 中进行，任务结束关闭自建 tab（保留用户原 tab）。\n\nProxy（`scripts/cdp-proxy.mjs`）由 `check-deps.mjs` 自动拉起并常驻。Proxy 首次启动生成共享密钥 `~/.mipham/skills/web-access/.cdp-token`（0600），除 `/health` 外所有端点都要求请求头 `X-CDP-Token`。先取 token 再调 API：\n\n```bash\nTOKEN=$(cat ~/.mipham/skills/web-access/.cdp-token)\ncurl -H \"X-CDP-Token: $TOKEN\" http://localhost:3456/targets\n```\n\n端点列表：\n\n| 端点                                       | 用途                                                                     |\n| ------------------------------------------ | ------------------------------------------------------------------------ |\n| `GET /targets`                             | 列出已开 tab                                                             |\n| `GET /new?url=`                            | 新建后台 tab（自动等加载）                                               |\n| `GET /navigate?target=&url=`               | 导航（自动等加载）                                                       |\n| `GET /back?target=`                        | 后退                                                                     |\n| `GET /info?target=`                        | 页面标题/URL/状态                                                        |\n| `POST /eval?target=`（body=JS）            | 执行任意 JS（读写 DOM、提取、提交）                                      |\n| `POST /click?target=`（body=CSS 选择器）   | JS 点击（`el.click()`，覆盖大多数场景）                                  |\n| `POST /clickAt?target=`（body=CSS 选择器） | 真实鼠标点击（`Input.dispatchMouseEvent`，算用户手势，能触发文件对话框） |\n| `POST /setFiles?target=`（body JSON）      | 设置 file input 本地文件路径（`DOM.setFileInputFiles`，绕过文件对话框）  |\n| `GET /scroll?target=&y=&direction=`        | 滚动（`direction=down/up/top/bottom`，触发懒加载）                       |\n| `GET /screenshot?target=&file=`            | 截图                                                                     |\n| `GET /close?target=`                       | 关闭 tab                                                                 |\n\n进入浏览器层后，`/eval` 是眼睛、`/click` 是手：先看 DOM 结构再决定下一步，不预先规划所有步骤。\n\n### 登录判断\n\n核心问题只有一个：**目标内容拿到了吗？** 打开页面先尝试获取目标内容；确认「目标内容无法获取」且判断登录能解决时，告知用户在其 Chrome 登录后继续（无需重启任何东西，刷新页面即可）。\n\n### 媒体资源提取\n\n判断内容在图片里时，用 `/eval` 从 DOM 直接拿图片 URL 定向读取，比全页截图精准。`/scroll` 到底部触发懒加载后再提取图片 URL。\n\n### 视频内容获取\n\n用户 Chrome 真实渲染，截图可捕获当前视频帧。用 `/eval` 操控 `<video>`（时长、seek、播放/暂停），配合 `/screenshot` 采帧，做离散采样分析。\n\n## 本地 Chrome 资源\n\n用户指向「本人访问过的页面」或「组织内部系统」时，检索本地书签/历史：\n\n```bash\nnode ~/.mipham/skills/web-access/scripts/find-url.mjs [关键词...] [--only bookmarks|history] [--limit N] [--since 1d|7h|YYYY-MM-DD] [--sort recent|visits]\n```\n\n## 并行调研：子 Agent 分治\n\n多个独立调研目标时，分治给子 Agent 并行执行（共享一个 Chrome、一个 Proxy，各自建 tab、各自 `/close`，无竞态）。子 Agent prompt 写**目标**（「获取/调研/了解」），不写**手段**（避免「搜索xx」锚定到 WebSearch 而错过需 CDP 的反爬站点）。\n\n## 信息核实\n\n核实目标是一手来源，非二手报道。搜索引擎是**定位**工具，不可直接**证明**真伪；找到来源后直接访问读原文。\n\n| 信息类型      | 一手来源       |\n| ------------- | -------------- |\n| 政策/法规     | 发布机构官网   |\n| 企业公告      | 公司官方新闻页 |\n| 工具能力/用法 | 官方文档、源码 |\n\n### 交叉验证\n\n- 关键声明须 2+ 独立来源交叉印证。\n- 优先采纳当年/近期资料。\n- 权威层级：官方文档 > 知名博客 > 技术社区 > 随机论坛。\n\n### 来源归因\n\n回答结尾附来源列表：\n\n```markdown\nSources:\n\n- [标题](URL) — 一句话说明\n```\n\n## 站点经验\n\n特定网站经验按域名存 `~/.mipham/skills/web-access/references/site-patterns/<domain>.md`（frontmatter: domain/aliases/updated + 平台特征/有效模式/已知陷阱）。操作前若有匹配经验先读；操作成功后把验证过的新模式写回。\n\n## Security Rules\n\n- 不主动操作用户已有 tab；任务结束关闭自建 tab。\n- 不提交凭据（除非用户显式批准）。\n- 尊重 robots.txt 与速率限制；不抓 PII。\n- proxy 仅绑 127.0.0.1，不暴露外网；除 `/health` 外所有端点要求 `X-CDP-Token` 共享密钥（`~/.mipham/skills/web-access/.cdp-token`，0600），防浏览器 CSRF 到 localhost。勿在共享/多用户主机运行。\n- URL 过窄 SSRF 校验：拒绝非 http(s)/about 协议与云元数据端点（`169.254.169.254` / `metadata.google.internal`）。⚠️ 私有网段（10.x / 172.16 / 192.168 / localhost）**有意放行**——本工具用途即访问组织内网（SSO 后台/内部系统），与 web-fetch 的完整 SSRF 屏蔽不同。\n\n## 何时不用本 skill\n\n- 纯逻辑/算法题（推理非研究）。\n- 代码已在上下文里的问题。\n- 大文件下载 → Bash + curl。\n" },
   { type: 'standard', raw: "---\nname: web-search\ndescription: Search the web for current information — documentation, news, technical references, troubleshooting, and research. Routes queries through Brave Search API with domain filtering and source verification.\nversion: 3.0.0\nuser-invocable: true\nallowed-tools:\n  - WebSearch\n  - WebFetch\n---\n\n# Web Search — Executable Workflow\n\n**Type**: Flexible — follow the query construction rules strictly, then adapt verification depth to the task.\n\n**Purpose**: Find accurate, current information from the web. This skill covers query formulation, domain filtering, result verification, and when to follow up with WebFetch for deep reading.\n\n**Triggers**: \"search for\", \"look up\", \"find\", \"what is\", \"how to\", \"latest\", \"current\", \"news about\", \"documentation for\", \"research\"\n\n---\n\n## Phase 0: Decide Whether to Search (ALWAYS RUN FIRST)\n\n```\nQuestion involves...\n├── Current events, news, recent releases?\n│   └── YES → Search (model training cutoff limitation)\n│\n├── Library/framework documentation?\n│   └── YES → Search (version-specific, up-to-date)\n│\n├── Error messages, stack traces?\n│   └── YES → Search (known issues, fixes)\n│\n├── Technology comparisons, benchmarks?\n│   └── YES → Search (current data)\n│\n├── Pure logic, algorithms, math?\n│   └── NO → Reason directly (no external data needed)\n│\n├── Question answerable from code in context?\n│   └── NO → Use existing context (faster, no network)\n│\n└── Opinion / subjective?\n    └── MAYBE → Search for data points, not consensus\n```\n\n---\n\n## Phase 1: Construct the Query\n\n### Rules (apply in order)\n\n1. **Be specific**: include version numbers, dates, proper nouns\n2. **Use technical terms**: framework/language jargon over natural language\n3. **Include context**: OS, environment, constraints if relevant\n4. **English preferred**: technical content is richer in English\n\n### Examples\n\n```\n❌ \"React\"                                → too broad\n❌ \"React problems\"                       → ambiguous\n❌ \"how to make website fast\"             → natural language\n✅ \"React 19 useEffect double mount fix\"  → specific + versioned\n✅ \"Core Web Vitals LCP optimization Next.js 14\"\n✅ \"Prisma 5 findMany nested include filter TypeScript\"\n✅ \"playwright click button not working 2026\"\n```\n\n### For Chinese-Language Queries\n\nChinese queries work but yield fewer technical results:\n\n```\n✅ \"React 19 useEffect 执行两次 修复\"     → mixed language for best results\n✅ \"Vue 3 Composition API 最佳实践 2026\"\n```\n\n---\n\n## Phase 2: Filter & Verify Results\n\n### Domain Authority Tiers\n\n| Tier              | Domains                                                               | Weight  |\n| ----------------- | --------------------------------------------------------------------- | ------- |\n| **Official**      | docs.github.com, nextjs.org, nodejs.org, python.org, rust-lang.org    | Highest |\n| **Authoritative** | developer.mozilla.org, web.dev, kubernetes.io                         | High    |\n| **Trusted**       | stackoverflow.com (high-score), dev.to, medium.com (verified authors) | Medium  |\n| **Low**           | personal blogs, random forums, w3schools                              | Low     |\n\n### Use allowed_domains for targeted searches\n\n```json\n{ \"query\": \"Next.js caching\", \"allowed_domains\": [\"nextjs.org\", \"github.com\"] }\n```\n\n### Use blocked_domains to exclude noise\n\n```json\n{ \"query\": \"JavaScript array methods\", \"blocked_domains\": [\"w3schools.com\"] }\n```\n\n### Cross-Reference Rule\n\n- **Critical claims** (API behavior, security): 2+ independent sources\n- **Code examples**: test before recommending\n- **Version info**: check publish date (prefer current year)\n\n---\n\n## Phase 3: Deep Read (When Needed)\n\nAfter search returns results, decide whether to deep-read:\n\n```\nSearch result looks promising?\n├── Snippet answers the question fully?\n│   └── → Use snippet + cite source (done)\n│\n├── Need code examples / detailed API docs?\n│   └── → WebFetch the page URL\n│       Use prompt to focus extraction\n│\n├── Multiple sources needed for verification?\n│   └── → WebFetch top 2-3 results\n│       Cross-reference and flag contradictions\n│\n└── Page is JavaScript SPA / login-walled?\n    └── → Delegate to web-access skill (ComputerUse browser)\n```\n\n---\n\n## Phase 4: Report Results\n\n### Format\n\n```markdown\n## [Topic]\n\n[Answer with inline citations]\n\n### Details (if deep-read was done)\n\n[Structured content from fetched pages]\n\nSources:\n\n- [Title](URL) — [1-sentence note on what was found there]\n- [Title](URL) — [1-sentence note]\n```\n\n### Attribution Rules\n\n- Always include source URLs\n- Note if a source is official docs vs community\n- Flag outdated content (e.g., \"article from 2024, may be stale\")\n- Distinguish between facts (need citation) and reasoning (your own)\n\n---\n\n## Search API Configuration\n\nWeb search uses **Brave Search API** (free tier: 2,000 queries/month).\n\nIf search returns \"not configured\":\n\n1. Get a free API key at https://brave.com/search/api/\n2. Set: `export BRAVE_API_KEY=\"BSA...\"`\n3. Restart Mipham Code\n\nAlternatives (additional API keys supported):\n\n- `TAVILY_API_KEY` — https://tavily.com\n- `SERPAPI_API_KEY` — https://serpapi.com\n" },
   { type: 'mipham', raw: "---\nname: doc-sync\ndescription: Keep engineering truth docs aligned with code — map changed code to docs, update stale docs after functional changes, keep git-reviewable\nversion: 1.0.0\n---\n\n# Doc Sync\n\nKeep engineering \"truth docs\" aligned with code. After a functional code change, run this skill to find the docs that map to the changed code, check them against the code + tests, and update anything that drifted. Docs travel with the branch in git and are reviewed alongside the code diff.\n\n## Where truth docs live\n\nEngineering truth docs live under `docs/truth/engineering/`. Routing from code → docs lives in `docs/truth/ROUTES.md`.\n\n```\ndocs/truth/\n├── ROUTES.md            # code area → canonical doc mapping\n└── engineering/\n    ├── behaviors/       # implementation behavior\n    ├── contracts/       # API / interface contracts\n    ├── architecture/    # component structure and boundaries\n    ├── workflows/       # multi-step flows and orchestration\n    └── operations/      # runbooks, config, deployment\n```\n\n## Invariants (never break)\n\n- **Doc-only**: touch `docs/truth/**` and `ROUTES.md` only. Never modify functional code, tests, or config outside `docs/truth/`.\n- **Evidence-backed**: every claim cites `file:line` (or `file` for a whole file). No invented behavior.\n- **Branch-scoped**: docs change in the same branch as the code, so they review together.\n\n## Workflow\n\n### 1. Map — find the docs that cover the change\n\nDetermine the changed code. Prefer an explicit path argument; otherwise use the working-tree or branch diff:\n\n```bash\ngit diff --name-only            # uncommitted working-tree changes\ngit diff --name-only HEAD~1     # last commit\n```\n\nRead `docs/truth/ROUTES.md` and match the changed paths to their canonical doc. A route is a glob → doc path pair. A changed path with no route is a signal to create one (Step 3).\n\n### 2. Check — is the doc now stale?\n\nFor each mapped doc, read the doc, the changed code, and the relevant tests. Compare:\n\n- Does the doc describe behavior the code no longer has?\n- Does the code add or remove behavior the doc doesn't mention?\n- Do contract shapes (signatures, types, errors) still match?\n- Are the `file:line` evidence pointers still valid?\n\nA doc is stale when any claim no longer matches the code + tests.\n\n### 3. Update — fix the drift\n\n- **Existing doc, stale**: edit the doc in place. Update claims, refresh `file:line` pointers, remove dead behavior, add new behavior. Keep the section structure unless the change demands otherwise.\n- **Existing doc, orphaned**: if the mapped code is gone, remove the doc and its route entry.\n- **Changed path has no route**: create one bounded doc under the right `docs/truth/engineering/<type>/` folder and add a route entry to `ROUTES.md`. Scope the doc to the changed area — do not document the whole codebase.\n\nKeep the diff minimal and reviewable: one doc per functional change, no unrelated rewrites.\n\n### 4. Verify — reviewable and true\n\nConfirm before reporting done:\n\n- `git diff --stat` shows only `docs/truth/**` and `ROUTES.md`.\n- Every claim in the updated doc has a `file:line` pointer that exists in the working tree.\n- The doc matches the code + tests, not the other way around.\n\nReport: \"Updated <doc> for <change>. Review the truth diff alongside the code diff.\"\n\n## Document templates\n\n### Behavior (`behaviors/`)\n\n```markdown\n# <Behavior Name>\n\n**Area**: <route / component>\n**Evidence**: `src/<file>:<line>`\n\n## What it does\n\n<one-paragraph summary, from code + tests>\n\n## Behavior\n\n- <observable behavior> — `src/<file>:<line>`\n\n## Edge cases\n\n- <case> — `src/<file>:<line>`\n\n## Tests\n\n- `tests/<file>.test.ts` — covers <behavior>\n```\n\n### Contract (`contracts/`)\n\n```markdown\n# <API / Interface>\n\n**Evidence**: `src/<file>:<line>`\n\n## Signature\n\n\\`\\`\\`ts\n// the actual exported signature\n\\`\\`\\`\n\n## Parameters\n\n| Param | Type | Description |\n| ----- | ---- | ----------- |\n\n## Returns / Errors\n\n- ...\n\n## Consumers\n\n- <caller> — `src/<file>:<line>`\n```\n\n### Architecture (`architecture/`)\n\n```markdown\n# <Component / Module>\n\n**Evidence**: `src/<file>`\n\n## Responsibility\n\n<one paragraph — what it owns, what it doesn't>\n\n## Dependencies\n\n- depends on: <...>\n- depended on by: <...>\n\n## Boundaries\n\n- <seam / interface> — `src/<file>:<line>`\n```\n\n### Workflow (`workflows/`)\n\n```markdown\n# <Workflow Name>\n\n**Evidence**: `src/<file>:<line>`\n\n## Steps\n\n1. <step> — `src/<file>:<line>`\n\n## Trigger / Exit\n\n- trigger: <...>\n- success: <...> / failure: <...>\n```\n\n### Operations (`operations/`)\n\n```markdown\n# <Runbook / Config>\n\n**Evidence**: `src/<file>`\n\n## Config / Env\n\n| Key | Default | Meaning |\n| --- | ------- | ------- |\n\n## Runbook\n\n- <action> — <command or step>\n\n## Failure modes\n\n- <symptom> → <cause> → <fix>\n```\n\n## Routing file (`ROUTES.md`)\n\n```markdown\n# Truth Routes\n\n| Code pattern      | Doc                                      |\n| ----------------- | ---------------------------------------- |\n| src/auth/session* | engineering/behaviors/session-timeout.md |\n| src/api/*         | engineering/contracts/api.md             |\n```\n\nPatterns are globs relative to the repo root. One doc may be routed by several patterns; one pattern maps to one doc. Keep patterns as specific as needed to avoid one giant doc.\n" },