@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/sql-optimization/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: sql-optimization
+description: 'Universal SQL performance optimization assistant for comprehensive query tuning, indexing strategies, and database performance analysis across all SQL databases (MySQL, PostgreSQL, SQL Server, Oracle). Provides execution plan analysis, pagination optimization, batch operations, and performance monitoring guidance.'
+---
+
+# SQL Performance Optimization Assistant
+
+Expert SQL performance optimization for ${selection} (or entire project if no selection). Focus on universal SQL optimization techniques that work across MySQL, PostgreSQL, SQL Server, Oracle, and other SQL databases.
+
+## 🎯 Core Optimization Areas
+
+### Query Performance Analysis
+```sql
+-- ❌ BAD: Inefficient query patterns
+SELECT * FROM orders o
+WHERE YEAR(o.created_at) = 2024
+  AND o.customer_id IN (
+      SELECT c.id FROM customers c WHERE c.status = 'active'
+  );
+
+-- ✅ GOOD: Optimized query with proper indexing hints
+SELECT o.id, o.customer_id, o.total_amount, o.created_at
+FROM orders o
+INNER JOIN customers c ON o.customer_id = c.id
+WHERE o.created_at >= '2024-01-01' 
+  AND o.created_at < '2025-01-01'
+  AND c.status = 'active';
+
+-- Required indexes:
+-- CREATE INDEX idx_orders_created_at ON orders(created_at);
+-- CREATE INDEX idx_customers_status ON customers(status);
+-- CREATE INDEX idx_orders_customer_id ON orders(customer_id);
+```
+
+### Index Strategy Optimization
+```sql
+-- ❌ BAD: Poor indexing strategy
+CREATE INDEX idx_user_data ON users(email, first_name, last_name, created_at);
+
+-- ✅ GOOD: Optimized composite indexing
+-- For queries filtering by email first, then sorting by created_at
+CREATE INDEX idx_users_email_created ON users(email, created_at);
+
+-- For full-text name searches
+CREATE INDEX idx_users_name ON users(last_name, first_name);
+
+-- For user status queries
+CREATE INDEX idx_users_status_created ON users(status, created_at)
+WHERE status IS NOT NULL;
+```
+
+### Subquery Optimization
+```sql
+-- ❌ BAD: Correlated subquery
+SELECT p.product_name, p.price
+FROM products p
+WHERE p.price > (
+    SELECT AVG(price) 
+    FROM products p2 
+    WHERE p2.category_id = p.category_id
+);
+
+-- ✅ GOOD: Window function approach
+SELECT product_name, price
+FROM (
+    SELECT product_name, price,
+           AVG(price) OVER (PARTITION BY category_id) as avg_category_price
+    FROM products
+) ranked
+WHERE price > avg_category_price;
+```
+
+## 📊 Performance Tuning Techniques
+
+### JOIN Optimization
+```sql
+-- ❌ BAD: Inefficient JOIN order and conditions
+SELECT o.*, c.name, p.product_name
+FROM orders o
+LEFT JOIN customers c ON o.customer_id = c.id
+LEFT JOIN order_items oi ON o.id = oi.order_id
+LEFT JOIN products p ON oi.product_id = p.id
+WHERE o.created_at > '2024-01-01'
+  AND c.status = 'active';
+
+-- ✅ GOOD: Optimized JOIN with filtering
+SELECT o.id, o.total_amount, c.name, p.product_name
+FROM orders o
+INNER JOIN customers c ON o.customer_id = c.id AND c.status = 'active'
+INNER JOIN order_items oi ON o.id = oi.order_id
+INNER JOIN products p ON oi.product_id = p.id
+WHERE o.created_at > '2024-01-01';
+```
+
+### Pagination Optimization
+```sql
+-- ❌ BAD: OFFSET-based pagination (slow for large offsets)
+SELECT * FROM products 
+ORDER BY created_at DESC 
+LIMIT 20 OFFSET 10000;
+
+-- ✅ GOOD: Cursor-based pagination
+SELECT * FROM products 
+WHERE created_at < '2024-06-15 10:30:00'
+ORDER BY created_at DESC 
+LIMIT 20;
+
+-- Or using ID-based cursor
+SELECT * FROM products 
+WHERE id > 1000
+ORDER BY id 
+LIMIT 20;
+```
+
+### Aggregation Optimization
+```sql
+-- ❌ BAD: Multiple separate aggregation queries
+SELECT COUNT(*) FROM orders WHERE status = 'pending';
+SELECT COUNT(*) FROM orders WHERE status = 'shipped';
+SELECT COUNT(*) FROM orders WHERE status = 'delivered';
+
+-- ✅ GOOD: Single query with conditional aggregation
+SELECT 
+    COUNT(CASE WHEN status = 'pending' THEN 1 END) as pending_count,
+    COUNT(CASE WHEN status = 'shipped' THEN 1 END) as shipped_count,
+    COUNT(CASE WHEN status = 'delivered' THEN 1 END) as delivered_count
+FROM orders;
+```
+
+## 🔍 Query Anti-Patterns
+
+### SELECT Performance Issues
+```sql
+-- ❌ BAD: SELECT * anti-pattern
+SELECT * FROM large_table lt
+JOIN another_table at ON lt.id = at.ref_id;
+
+-- ✅ GOOD: Explicit column selection
+SELECT lt.id, lt.name, at.value
+FROM large_table lt
+JOIN another_table at ON lt.id = at.ref_id;
+```
+
+### WHERE Clause Optimization
+```sql
+-- ❌ BAD: Function calls in WHERE clause
+SELECT * FROM orders 
+WHERE UPPER(customer_email) = 'JOHN@EXAMPLE.COM';
+
+-- ✅ GOOD: Index-friendly WHERE clause
+SELECT * FROM orders 
+WHERE customer_email = 'john@example.com';
+-- Consider: CREATE INDEX idx_orders_email ON orders(LOWER(customer_email));
+```
+
+### OR vs UNION Optimization
+```sql
+-- ❌ BAD: Complex OR conditions
+SELECT * FROM products 
+WHERE (category = 'electronics' AND price < 1000)
+   OR (category = 'books' AND price < 50);
+
+-- ✅ GOOD: UNION approach for better optimization
+SELECT * FROM products WHERE category = 'electronics' AND price < 1000
+UNION ALL
+SELECT * FROM products WHERE category = 'books' AND price < 50;
+```
+
+## 📈 Database-Agnostic Optimization
+
+### Batch Operations
+```sql
+-- ❌ BAD: Row-by-row operations
+INSERT INTO products (name, price) VALUES ('Product 1', 10.00);
+INSERT INTO products (name, price) VALUES ('Product 2', 15.00);
+INSERT INTO products (name, price) VALUES ('Product 3', 20.00);
+
+-- ✅ GOOD: Batch insert
+INSERT INTO products (name, price) VALUES 
+('Product 1', 10.00),
+('Product 2', 15.00),
+('Product 3', 20.00);
+```
+
+### Temporary Table Usage
+```sql
+-- ✅ GOOD: Using temporary tables for complex operations
+CREATE TEMPORARY TABLE temp_calculations AS
+SELECT customer_id, 
+       SUM(total_amount) as total_spent,
+       COUNT(*) as order_count
+FROM orders 
+WHERE created_at >= '2024-01-01'
+GROUP BY customer_id;
+
+-- Use the temp table for further calculations
+SELECT c.name, tc.total_spent, tc.order_count
+FROM temp_calculations tc
+JOIN customers c ON tc.customer_id = c.id
+WHERE tc.total_spent > 1000;
+```
+
+## 🛠️ Index Management
+
+### Index Design Principles
+```sql
+-- ✅ GOOD: Covering index design
+CREATE INDEX idx_orders_covering 
+ON orders(customer_id, created_at) 
+INCLUDE (total_amount, status);  -- SQL Server syntax
+-- Or: CREATE INDEX idx_orders_covering ON orders(customer_id, created_at, total_amount, status); -- Other databases
+```
+
+### Partial Index Strategy
+```sql
+-- ✅ GOOD: Partial indexes for specific conditions
+CREATE INDEX idx_orders_active 
+ON orders(created_at) 
+WHERE status IN ('pending', 'processing');
+```
+
+## 📊 Performance Monitoring Queries
+
+### Query Performance Analysis
+```sql
+-- Generic approach to identify slow queries
+-- (Specific syntax varies by database)
+
+-- For MySQL:
+SELECT query_time, lock_time, rows_sent, rows_examined, sql_text
+FROM mysql.slow_log
+ORDER BY query_time DESC;
+
+-- For PostgreSQL:
+SELECT query, calls, total_time, mean_time
+FROM pg_stat_statements
+ORDER BY total_time DESC;
+
+-- For SQL Server:
+SELECT 
+    qs.total_elapsed_time/qs.execution_count as avg_elapsed_time,
+    qs.execution_count,
+    SUBSTRING(qt.text, (qs.statement_start_offset/2)+1,
+        ((CASE qs.statement_end_offset WHEN -1 THEN DATALENGTH(qt.text)
+        ELSE qs.statement_end_offset END - qs.statement_start_offset)/2)+1) as query_text
+FROM sys.dm_exec_query_stats qs
+CROSS APPLY sys.dm_exec_sql_text(qs.sql_handle) qt
+ORDER BY avg_elapsed_time DESC;
+```
+
+## 🎯 Universal Optimization Checklist
+
+### Query Structure
+- [ ] Avoiding SELECT * in production queries
+- [ ] Using appropriate JOIN types (INNER vs LEFT/RIGHT)
+- [ ] Filtering early in WHERE clauses
+- [ ] Using EXISTS instead of IN for subqueries when appropriate
+- [ ] Avoiding functions in WHERE clauses that prevent index usage
+
+### Index Strategy
+- [ ] Creating indexes on frequently queried columns
+- [ ] Using composite indexes in the right column order
+- [ ] Avoiding over-indexing (impacts INSERT/UPDATE performance)
+- [ ] Using covering indexes where beneficial
+- [ ] Creating partial indexes for specific query patterns
+
+### Data Types and Schema
+- [ ] Using appropriate data types for storage efficiency
+- [ ] Normalizing appropriately (3NF for OLTP, denormalized for OLAP)
+- [ ] Using constraints to help query optimizer
+- [ ] Partitioning large tables when appropriate
+
+### Query Patterns
+- [ ] Using LIMIT/TOP for result set control
+- [ ] Implementing efficient pagination strategies
+- [ ] Using batch operations for bulk data changes
+- [ ] Avoiding N+1 query problems
+- [ ] Using prepared statements for repeated queries
+
+### Performance Testing
+- [ ] Testing queries with realistic data volumes
+- [ ] Analyzing query execution plans
+- [ ] Monitoring query performance over time
+- [ ] Setting up alerts for slow queries
+- [ ] Regular index usage analysis
+
+## 📝 Optimization Methodology
+
+1. **Identify**: Use database-specific tools to find slow queries
+2. **Analyze**: Examine execution plans and identify bottlenecks
+3. **Optimize**: Apply appropriate optimization techniques
+4. **Test**: Verify performance improvements
+5. **Monitor**: Continuously track performance metrics
+6. **Iterate**: Regular performance review and optimization
+
+Focus on measurable performance improvements and always test optimizations with realistic data volumes and query patterns.

