xtep-workspace 1.10.10

package/plugin/skills/diagnosing-issues/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: diagnosing-issues
+description: Use when debugging errors or investigating performance issues. Traces root cause of problems, applies to logic errors and performance bottlenecks.
+---
+
+# Diagnosing Issues
+
+## Announcement (MANDATORY)
+
+Before executing this skill, you MUST announce to the user:
+
+「我将使用 **问题诊断** 技能来追踪问题根因、分析逻辑错误和性能瓶颈。」
+
+This creates a commitment checkpoint. Proceed only after announcing.
+
+## Core Thinking
+
+**Trace** - Follow the causal chain to find root cause.
+
+**Recording**: Conversation output is invisible to users. You MUST record to workspace node. Standard: "If context is wiped now, can you recall discussion details from conclusion alone?"
+
+**Progressive Recording**: Diagnosis can be long. After each hypothesis test, immediately `log_append` the result. Don't lose valuable debugging insights.
+
+## Applicable Scenarios
+
+- **Debug**: Diagnose logic errors (why error occurs)
+- **Optimize**: Diagnose performance bottlenecks (why slow)
+
+## SOP
+
+### 1. Reproduce/Locate
+
+#### Debug Scenario
+- Collect error info (message, stack trace, error code)
+- Confirm reproduction steps (always/sometimes, trigger conditions)
+- **Locate code line**: Find code position from error stack
+
+#### Optimize Scenario
+- Collect performance data (response time, throughput, resource usage)
+- Identify slow operations (API, DB query, compute-intensive tasks)
+- **Locate bottleneck**: Find slowest function call or SQL
+
+### 2. Causal Chain Analysis
+
+Build call chain using AST analysis or code tracing:
+
+```
+Entry function
+  ↓ calls
+Intermediate function A
+  ↓ calls
+Intermediate function B
+  ↓ calls
+Problem function ← Located point
+  ↓ trace back
+Data source/Logic flaw ← Root cause
+```
+
+### 3. Hypothesis Testing
+
+**Construct hypotheses**:
+- Based on error type, list possible causes
+- Based on performance data, identify potential bottlenecks
+- Priority: Most likely causes first
+
+**Verify hypotheses**:
+- Add logging to verify assumptions
+- Modify code to test hypotheses
+- Use debugger to trace execution
+
+**⚠️ Checkpoint**: After each hypothesis test, `log_append` the result (confirmed/rejected + evidence).
+
+### 4. Root Cause Confirmation
+
+**Confirmation criteria**:
+- Can explain all observed symptoms
+- Can reproduce consistently
+- Modification can fix the issue
+
+**Output diagnosis report**:
+- Reproduction path
+- Causal chain analysis
+- Root cause location
+- Fix recommendation
+
+### 5. Record to Workspace (MANDATORY)
+
+After diagnosis, MUST record to workspace node:
+
+**Recording locations**:
+| Content | Location | Tool |
+|---------|----------|------|
+| Key conclusions (brief) | conclusion | node_update |
+| Hypotheses, investigation, root cause | notes | node_update |
+| Full trace log (>200 lines) | MEMO | memo_create + node_reference |
+
+**NEVER hardcode MEMO IDs** in text like "见 MEMO#xxx". Use `node_reference` to link.
+
+**Reference rules** (diagnosis tasks MUST include):
+- Root cause location: `file:line` format (CRITICAL)
+- Error stack trace: key frames with file:line
+- Causal chain: each node with file reference
+- Core principle: precise location enables verification and fix
+
+**Conclusion template** (brief):
+```
+[问题描述] + [根因位置] + [修复建议]
+```
+
+**Notes template** (detailed):
+```
+**Issue**: [error/symptom]
+**Reproduction**: [steps]
+**Investigation**:
+- Hypothesis 1: [tested] → [result]
+- Hypothesis 2: [tested] → [result]
+**Causal Chain**: Entry → A → B → Problem
+**Root Cause**: [file:line] - [explanation]
+**Fix**: [recommendation]
+```
+
+**Output**: node_update called with conclusion + notes
+
+### 6. Present to User (MANDATORY)
+
+After recording, MUST present diagnosis to user:
+
+1. **Output summary**: Show root cause and fix recommendation using Output Template
+2. **Wait for confirmation**: Ask user if diagnosis is correct and fix approach is acceptable
+3. **NEVER proceed directly**: Do NOT start fixing without user confirmation
+
+**Output**: Diagnosis presented, user confirmation received
+
+## Checklist
+
+### Debug
+- [ ] Error message collected
+- [ ] Stack trace analyzed
+- [ ] Reproduction steps confirmed
+- [ ] Root cause code located
+- [ ] Fix verified
+
+### Optimize
+- [ ] Performance baseline established
+- [ ] Bottleneck identified
+- [ ] Causal chain traced
+- [ ] Optimization point confirmed
+
+### Recording (MANDATORY)
+- [ ] **Conclusion written**: Brief summary in node conclusion
+- [ ] **Notes written**: Investigation, root cause in node notes
+- [ ] **MEMO linked**: Long content in MEMO, linked via node_reference (not hardcoded ID)
+- [ ] **Wipe test**: If context wiped now, can recall details from recorded content?
+
+### Long Content Protection
+- [ ] **Progressive recording**: Used `log_append` after each hypothesis test
+- [ ] **Root cause referenced**: Location has precise `file:line`
+- [ ] **Causal chain referenced**: Each node has file reference
+
+## Output Template
+
+```markdown
+### Diagnosis Summary
+**Issue type**: [Error/Performance]
+**Root cause**: [One sentence description]
+**Location**: [file:line]
+
+### Reproduction Path
+1. [Step 1]
+2. [Step 2]
+3. [Symptom appears]
+
+### Causal Chain
+[Entry] → [Function A] → [Function B] → [Problem point]
+
+### Root Cause Analysis
+[Detailed explanation of why this causes the issue]
+
+### Fix Recommendation
+[Specific fix approach]
+```
+
+## Red Flags
+
+1. **Fix symptoms not cause** - Patch visible error without finding root cause
+2. **Skip reproduction** - Assume issue without consistent reproduction
+3. **Single hypothesis** - Lock on first guess without exploring alternatives
+4. **No verification** - Claim fix without testing
+5. **Silent execution** - Complete diagnosis, then immediately start fixing without showing user
+6. **Vague location** - "The problem is in module X" without `file:line`
+7. **Lost hypotheses** - Test multiple hypotheses without logging results
+
+## Mandatory Rules
+
+1. **MUST reproduce first** - NEVER attempt fix without consistent reproduction
+2. **MUST find root cause** - Fixing symptoms without root cause leads to recurrence
+3. **MUST test one hypothesis at a time** - Multiple simultaneous changes = no learning
+4. **MUST verify the fix** - "Should work" is not verification
+5. **NEVER blame user/environment** - Reproduce in user's conditions first
+6. **MUST present before proceed** - After diagnosis, NEVER start fixing directly. Present diagnosis, wait for user confirmation
+
+## Anti-Patterns
+
+| Pattern | Wrong | Right |
+|---------|-------|-------|
+| **Guess and fix** | Try random fixes hoping one works | Systematic hypothesis testing |
+| **Blame user** | "Works on my machine" | Reproduce in user environment |
+| **Ignore edge cases** | Only test happy path | Test error scenarios too |
+| **Incomplete trace** | Stop at first error | Trace to true root cause |
+
+## Common Rationalizations
+
+| Excuse | Why Wrong | Correct Action |
+|--------|-----------|----------------|
+| "The fix is obvious" | Obvious fixes often miss root cause | Trace causal chain first |
+| "It only happens sometimes" | Intermittent bugs need systematic reproduction | Find trigger conditions |
+| "Adding a retry will fix it" | Retry masks the real problem | Find why it fails, then fix |
+| "Let me try this quick fix first" | Quick fixes compound into technical debt | Diagnose properly, fix once |
+| "I've seen this before" | Similar symptoms may have different causes | Verify with evidence, don't assume |

