Skill: bustes01/requirement-comprehension-engine (version 1.2.0)

--- name: requirement-comprehension-engine description: > Advanced requirement comprehension and skill orchestration engine. Analyzes complex/multi-step user requests, determines which skills to invoke and in what order, builds task decomposition trees. Delegates memory management to complex-memory-manager and self-iteration to self-iteration-engine for cross-skill consistency. Triggers: multi-intent requests, ambiguous instructions, requests spanning multiple skill domains, structured requirement analysis. version: 1.2.0 metadata: openclaw: emoji: "🧠" homepage: https://clawhub.ai/BusTes01/requirement-comprehension-engine models: - gpt-4 - deepseek-v4-flash - gemini-2.0-flash - claude-4-opus requires: skills: - complex-memory-manager - self-iteration-engine --- # 🧠 Requirement Comprehension Engine A metacognitive skill that equips agents with structured requirement analysis, skill selection & orchestration. Delegates memory management to **complex-memory-manager** and self-iteration to **self-iteration-engine** for cross-skill consistency. ## Core Capabilities ### 1. Requirement Analysis & Decomposition When the agent receives a complex or ambiguous request: **Step 1: Intent Classification** - Parse incoming message for explicit intent signals (verbs, domain keywords, output expectations) - Classify into: Direct Action / Information Request / Creative Generation / Analysis & Insight / Meta-Request / Multi-Step Workflow - If ambiguous, flag as **Under-Specified** and use elicitation templates **Step 2: Structured Decomposition** Break the request into a tree: ``` Original Request ├── Intent A (primary) │ ├── Sub-goal A1 → skill/action candidate │ ├── Sub-goal A2 → skill/action candidate │ └── Dependency check ├── Intent B (secondary) │ └── ... └── Cross-cutting concerns (privacy, cost, performance) ``` **Step 3: Skill Mapping** For each sub-goal, select the best matching skill: - Check `name` + `description` of all available skills (always in context as metadata) - Rank matching skills by semantic relevance - If no match → fallback to general knowledge - If multiple → pick the most specific or orchestrate ### 2. Skill Orchestration Logic | Situation | Action | |-----------|--------| | Single clear intent, single skill | Direct invocation | | Multiple independent intents | Parallel execution | | Multi-step pipeline (output A → input B) | Sequential orchestration with handoff | | Full autonomy requested | Analyze, decide, execute, explain | | Conflicting skill capabilities | Prefer skill with more specific description | **Handoff Protocol:** ``` [ComprehensionEngine] Handoff: Skill-A → Skill-B Context: {user's original intent excerpt} Skill-A result: {summary} Skill-B requirement: {what Skill-B needs to continue} ``` ### 3. Requirement Elicitation Templates When a request is **under-specified**: **Pattern A: Missing Output Format** > "I need to confirm the output format — do you want a daily report, summary, table, chart, code, or something else?" **Pattern B: Missing Scope** > "This request seems broad. Could you narrow down the focus? For example: Option A, Option B, or Option C?" **Pattern C: Ambiguous Intent** > "I see two possible directions: do you want me to analyze existing data, or go out and collect new data?" **Pattern D: Multi-Step Confirmation** > "I plan to do this in three steps: ① collect latest market data ② analyze trends ③ generate a visualization. Does that work?" ### 4. Delegation to Shared Components | Function | Delegated To | How | |----------|-------------|-----| | Persistent memory (T1/T2/T3) | `complex-memory-manager` | Use its encrypt/decrypt, storage conventions, and cleanup protocols | | Usage logging & performance tracking | `self-iteration-engine` | Use its log format, review cycles, and update matrix | | Self-iteration decisions | `self-iteration-engine` | Check triggers, run update decision matrix | | New skill creation proposals | `self-iteration-engine` | Use its proposal template | ## Quick Reference: Skill Selection Flow ``` User speaks ↓ Parse & Classify Intent ↓ Is it clear? ──No──→ Use Elicitation Templates │ ↓ Yes←── User clarifies ↓ Decompose into sub-goals ↓ For each sub-goal: ├── Match skill by name+description ├── If match: check last-review-date; if >30d → quick scan SKILL.md ├── If no match: fallback to general knowledge └── If multi-skill: orchestrate (parallel or sequential) ↓ Execute & Deliver ↓ Log outcome → Delegate to self-iteration-engine ↓ [Periodic] Delegate review to self-iteration-engine + memory cleanup to complex-memory-manager ``` ## Dependency Check Before each orchestration run: 1. Verify `complex-memory-manager` metadata description is in context 2. Verify `self-iteration-engine` metadata description is in context 3. If either is missing, they may not be installed — fallback to built-in behavior --- # 🧠 需求理解引擎 一个元认知技能，赋予Agent结构化的需求分析、技能选择与编排能力。将持久化记忆委托给 **complex-memory-manager**，将自迭代委托给 **self-iteration-engine**，实现跨技能一致性。 ## 核心能力 ### 1. 需求分析与分解 当Agent收到复杂或模糊请求时： **第一步：意图分类** - 解析输入信息的意图信号 - 分类：直接操作 / 信息查询 / 创意生成 / 分析洞察 / 元请求 / 多步工作流 - 若模棱两可，标记为"信息不足"并使用澄清模板 **第二步：结构化分解** 将请求拆解为树状结构 **第三步：Skill映射** 为每个子目标选择最佳匹配skill ### 2. 技能编排逻辑 | 场景 | 行动 | |------|------| | 单一明确意图 | 直接调用 | | 多个独立意图 | 并行执行 | | 多步流水线 | 顺序编排+交接记录 | | 用户要求自主 | 分析→决策→执行→解释 | | 技能冲突 | 选择描述更具体的 | ### 3. 需求澄清模板 在请求信息不足时使用四种追问模式（详见英文版）。 ### 4. 委托给共享组件 | 功能 | 委托给 | 方式 | |------|--------|------| | 持久化记忆(T1/T2/T3) | `complex-memory-manager` | 使用其加密/解密、存储规范、清理协议 | | 使用日志与性能追踪 | `self-iteration-engine` | 使用其日志格式、审查周期、更新矩阵 | | 自迭代决策 | `self-iteration-engine` | 检查触发条件、运行更新决策矩阵 | | 新技能创建建议 | `self-iteration-engine` | 使用其提案模板 | ## 依赖检查 每次编排运行前： 1. 检查 `complex-memory-manager` 的 metadata 是否在上下文中 2. 检查 `self-iteration-engine` 的 metadata 是否在上下文中 3. 若缺失，可能未安装——回退到内置基础行为 ## 参考文件 - `references/orchestration-patterns.md` — 高级多skill编排示例