package/skills/summarize/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: summarize
 description: 把一份素材（SPMS 的需求/开发计划/Issue、一份本地文档、或一个主题）讲成一份人人都读得懂的 HTML 报告，并提交到指定项目的「报告」Tab。凡用户输入 /summarize <素材> --project <项目>，或要求「给这条需求写份解读 / 把这份开发计划总结一下发到项目里 / 出一份报告放到项目报告区」时使用。Use when the user types /summarize <material>, or asks for a readable report to be produced and filed into an SPMS project's Reports tab.
+disable-model-invocation: true
 ---
 
 # summarize · 产出一份报告，并把它放进项目里

package/skills/swarm/references/teams/product.md

@@ -29,7 +29,7 @@
 | 角色 | 载体 | 模型/effort | 权限 | 可写范围 | 职责 |
 |------|------|-----------|------|---------|------|
 | **lead（产品负责人）** | 当前会话 | — | — | 定稿合入 | 唯一与用户对话的人；汇聚澄清问题并批量提问；裁决分歧；合成评审结论 |
-| **product-designer（产品设计师）** | `general-purpose`，或自定义 `.claude/agents/product-designer.md` | `opus`/`sonnet` + `high` | `acceptEdits` | `docs/prd/<feature>.md`（**PRD 唯一写手**） | 按 PRD 骨架产出：概述/目标/非目标 + 逐条 FR/NFR + 可断言验收标准 + TC 种子；分期建议放末尾 |
+| **product-designer（产品设计师）** | `general-purpose`，或自定义 `.claude/agents/product-designer.md` | `opus`/`sonnet` + `high` | `acceptEdits` | `docs/prd/<feature>.md`（**PRD 唯一写手**） | 按 PRD 骨架产出：概述/目标/非目标 + 逐条 FR/NFR + 可断言验收标准 + UAT 场景预期状态；六维推演与 SMAR 检查，分期建议放末尾，不创建 TC |
 | **clarifier（需求澄清官）** | `Explore`（只读） | `sonnet` | 只读 | 不写文件，交问题清单 | 找歧义、缺口、隐含假设；构造 2–4 个高信息量业务场景压测语义与边界；问题分级并给建议默认值 |
 | **stakeholder-proxy（干系人代理）** | `Explore` | `sonnet` | 只读 | 交立场报告 | 分别代入最终用户 / 运营 / 客服 / 合规 / 数据等视角，指出这份需求会让哪个角色受伤、哪句话会被误解 |
 | **feasibility-reviewer（技术可行性评审）** | `Explore` | `sonnet`/`opus` | 只读 | 交可行性报告 | 对着**代码库事实**核对：现有数据模型/接口/权限能否承接、影响面、隐藏成本；结论分「可直接做 / 需先改 X / 做不到」 |