package/plugin/skills/discovering-context/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: discovering-context
+description: Use when starting work on unfamiliar codebase or module. Investigates project context, understands existing state and dependencies.
+---
+
+# Discovering Context
+
+## Announcement (MANDATORY)
+
+Before executing this skill, you MUST announce to the user:
+
+「我将使用 **上下文探索** 技能来调查项目背景、理解现有状态和依赖关系。」
+
+This creates a commitment checkpoint. Proceed only after announcing.
+
+## Core Thinking
+
+**Investigate** - Build cognitive model through systematic information collection.
+
+**Recording**: Conversation output is invisible to users. You MUST record to workspace node. Standard: "If context is wiped now, can you recall discussion details from conclusion alone?"
+
+**Progressive Recording**: For long explorations, NEVER wait until the end to record. After each major discovery, immediately `log_append` key findings. Context may be lost at any time.
+
+## Typical Actions
+
+- **Explore codebase**: Use Task tool with `subagent_type=Explore` for complex exploration
+- Search code: Use Grep/Glob for targeted keyword search
+- Read docs: Scan README, design docs, API docs
+- Trace dependencies: Analyze module relationships, data flow
+
+## When to Use Explore Agent
+
+**PREFER Explore agent** for open-ended exploration:
+- "Where is X implemented?"
+- "How does the codebase handle Y?"
+- "Find all files related to Z"
+
+**Use Grep/Glob directly** for targeted search:
+- Specific class/function name
+- Known file pattern
+- Simple keyword lookup
+
+## Strategy Selection
+
+### Macro (Document-first)
+- **Use when**: New project, architecture design, requirements analysis
+- **Sources**: README, docs/, architecture diagrams, CHANGELOG
+- **Goal**: Understand overall design, business logic, module structure
+
+### Micro (Code-first)
+- **Use when**: Bug fixing, feature extension, code refactoring
+- **Sources**: Source code, type definitions, test cases
+- **Goal**: Understand implementation, data flow, call chains
+
+**Decision rules**:
+- Architecture design → Macro
+- Specific implementation → Micro
+- New domain → Macro first, then Micro deep dive
+- Clear local scope → Micro first
+
+## SOP
+
+### 1. Entry Point Location
+
+**Macro entries**:
+1. Project root README.md
+2. docs/ directory
+3. package.json / pyproject.toml
+4. CHANGELOG.md
+
+**Micro entries**:
+1. Grep for keywords
+2. src/index.* or main.*
+3. Type definitions (src/types/)
+4. Test files
+
+### 2. Dependency Analysis
+
+**Module dependencies**:
+- Analyze import/export relationships
+- Identify core vs auxiliary modules
+- Build mental dependency graph
+
+**External dependencies**:
+- Extract production vs dev dependencies
+- Identify core libraries and their purpose
+- Note version constraints
+
+**Data dependencies**:
+- Identify shared data structures
+- Trace data flow paths
+- Understand state management
+
+**⚠️ Checkpoint**: After completing dependency analysis, `log_append` key module relationships before proceeding.
+
+### 3. Data Flow Tracing
+
+**For functional tasks**:
+- Start from user input
+- Track through modules
+- Identify transformations
+- Locate final output
+
+**For system tasks**:
+- Identify core data structures
+- Understand persistence
+- Analyze sync mechanisms
+- Trace config propagation
+
+**Visualization rules**:
+- Code investigation: **MUST** use mermaid sequenceDiagram
+- Architecture overview: flowchart or simple `A → B → C`
+
+**⚠️ Checkpoint**: After tracing data flow, `log_append` the flow diagram before proceeding.
+
+### 4. Output Knowledge Snapshot
+
+Structure findings using output template.
+
+### 5. Record to Workspace (MANDATORY)
+
+After exploration, MUST record to workspace node:
+
+**Recording locations**:
+| Content | Location | Tool |
+|---------|----------|------|
+| Key conclusions (brief) | conclusion | node_update |
+| Scope, key files, dependencies | notes | node_update |
+| Full knowledge snapshot (>200 lines) | MEMO | memo_create + node_reference |
+
+**NEVER hardcode MEMO IDs** in text like "见 MEMO#xxx". Use `node_reference` to link.
+
+**Reference rules** (investigation tasks MUST include):
+- Key files: `file:line` format
+- Entry points: exact location
+- Dependencies: module names with paths
+- Core principle: references enable traceability, not bureaucracy
+
+**Conclusion template** (brief):
+```
+[探索范围] + [关键发现] + [待确认项]
+```
+
+**Notes template** (detailed):
+```
+**Strategy**: Macro/Micro
+**Scanned**: [directories/files]
+**Key Files**:
+- Entry: file:line
+- Types: file
+**Dependencies**: [list]
+**Data Flow**: [brief]
+**Uncertainties**: [items]
+```
+
+**Output**: node_update called with conclusion + notes
+
+### 6. Present to User (MANDATORY)
+
+After recording, MUST present findings to user:
+
+1. **Output summary**: Show key findings using Output Template
+2. **Wait for confirmation**: Ask user if findings are correct/complete
+3. **NEVER proceed directly**: Do NOT start execution without user acknowledgment
+
+**Output**: Summary presented, user confirmation received
+
+## Information Source Priority
+
+1. **Codebase**: Most reliable, implementation is truth
+2. **Docs**: Official documentation, design docs
+3. **User**: Confirm requirements and expectations
+4. **Public Knowledge**: Tech docs, best practices
+
+**Rules**:
+- Code conflicts with docs → Trust code
+- Docs missing → Check code first, then ask user
+- Uncertain → Mark as "to be confirmed"
+
+## Output Template
+
+```markdown
+### Discovery Summary
+**Scope**: [What was explored]
+**Strategy**: Macro / Micro
+
+### Key Files
+| Role | File | Description |
+|------|------|-------------|
+| Entry | file:line | [description] |
+| Types | file | [description] |
+| Config | file | [description] |
+
+### Dependencies
+- **Internal**: [module relationships]
+- **External**: [key libraries]
+
+### Data Flow
+[Visualize with mermaid sequenceDiagram or flowchart]
+
+```mermaid
+sequenceDiagram
+    participant A
+    participant B
+    A->>B: [action]
+    B-->>A: [response]
+```
+
+### Findings
+- [Key finding 1]
+- [Key finding 2]
+
+### Uncertainties
+- [ ] [Item needing confirmation]
+```
+
+## Checklist
+
+### Macro
+- [ ] Project overview understood
+- [ ] Tech stack identified
+- [ ] Module structure mapped
+- [ ] Data flow documented
+- [ ] Config/deployment understood
+
+### Micro
+- [ ] Entry point located
+- [ ] Key functions identified
+- [ ] Type definitions understood
+- [ ] Dependencies traced
+- [ ] Data flow traced
+- [ ] Error handling identified
+
+### Recording (MANDATORY)
+- [ ] **Conclusion written**: Brief summary in node conclusion
+- [ ] **Notes written**: Scope, key files, dependencies in node notes
+- [ ] **MEMO linked**: Long content in MEMO, linked via node_reference (not hardcoded ID)
+- [ ] **Wipe test**: If context wiped now, can recall details from recorded content?
+
+### Long Content Protection
+- [ ] **Progressive recording**: Used `log_append` after each major discovery
+- [ ] **References complete**: All key files have `file:line` references
+- [ ] **Checkpoints hit**: Logged after dependency analysis and data flow tracing
+- [ ] **Output Template complete**: Every section filled, no placeholders left
+
+## Red Flags
+
+1. **Skip exploration** - Start implementing without reading existing code
+2. **Assume existence** - Assume feature exists without verification
+3. **Ignore dependencies** - Don't check module relationships
+4. **Wrong strategy** - Use docs when should use code, or vice versa
+5. **Silent execution** - Complete exploration, then immediately start implementing without showing user
+6. **Batch recording** - Explore for 30+ minutes without any `log_append`
+7. **Missing references** - Conclusions without `file:line` references
+8. **Skip checkpoints** - Complete long exploration without intermediate logs
+
+## Mandatory Rules
+
+1. **MUST explore before implementing** - NEVER code without understanding existing patterns
+2. **MUST verify existence** - NEVER assume feature/module exists, check code
+3. **MUST trust code over docs** - When docs conflict with code, code is truth
+4. **MUST record findings** - Exploration without documentation is wasted effort
+5. **MUST scope exploration** - Explore what's needed, not the entire project
+6. **MUST present before proceed** - After exploration, NEVER start execution directly. Present findings, wait for user confirmation
+
+## Anti-Patterns
+
+| Pattern | Wrong | Right |
+|---------|-------|-------|
+| **Blind start** | Code without reading existing code | Grep/Glob to locate relevant code first |
+| **Over-explore** | Read entire project | Scope to task needs |
+| **Trust docs over code** | Docs say X exists, believe it | Code is truth, docs may be stale |
+| **No record** | Explore and forget | Output structured knowledge snapshot |
+
+## Common Rationalizations
+
+| Excuse | Why Wrong | Correct Action |
+|--------|-----------|----------------|
+| "I'll figure it out as I code" | Leads to wrong assumptions and rework | Explore first, code informed |
+| "The docs explain everything" | Docs are often outdated or incomplete | Verify against actual code |
+| "I've worked on similar projects" | This project may have different patterns | Check this specific codebase |
+| "Exploration takes too long" | Coding without context takes longer | 20 min exploration saves hours |
+| "I'll just ask if I get stuck" | User may not know implementation details | Code is the authoritative source |