path: references/memory-management.md
content: # Memory Management Reference

## Tiered Memory System

### Tier 1: Public / Visible (No encryption)

Store in `memory/tier1-public/` or directly in daily notes.

**Content allowed:**
- Skill usage statistics
- Generic workflow patterns
- Common user request categories
- Aggregated/statistical behavioral data (no personal identification)

**Example:**
```json
{
  "skill_stats": {
    "morning-news-daily": { "calls": 47, "success_rate": 0.96 },
    "text-to-image-free": { "calls": 23, "success_rate": 0.91 }
  },
  "common_flows": [
    { "trigger": "morning greeting", "skills": ["morning-news-daily"] },
    { "trigger": "image creation", "skills": ["text-to-image-free"] }
  ]
}
```

### Tier 2: Internal / Agent-Only (Base64 + XOR)

Store in `memory/tier2-internal/` with lightweight encryption. The key is derived from the skill name and date — only the agent knows how to reconstruct it without storing the key.

**Encryption method:**
```python
def xor_encrypt(text: str, key: str) -> str:
    import base64
    result = bytes([ord(c) ^ ord(key[i % len(key)]) for i, c in enumerate(text)])
    return base64.b64encode(result).decode()

def xor_decrypt(encoded: str, key: str) -> str:
    import base64
    raw = base64.b64decode(encoded)
    return ''.join(chr(b ^ ord(key[i % len(key)])) for i, b in enumerate(raw))

# Key derivation: sha256(skill_name + date[:7])[:8]
# Example: key for "req-comprehend" on 2026-05 = "a3f1b2c4"
```

**Memory entry format:**
```markdown
---
tier: internal
key_hint: req-comprehend-2026-05
created: 2026-05-19
expires: 2026-06-19
---

## Encrypted Preference
> a0VmcEdWYQpnUgpmUQp... (base64 encoded, XOR encrypted)

## Decryption Note
XOR with key derived from sha256("req-comprehend-2026-05")[:8]
Purpose: Stores user's preference for one specific output format choice
```