@@ -86,7 +86,7 @@
 |-------|------|------------------|
 | `prd` | product-designer | PRD 骨架、FR/NFR 编号与验收标准写法、SPMS 写入口径 |
 | `story-points` | estimator | 四轴因子表、复现性要求（同输入同输出）、写回 `plannedPoints` 前需 lead 同意 |
-| `test-plan` | acceptance-reviewer | 「标准 → 用例」映射；不得覆盖或改写 PRD 种下的 TC 种子 |
+| `test-plan` | acceptance-reviewer | 将验收条件与 UAT 状态展开为测试方法及「标准 → 用例」映射；不得覆盖或改写既有用例（含历史 PRD 种子） |
 | `dev-plan` | 定稿后由 lead 触发 | 需求定稿是 dev-plan 的前置输入 |
 
 ---

package/skills/tdd/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: tdd
+description: "Use only when the user explicitly asks for TDD, a failing test, or a regression test, OR when the bug has an obvious cheap local test target. Skip when the test path is unclear, expensive, integration-heavy, or not requested."
+disable-model-invocation: true
+---
+
+# TDD Bug Fix
+
+When fixing a bug with a clear, cheap test path, make the broken behavior executable before changing production code. The goal is a focused regression test that fails before the fix and passes after it.
+
+Do not force a test when it would be impractical. If the available test would require broad harness setup, brittle mocks, slow end-to-end infrastructure, production-only state, vague reproduction steps, or large unrelated fixture churn, skip adding a new test and use the closest useful verification instead.
+
+## Workflow
+
+1. **Understand the bug.** Identify the intended behavior, current behavior, affected path, and smallest observable reproduction.
+2. **Choose the narrowest executable check.** Prefer the closest unit, component, integration, or regression test already used for that codepath. If no practical test path is obvious, do not create one from scratch just to satisfy the workflow.
+3. **Write the failing test first.** Add the smallest focused test that would have caught the bug. The test should encode intended behavior, not mirror the current implementation.
+4. **Run the new test before fixing.** Confirm it fails for the intended reason. If it passes or fails for an unrelated reason, correct the test or reproduction before editing the implementation.
+5. **Fix the bug.** Make the smallest production change that satisfies the intended behavior while preserving nearby contracts.
+6. **Rerun the regression test.** Confirm the test now passes.
+
+## If a Failing Test Is Impractical
+
+Use the closest executable regression check instead: a targeted script, manual reproduction command, browser automation, snapshot comparison, log assertion, or focused integration check.
+
+Prefer no new test over a bad test. A bad test is one that mostly tests mocks, encodes current implementation details, depends on timing or unrelated global state, needs expensive infrastructure for a small fix, or would be deleted immediately after proving the fix.
+
+## Guardrails
+
+- Do not change tests merely to match a wrong implementation.
+- Do not weaken existing assertions unless the expected behavior has genuinely changed and the reason is clear.
+- Keep the regression test focused on the bug. Avoid broad fixture churn or unrelated coverage expansion.
+- If the bug is flaky, make the test deterministic where possible and document the signal being locked down.
+- If the bug exposes a broader class of failures, first land the focused regression path, then consider additional sibling coverage.
+
+## Final Response
+
+Report the evidence, not just the outcome:
+
+- Name the failing-before test or executable check and the failure it produced.
+- Name the passing-after test run and any nearby validation performed.
+- If failing-before evidence could not be demonstrated, state why and describe the closest regression check used instead.