### Tier 3: Private / External (Not stored in skill memory)

**Rule: NEVER store the following in skill memory files:**
- API keys / tokens
- Passwords / secrets
- Email addresses
- Phone numbers
- Home/work addresses
- Government IDs
- Financial account numbers
- Biometric data

These belong in environment variables, secret managers (1Password, Bitwarden), or encrypted system keychains.

## Memory Cleanup Protocol

Run every 7 days:

1. List all files in `memory/tier1-public/`, `memory/tier2-internal/`
2. Check `created` dates — delete if >30 days old (unless marked `persist: true`)
3. Check if any Tier 2 entries contain PII — if found, immediately delete
4. Compact: merge duplicate entries, remove outdated workflow patterns
5. Archive: move old entries to `memory/archive/YYYY-MM/`

## Privacy Audit Checklist

- [ ] No real names, usernames, or handles in memory
- [ ] No API keys or tokens in any visible file
- [ ] No local filesystem paths containing /home/<username>
- [ ] No fixed schedules that reveal personal routine (use relative: "early morning" instead of "6am")
- [ ] No geographic specifics beyond city level
- [ ] All Tier 2 entries have expiry dates
- [ ] Tier 3 data never touches skill memory


path: references/orchestration-patterns.md
content: # Orchestration Patterns Reference

## Multi-Skill Orchestration Recipes

### Pattern 1: Sequential Pipeline

**When:** Output of Skill A is input for Skill B.

```
User: "Generate an image of today's stock market trend"
→ Skill A: astock-daily-brief (fetch market data → output: structured text)
→ Skill B: text-to-image-free (take market summary → generate visualization)
→ Deliver final image
```

**Handoff template:**
```markdown
[Orchestration] Handoff: astock-daily-brief → text-to-image-free
Context: User wants visual representation of market data
Skill-A result: {summary text of today's A-share market}
Skill-B instruction: "Create an infographic-style image based on this market data summary"
```

### Pattern 2: Parallel Fan-Out

**When:** Multiple independent tasks from one request.

```
User: "Give me today's morning news and generate an image of a cyberpunk city"
→ Skill A: morning-news-daily (fetch news)
→ Skill B: text-to-image-free (generate image)
   (Both independent — can run simultaneously)
→ Merge and deliver as a single response
```

### Pattern 3: Conditional Orchestration

**When:** Task B only runs if Task A meets certain criteria.

```
User: "Check the market. If it's down significantly, generate a worried face image"
→ Skill A: astock-daily-brief (check market)
→ Decision point: is market down >2%?
   ├── Yes → Skill B: text-to-image-free ("worried investor face")
   └── No → Skip B, just deliver market summary
```

### Pattern 4: Recursive Decomposition

**When:** A request requires a multi-level breakdown.

```
User: "Help me analyze this investment thesis"
→ Root: Analyze investment thesis
  ├── 1. Gather data (astock-daily-brief)
  ├── 2. Identify risks (general reasoning)
  ├── 3. Generate report structure (general knowledge)
  └── 4. Create visualization (text-to-image-free)
→ All sub-tasks complete → compose final deliverable
```

## Skill Conflict Resolution

| Conflict | Resolution |
|----------|------------|
| Two skills match same description | Pick the one with higher success_rate in usage log |
| Skill suggests something another skill contradicts | Flag both to user with reasoning |
| No skill matches but request is complex | Decompose into primitives, solve each with general knowledge |
| Skill requires API key that's missing | Gracefully fallback, inform user of capability gap |

## Performance Fallback Chain

When a skill fails, the orchestration layer should attempt fallbacks:

1. First attempt: primary skill
2. First fallback: same task with general knowledge (no skill)
3. Second fallback: simplified version of the request
4. Last resort: inform user with partial results and next steps

## Logging Handoffs

Each orchestrated flow should produce a lightweight execution log:

```json
{
  "execution_id": "exec_20260519_001",
  "timestamp": "2026-05-19T06:00:00+08:00",
  "trigger": "daily morning routine",
  "flow": "sequential",
  "steps": [
    { "skill": "morning-news-daily", "status": "success", "duration_s": 12 },
    { "skill": "text-to-image-free", "status": "success", "duration_s": 45 }
  ],
  "user_facing": true,
  "result_delivered": true
}
```

Maintain last 100 execution logs; older ones are rotated out.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal:  | SkillSpector: clean (LOW)