package/skills/teach/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: teach
+description: "Explain a body of work plainly so a person actually understands it. Runs the `how` and `why` skills and weaves what they find into one clear explanation. Use for 'teach me this', 'help me really understand X', 'explain this change or subsystem to me'."
+disable-model-invocation: true
+---
+
+# Teach
+
+**You explain what a thing is, how it works, and why it's built that way, in one plain account at the person's pace. The goal is that they understand it, not that you change anything.**
+
+Teach sits on top of `how` and `why`. Get your bearings on what the work is and what it touches, then run `how` for how it works and `why` for why it's that way. Those are real skill invocations that do their own digging. Blend what they find into one plain explanation, lead with what matters to the person, and go deeper when they ask. Reword freely for teaching, with one exception. Keep `why`'s confidence language intact (its hedges are findings, not style).
+
+1. Decide the few things they should walk away understanding. Choose them from why they're asking (about to change it, reviewing it, debugging it, new to it) and what they already know, both read from the conversation, not quizzed out of them. Skip what they plainly already know. Put the depth where their question is.
+2. Let `how` and `why` do the work, don't redo it. Read the code yourself to get oriented, then run `how` for how it works and `why` for why. Run them in parallel and combine the results. Match the size to the question. Run both for a subsystem, maybe one is enough for a small change. Keep `why` narrow by default since its full sweep is slow. Put the narrowing in the ask itself (a scoped question, git plus a source or two) so `why` records the skipped categories per its own contract, and widen it only when the reasons are the point.
+3. Start with a plain definition. Name the thing and say what it is in general terms, the way a senior engineer would say it out loud, with its common name if it has one. Then tie it to the case in front of you ("in X, we use this to ...") and build from there: how it works, the deeper reasons, the edge cases. For each part, explain the idea so it clicks: the problem it solves and how it actually works. Walk through what happens as the person does the thing (opens a long chat, scrolls up) when that is what makes it land. Listing functions and constants is reference, not teaching. Don't print framing labels ("the one idea to hold onto", "the thing to walk away with", "the key insight", "at its core", "TL;DR"). Give the smallest complete answer first, a sentence or two, not a dense paragraph, then stop. Add layers when they ask. Never a wall of text.
+4. Keep it a conversation, not a lecture or a performance. Offer to go deeper or move on, and follow their lead. No quizzes. No pacing theater. Don't print "Pause", don't ask them to say it back, don't announce "the sentence to nail", and don't flag a part as important or hard ("here is the part worth slowing down on", "this is the tricky part", "here is where it gets interesting"). Just say it. When you would pause, stop and let them respond. Running one-shot with no live human, deliver it cleanly and put any offer to go deeper at the end.
+5. Show, don't only tell, and build the picture up diagram by diagram. Open the diff, the code, or the debugger when that is the fastest way to land it. Draw when a picture lands faster than words. For anything with three or more moving parts, do not draw one diagram with all of them at once. Draw a short series instead, where each diagram redraws the last and adds a single part, so the reader watches the system assemble. A single all-at-once diagram, especially one saved for the end, is a reference, not teaching. Concretely, to teach a flow from A to B to C, draw it three times. First A to B. Then redraw and add C. Then redraw and add the return edge or the next piece. Match the medium to the idea, and use both kinds when both help. A mermaid diagram fits a flow or structure where the labels carry the meaning. When the idea is spatial, like layout, overlap, scroll position, or a before and after, reach for the image-generation tool and draw it marker-on-whiteboard style with a few short labels, since image models garble long text. Generate that picture, don't settle for describing it in words. The build-up rule holds for generated images too. A single simple point needs no figure.
+
+Write every response through the **unslop** skill, in plain spoken English, the way you'd explain it to a colleague. Be tight, not terse. Cut filler and hedging, keep the part that makes it click. State the concrete mechanism, not a metaphor, a framing, or a preview of what is coming. This is the target density: "Virtualization runs in two parts, one for rendering and one for loading from disk. When an item scrolls out past the buffer, both its DOM node and its in-memory data are evicted." Normal sentence case, not all-lowercase. No em dashes. Prefer periods over commas. Keep each sentence to one or two commas. If clauses pile up, split them into separate sentences. Give each concept one name and keep it. Avoid mirror sentences ("A without B, or B without A") and tidy closers ("the rest follows", "it all falls out"). The words in these steps are directions to you, not labels to print. Don't echo the structure as headers or stock phrases.
+
+**Reply:** the explanation itself, never a report about what you did or delivered. Lead with the main point, then the plain account of what it is, how it works, and why, and the threads worth chasing with `how` or `why`.

package/skills/test-plan/SKILL.md

@@ -22,18 +22,19 @@ description: 由需求（PRD 正文 + 验收标准）成套产出测试用例草
 
 ## 与 `prd` skill 的分工(别重复建单)
 
-`prd` skill 在建需求时**每条 FR 已经种了 1 条 TC 种子**——那条种子是用来校验"验收标准是否可断言"的,不是完整覆盖。
+`prd` skill 定义**做什么、不同用户场景的预期状态与验收条件**,不设计测试步骤,也不要求创建 TC。**本 skill 负责怎么测**:将验收标准与 UAT 状态展开为测试数据、步骤、方法和成套 TC。
 
-**你的活是把它补全成套**,不是重来一遍:
+承接时先查已有用例,既有 PRD 可能已经留有 TC 种子,不能假定每条需求都有:
 
-- ⛔ **种子不得被覆盖、不得被删除、不得被改写**;
-- ✅ 种子已覆盖的验收标准,在映射表里指向**那条种子的 key**,不新建重复用例;
-- ✅ 两个 skill **共用同一套查重口径**(§2)——服务端只对**字面同名**幂等(§1 保证边界),语义等同但换了说法的用例仍会各建一条,而 `TC-N` 是**租户级序列、烧掉不可回收**。
+- ⛔ **既有用例不得被覆盖、不得被删除、不得被改写**;
+- ✅ 既有用例已覆盖的验收标准,在映射表里指向**真实 key**,不新建重复用例;尚无 TC 时从零设计成套;
+- ✅ 按 §1 查重——服务端只对**字面同名**幂等,语义等同但换了说法的用例仍会各建一条,而 `TC-N` 是**租户级序列、烧掉不可回收**;
+- ✅ 产品预期状态不明确时反馈需求缺口,不在测试设计中自行决定产品行为。
 
 ## 流程总览
 
 ```
-0. 读需求         → requirement_get:PRD 正文 + 验收标准逐条编号 AC1..ACn + projectId
+0. 读需求         → PRD/UAT 预期状态 + 验收标准逐条编号 AC1..ACn + projectId
 1. 查重           → testcase_list(requirementKey) 翻页到 hasMore=false,建立现有用例清单
 2. 设计用例       → 四类覆盖 + 逐条映射(references/case-taxonomy.md)
 3. 判可断言性     → 推不出步骤的标准 → 报出,不编
@@ -45,7 +46,7 @@ description: 由需求（PRD 正文 + 验收标准）成套产出测试用例草
 
 `requirement_get(key)` 拿三样东西:
 
-- `description`(PRD 正文)——理解上下文用;
+- `description`(PRD 正文)——理解上下文及场景预期状态;用户提供 PRD 时同时读其中的 UAT 状态表;
 - `acceptanceCriteria`——**按 `\n` 切行,逐条编号 AC1…ACn**(SPMS 的验收标准就是一行一条,前端按行渲染成圆点列表);
 - `projectId`——`testcase_create` 的必填入参,**从这里取**,不要向用户要。
 
@@ -72,7 +73,7 @@ description: 由需求（PRD 正文 + 验收标准）成套产出测试用例草
 
 ## 第 3 步:判可断言性(拒绝编造)
 
-一条验收标准**推不出可执行步骤**时(没有可观测的输出、没有数值、只有形容词),产出的是**报告不是用例**:
+一条验收标准**推不出可执行步骤**时(没有可观测的输出、阈值缺口径、只有形容词),产出的是**报告不是用例**。明确的状态、枚举、相等/不变也可断言,不因缺少数字拒绝合格标准:
 
 ```
 AC3「操作体验流畅」→ ⛔ 无法成例
@@ -95,7 +96,7 @@ AC3「操作体验流畅」→ ⛔ 无法成例
 ## 红线(任何情况下不违反)
 
 - **不碰终态。** 不转 `active`、**不回填 `result`**(那是修复闭环 `testcase_update` 的活)、不删用例、不改需求状态。
-- **不重复建单。** 写入前必须查重且翻页到底;`prd` 的种子不动。
+- **不重复建单。** 写入前必须查重且翻页到底;既有用例(含历史 PRD 种子)不动。
 - **不编造用例。** 推不出步骤就报出该条无法成例。
 - **不声称未发生的写入。** 无 `write` 能力时报出 `CAPABILITY_REQUIRED` 并**明说未写入**(能力签发时定死,只能重签,改白名单无效);写入失败同理,失败几条说几条。
 - **不越出项目白名单。** `PROJECT_NOT_ALLOWED` 就停,不改去别的项目建单。
@@ -113,7 +114,7 @@ AC3「操作体验流畅」→ ⛔ 无法成例
 
 ## 汇报格式(交付时逐项给出)
 
-1. **映射表**:AC1…ACn × 用例 key(含指向 `prd` 种子的那几条)——**空格 = 覆盖有洞**;
+1. **映射表**:AC1…ACn / UAT 场景 × 用例 key(含已存在的用例)——**空格 = 覆盖有洞**;
 2. **四类计数**:正常路径 / 边界 / 权限 / 并发 各几条(每类 ≥1);
 3. **新建 key 清单**:TC-N 列表;
 4. **无法成例清单**:哪条 AC、缺什么、建议怎么改写;
@@ -125,7 +126,7 @@ AC3「操作体验流畅」→ ⛔ 无法成例
 ## 通用默认值(任何 repo 都适用)
 
 - **MCP 工具**:SPMS MCP 的 `requirement_get` / `testcase_list` / `testcase_create` / `testcase_get` / `pms_search`(挂载名以你本地 MCP 配置为准,惯例是 `xgent-pms`,即 `mcp__xgent-pms__*`)。
-- **上游**:需求由 `prd` skill 定稿并种下 1 条 TC 种子;本 skill 补全成套。**查重口径与 `prd` 共用**(§1)。
+- **上游**:需求由 `prd` skill 定清产品行为、场景预期状态与验收条件;本 skill 展开怎么测并创建成套 TC,兼容已有历史种子。
 - **不做**:执行测试、回填 `result`、改 TC 数据模型。
 
 ## 本仓库(xgent-ai-portal)默认值

package/skills/test-plan/references/case-taxonomy.md

@@ -32,11 +32,12 @@
 ```
 
 - **每条 AC 至少一个用例 key**;
-- **`prd` 种下的种子**也进表(指向它的既有 key,不新建);
+- **既有用例(含历史 PRD 种子)**也进表(指向真实 key,不新建);上游没有 TC 时从零设计;
+- PRD 的 UAT 预期状态一并映射到 AC 与用例;数据准备、执行步骤和工具在测试计划展开,不自行补定产品状态;
 - **空格 = 覆盖有洞**,交付前自己先扫一遍;
 - 覆盖率**没有自动断言**(需要语义判断),这张表就是人工核对的依据。
 
-## 3. 查重口径(与 `prd` skill 共用,不许各写一套)
+## 3. 查重口径(创建任何 TC 前使用)
 
 ```
 1. testcase_list(requirementKey='FR-x', limit=200)

package/skills/why/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: why
+description: "Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior."
+disable-model-invocation: true
+---
+
+# Why
+
+Investigate the motivation and intent behind code.
+
+Companion to the `how` skill. `how` answers what the code does and how it works. `why` answers what forces led to its shape.
+
+Each spawn below names a role line in the `pstack-models.mdc` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If the Task tool rejects a slug, use the default and say so. If it rejects the default, use the closest valid slug of the same family from its error message.
+
+## Operating Posture
+
+Operate as a **careful, cautious, and precise investigator**. Be honest about what you know vs what you're inferring. Read `references/epistemics.md` for the full confidence framework and phrasing guide. The synthesizer must follow it.
+
+## Step 1. Understand the Target and the Question
+
+Parse what the user is asking. The **target** is usually a chunk of code, a pattern, a feature, or a named design decision. The **question** is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.
+
+If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, cursor location, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.
+
+## Step 2. Establish the Code Anchor
+
+Before spawning investigators, anchor the investigation in concrete code. You need:
+
+- The relevant file path(s) and line range(s)
+- The key symbols (function names, class names, constants)
+- An initial commit list. The last few commits touching the target.
+- PR numbers from merge commits (pattern `(#1234)` in the subject line)
+
+Build this inline.
+
+```bash
+# Blame target lines for last-touch commits
+git blame -L <start>,<end> <file>
+
+# Full file history, with patches, through renames
+git log --follow -p -- <file>
+
+# Last N commits touching the file, PR numbers visible
+git log --oneline -20 -- <file>
+
+# Extract PR numbers from a commit message
+git log -1 --format=%B <commit>
+```
+
+Pull PR bodies and discussion via `gh` for any substantive commits:
+
+```bash
+gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews
+```
+
+Capture this as seed context (file paths, symbols, commits, PR numbers, linked ticket IDs). Pass it to the investigators.
+
+## Step 3. Spawn Parallel Investigators (default posture)
+
+**Default to the full parallel investigation.**
+
+### Discovery
+
+Before spawning investigators, list the available MCPs from the Cursor environment. Use the available-tools map when present. Otherwise inspect the `mcps/` directory Cursor exposes for enabled MCP servers.
+
+Map each available MCP to one evidence category:
+
+1. Source control history
+2. Issue / ticket tracker
+3. Long-form documents
+4. Real-time team chat
+5. Infrastructure observability
+6. Error / exception tracking
+7. Product analytics warehouse
+
+Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.
+
+Aim for a complete **coverage map**, not a minimal one. Document the null, don't skip the search.
+
+Launch all matching investigators in a single message so they run concurrently. Don't ask one agent to cover multiple MCPs.
+
+Subagent config (each):
+- `subagent_type`: `generalPurpose`
+- `model`: the `why investigators` line, default `grok-4.7-xhigh-fast`
+- `readonly`: `false` (agent mode). **Do not use readonly/Ask mode.** It strips MCP access, which disables MCP-backed investigators entirely. Investigators still shouldn't write anything.
+
+Each investigator gets:
+1. The base prompt from `references/investigator-prompt.md`
+2. The category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`
+3. The cross-cutting `references/sources/incident-postmortem.md` **if the target code looks defensive** (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers)
+4. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)
+5. The user's original question
+
+### Investigator roster. One per available evidence category
+
+Spawn one investigator per category that has a matching MCP. Each owns exactly one tool or MCP.
+
+Each entry names the category and the kind of "why" it uniquely surfaces. Use it to know what to expect back, how to name a gap when a category returns empty, and (only in the rare provably-irrelevant case) to justify a skip.
+
+1. **Source control investigator**. Git history, `gh` for PRs, code comments, tests. Always spawn. The only guaranteed source. Best at surfacing *implementation-time rationale captured during review*.
+
+2. **Issue / ticket tracker investigator** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at surfacing *the product or business forcing function*. Strongest when the why is external to engineering.
+
+3. **Long-form documents investigator** (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at surfacing *long-form design rationale*. Where the why is written out before it becomes code.
+
+4. **Real-time team chat investigator** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at surfacing *real-time deliberation that never reached a doc*. Especially important when the source control, ticket, and doc paper trail is thin.
+
+5. **Infrastructure observability investigator** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Infra/runtime view. Best at surfacing *infrastructure and runtime reality that motivated the code*. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).
+
+6. **Error / exception tracking investigator** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at surfacing *the specific exceptions and error trajectories that motivated defensive or corrective code*. Strongest for catch blocks, null guards, type checks, retries, and other defenses.
+
+7. **Product analytics warehouse investigator** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Product/data view. Best at surfacing *product and data reality that shaped the code*. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions.
+
+### When to skip an investigator
+
+Only skip with an **explicit, written justification** that goes in the final "Sources Consulted" section. Two valid reasons:
+
+- **No MCP is available for that category** in this environment. Flag this as a gap, not a choice. Example: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable."
+- **The source is provably irrelevant**, not just "probably irrelevant." A high bar. Example: "Error / exception tracking skipped. Target is a build-time script with no runtime code path."
+
+If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline **only after** confirming all seven available category searches would be redundant. Say so explicitly. This should be rare.
+
+## Step 4. Synthesize
+
+Spawn one synthesizer subagent:
+
+- `subagent_type`: `generalPurpose`
+- `model`: the `why synthesizer` line, default `claude-opus-5-5-max`
+- `readonly`: `false` (agent mode). The synthesizer's quality check spot-verifies citations, which can require MCP access. Readonly/Ask mode strips MCPs and defeats that.
+
+The synthesizer gets:
+1. The investigator findings, including any null results and any categories skipped with justification
+2. The code anchor from Step 2 (file paths, symbols, commit hashes, PR numbers, ticket IDs)
+3. The user's original question
+4. The epistemics framework from `references/epistemics.md`
+5. The synthesizer prompt template from `references/synthesizer-prompt.md`
+
+## Step 5. Present
+
+Take the synthesizer's output and present it to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**.
+
+## Output Format
+
+The output structure is the one in `references/synthesizer-prompt.md`: The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted, Confidence Summary. Adapt as needed, but keep the confidence separation intact, and keep Sources Consulted as one line per investigator, including the ones that returned nothing or were skipped, with the reason.
+
+After the Sources Consulted block, if the user's `why` question is a precursor to actually changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set suitable for planning the change.
+
+## Common Failure Modes to Avoid
+
+- **Recency bias**. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back.
+
+## Reference Files
+
+- `references/epistemics.md`. Confidence tiers and phrasing guide. The synthesizer must follow it.
+- `references/investigator-prompt.md`. Base prompt template for investigator subagents.
+- `references/source-playbook.md`. Index pointing at the category playbooks below.
+- `references/sources/*.md`. One self-contained example playbook per category, plus cross-cutting `incident-postmortem.md`. Give an investigator the single file that matches its category and adapt it to the available MCP.
+- `references/synthesizer-prompt.md`. Prompt template for the synthesizer subagent, including the output format.