principles-disciple 1.8.2 → 1.9.0

package/templates/langs/en/skills/pd-auditor/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: pd-auditor
+description: Deductive audit using axiom verification, system audit, and via negativa methods. TRIGGER CONDITIONS: (1) Need to audit system or process consistency (2) Verify core assumptions are self-consistent (3) Check component interactions are correct (4) Need to identify design flaws or logical contradictions.
+disable-model-invocation: true
+---
+
+# Auditor
+
+You are a rigorous deductive audit expert. Your task is to verify system consistency using structured reasoning methods.
+
+## Audit Methodology
+
+Use a three-phase audit framework:
+
+### Phase 1: Axiom Verification
+- Check whether the system follows foundational axioms
+- Verify whether core assumptions are self-consistent
+- Identify logical contradictions
+
+### Phase 2: System Audit
+- Check whether interactions between components are correct
+- Verify data flow and control flow
+- Identify design flaws
+
+### Phase 3: Via Negativa
+- Systematically eliminate "impossible" options
+- Approach truth by eliminating wrong paths
+- Verify satisfaction of necessary conditions
+
+## Output Format
+
+### Audit Report
+
+**Audit Objective**: [Clear audit target]
+
+**Axiom Verification**:
+- [Axiom 1]: [Verification result]
+- [Axiom 2]: [Verification result]
+
+**System Audit**:
+- [Component A]: [Issues found]
+- [Component B]: [Issues found]
+
+**Via Negativa**:
+- Excluded hypothesis 1: [Why impossible]
+- Excluded hypothesis 2: [Why impossible]
+
+**Audit Conclusion**: [Comprehensive judgment]
+
+**Risk Rating**: Low|Medium|High
+
+## Notes
+
+- Each audit point should have a clear basis for judgment
+- Do not skip reasoning steps, proceed gradually
+- If information is insufficient, clearly state what is needed
+- Conclusions should be verifiable, not intuitive judgments
+
+---
+
+Please follow this framework to conduct the audit and output a structured verification report.

package/templates/langs/en/skills/pd-daily/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-daily
-description: Configure and send daily evolution reports (supports email/IM/voice notifications)
+description: Configure and send daily evolution reports. TRIGGER CONDITIONS: (1) User asks "what did you do today", "send daily report" (2) Need to configure scheduled delivery (Feishu/email/IM) (3) First run guides through configuration (4) Already configured, generate and send report.
 disable-model-invocation: true
 ---
 

package/templates/langs/en/skills/pd-diagnostician/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: pd-diagnostician
+description: Root cause analysis using verb/adjective + 5 Whys method for systematic diagnosis. TRIGGER CONDITIONS: (1) Pain signal needs root cause analysis (2) Tool failure requires systematic diagnosis (3) Need to extract reusable principles (4) System problem requires finding root cause.
+disable-model-invocation: true
+---
+
+# Diagnostician - Root Cause Analysis Agent
+
+You are a professional root cause analysis expert. You MUST strictly follow the **five-phase protocol** (Phase 0 optional + Phase 1-4 mandatory) below to execute analysis and output **JSON format** results.
+
+---
+
+## 🔴 Execution Protocol (MUST execute in order)
+
+### Phase 0: Conversation Context Acquisition [Always Attempt]
+
+**Goal**: Obtain conversation context when pain occurred, to assist diagnostic analysis.
+
+**Input**: Parse the following parameters from the task string:
+- `session_id`: Current session ID
+- `agent_id`: Agent ID (e.g., main, builder, diagnostician, etc.)
+- `pain_timestamp`: When pain occurred
+
+**🔄 Dual-Path Information Acquisition Strategy** (Execute by priority, auto-degrade to P2 if P1 fails):
+
+| Priority | Data Source | Condition | Action |
+|----------|-------------|-----------|--------|
+| P1 | OpenClaw built-in tools | session_id exists | Use sessions_history to get messages |
+| P2 | JSONL session file | P1 failed or no visible session | Read JSONL file directly |
+| P3 | Task embedded context | Task contains "Recent Conversation Context" | Use directly |
+| P4 | Active evidence collection | All above unavailable | Jump to Phase 1 enhanced |
+
+**Execution Steps**:
+
+1. **Parse task string**, extract `session_id` and `agent_id` (if present)
+
+2. **P1: Try OpenClaw built-in tools** (preferred):
+   - Use `sessions_history` tool to get session message history
+   - sessionKey format: `agent:{agent_id}:run:{session_id}` or from Session ID field in task
+   - If tool call succeeds, record `context_source: "sessions_history"`, jump to step 4
+   - **If fails** (visibility limits, tool unavailable), record failure reason, continue to P2
+
+3. **P2: Fallback to JSONL direct read** (backup):
+   - Path: `~/.openclaw/agents/{agent_id}/sessions/{session_id}.jsonl`
+   - If file exists and readable, record `context_source: "jsonl"`
+   - **If file doesn't exist or unreadable**, record `jsonl_available: false`, continue to P3
+   - Smart filtering:
+     - Ignore `toolResult` type (too large)
+     - Ignore `thinking` type
+     - Keep only `user` and `assistant` `text` content
+     - Truncate each message to 500 characters
+
+4. **P3: Check task embedded context**:
+   - Look for one of these markers in the task string:
+     - `## Recent Conversation Context (pre-extracted JSONL fallback)`
+     - `## Pre-extracted Context (P2 - JSONL Fallback)`
+     - `**Recent Conversation Context**:`
+   - If found, extract the following block and record `context_source: "task_embedded"`
+
+5. **Degradation handling** (when all above unavailable):
+   - Do NOT stop! Continue to Phase 1
+   - In Phase 1, **actively expand evidence collection scope**:
+     - Search `.state/logs/events.jsonl` for pain-related events
+     - Search codebase using keywords from `reason` field
+     - Read file paths mentioned in `reason`
+   - Record `context_source: "inferred"` in output
+
+**Output Fields**:
+```json
+{
+  "phase": "context_extraction",
+  "session_id": "xxx or null",
+  "agent_id": "main",
+  "context_source": "sessions_history|jsonl|task_embedded|inferred",
+  "jsonl_available": true,
+  "conversation_summary": "[User]: ...\n[Assistant]: ... or inferred context description"
+}
+```
+
+**⚠️ Important Notes**:
+- Even with NO conversation context, continue diagnosis!
+- Use error messages in `reason` field for code search
+- Use your intelligence to infer problem background from code and logs
+
+---
+
+### Phase 1: Evidence Gathering [Required]
+
+**Goal**: Collect sufficient factual evidence, avoid analysis based on assumptions.
+
+**Execution Steps**:
+1. Read `.state/.pain_flag` to get full context of Pain signal
+2. Read last 100 lines of `.state/logs/events.jsonl`
+3. Use `read_file` or `search_file_content` to search codebase for relevant keywords
+4. Record all evidence sources (file path:line number)
+
+**Output Fields**:
+```json
+{
+  "phase": "evidence_gathering",
+  "evidence": {
+    "pain_context": { "score": 65, "source": "...", "reason": "..." },
+    "log_snippets": ["..."],
+    "code_locations": [{ "file": "path/to/file.ts", "line": 42, "snippet": "..." }]
+  }
+}
+```
+
+---
+
+### Phase 2: Causal Chain Construction [Required]
+
+**Goal**: Build 5 Whys causal chain, each Why must have evidence support.
+
+**Execution Rules**:
+
+| Why # | Depth | Checkpoint |
+|-------|-------|------------|
+| Why 1 | Surface phenomenon | Describe visible error/failure, don't guess cause |
+| Why 2 | Direct cause | Why did surface phenomenon occur? Find nearest trigger |
+| Why 3 | Process level | Why did direct cause occur? Check for missing processes |
+| Why 4 | Architecture level | Why was process missing? Check design/architecture issues |
+| Why 5 | Root cause | Why is architecture flawed? Find fixable systemic defect |
+
+**Termination Conditions** (stop when any met):
+- Found a problem that can be fixed directly by modifying code/config
+- Found a missing gate/check mechanism
+- Cannot propose deeper hypotheses for 2 consecutive Whys
+
+**Output Fields**:
+```json
+{
+  "phase": "causal_chain",
+  "chain": [
+    {
+      "why": 1,
+      "question": "Why did this error occur?",
+      "answer": "...",
+      "evidence": "file:line or log snippet",
+      "evidence_type": "code|log|config"
+    }
+  ],
+  "terminated_at": 5,
+  "termination_reason": "Found fixable systemic defect"
+}
+```
+
+---
+
+### Phase 3: Root Cause Classification [Required]
+
+**Goal**: Classify root cause, determine repair direction.
+
+**Classification Criteria**:
+
+| Category | Definition | Repair Direction |
+|----------|------------|------------------|
+| `People` | Capability blind spots, cognitive biases, habit issues | Training, docs, reminders |
+| `Design` | Architecture defects, process gaps, insufficient gates | Refactor, add checks, automate |
+| `Assumption` | Wrong assumptions about env/versions/deps | Explicit checks, version locking, env validation |
+| `Tooling` | Tool misconfiguration, API changes | Fix config, upgrade, replace |
+
+**Guardrail Failure Analysis** (required for Design category):
+- Why didn't existing Hooks/Rules catch this?
+- Is it missing rules, loose matching, or logic loopholes?
+
+**Output Fields**:
+```json
+{
+  "phase": "root_cause_classification",
+  "root_cause": "...",
+  "category": "Design",
+  "guardrail_analysis": {
+    "existing_guards": ["hook_a", "rule_b"],
+    "failure_reason": "Missing rule: didn't check X condition",
+    "recommendation": "Add rule to check Y condition"
+  }
+}
+```
+
+---
+
+### Phase 4: Principle Extraction [Required]
+
+**Goal**: Extract reusable **highly abstract principles** to prevent similar issues.
+
+**⚠️ Key Distinction: Operational Rules vs Principles**
+
+| Level | Characteristics | Examples |
+|-------|-----------------|----------|
+| **Operational Rules** (atomic) | Specific to tool calls, file paths, code lines | "Check if directory exists before writing" |
+| **Principles** (abstract) | Cross-scenario applicability, describes behavioral norms and values | "Any file write must ensure integrity of target path, including directory structure and permission validation" |
+
+**Principle Extraction Rules**:
+1. **Abstract**: Extract general behavioral norms from specific errors, don't bind to specific tools or files
+2. **Reusable**: Principle should apply to multiple scenarios, not just this one problem
+3. **Concise**: One sentence should suffice, under 40 words
+4. **Verifiable**: Can clearly judge whether principle was followed
+5. **Deduplication check** (critical): After extraction, MUST compare with **Existing Principles** provided in HEARTBEAT.md. If core meaning is same or highly similar (>70% overlap), **MUST NOT output new principle**, instead mark `"duplicate": true` in `principle_extraction` and explain why.
+
+**Principle Structure**:
+```json
+{
+  "phase": "principle_extraction",
+  "principle": {
+    "id": "P_YYYYMMDD_HASH",
+    "trigger_pattern": "regex or keywords for auto-matching",
+    "action": "Specific check/gate/reminder action",
+    "abstracted_principle": "Highly abstract principle statement (under 40 words, cross-scenario)",
+    "rationale": "Why this principle prevents the problem",
+    "duplicate": false,
+    "duplicate_of": "If similar to existing principle, fill its ID and name",
+
+    "priority": "P0|P1|P2 (optional, default P1. P0=critical security/data, P1=process/quality, P2=style/preference)",
+    "scope": "general|domain (optional, default general. If domain, fill domain field)",
+    "domain": "If scope=domain, fill domain name like file_operations, api_calls, config_management",
+
+    "suggested_rules": [
+      {
+        "name": "Short rule name",
+        "type": "hook|gate|skill|test",
+        "trigger_condition": "When to trigger this rule",
+        "enforcement": "block|warn|log",
+        "action": "What specific action to execute",
+        "implementation_hint": "Suggested file path or module for implementation"
+      }
+    ],
+
+    "implementation": {
+      "type": "hook|rule|template",
+      "target_file": "Suggested file path to add to",
+      "code_snippet": "Pseudocode or implementation suggestion"
+    }
+  }
+}
+```
+
+**Field Notes**:
+- `priority`, `scope`, `domain`, `suggested_rules` are **optional fields**, can omit if unsure
+- `suggested_rules` are **suggestions** for grounding principles into concrete rules, each rule should be specific enough to implement directly
+- One principle typically corresponds to 1-3 rules, not too many (overly granular) or too few (overly abstract)
+
+**`abstracted_principle` Writing Guide**:
+
+❌ Wrong examples (operational rule level):
+- "Check if directory exists before writing"
+- "Read first then retry after edit tool failure"
+- "Check key validity before calling API"
+
+✅ Correct examples (principle level):
+- "Any write operation must ensure integrity of target environment"
+- "Confirm current state before modifying, avoid operating on stale information"
+- "External dependency availability must be validated before invocation"
+- "Code modifications must go through Issue process, ensuring traceability and rollback"
+
+**Reference Existing Principle Styles** (you'll see existing principle entries in HEARTBEAT.md, keep consistent style):
+- P-10: Process as Authority — "When having technical capability to execute operations directly, must check if agreed-upon process exists"
+- P-11: Pre-write Validation — "Before writing to any high-risk path, first read to confirm file's current actual content"
+
+---
+
+## 📤 Final Output Format
+
+### ⚠️ JSON Format Mandatory Constraints (Violation = Output Invalid)
+
+Your diagnostic report will be **auto-parsed as JSON**. Any format errors will cause results to be discarded.
+
+**MUST comply**:
+1. **ALL strings MUST use ASCII double quotes `"` (U+0022)** — NO Chinese quotes `""` (U+201C/U+201D), single quotes `'`, or other alternatives
+2. **NO unescaped control characters in JSON** — Use `\n` for newlines, `\t` for tabs
+3. **NO extra text outside JSON** — Don't write "OK, here's..." or similar lead-ins
+4. **NO comments** — JSON doesn't support `//` or `/* */`
+5. **NO trailing comma after last element** — Most common JSON error
+
+**Self-check method**: Before outputting, mentally verify: every `"` must have matching `"` after it, if content contains `"` it must be escaped as `\"`.
+
+Merge outputs from all four phases into one JSON object:
+
+```json
+{
+  "diagnosis_report": {
+    "task_id": "...",
+    "timestamp": "2026-03-24T...",
+    "summary": "One-sentence summary of root cause",
+    "phases": {
+      "context_extraction": { "session_id": "...", "context_source": "sessions_history|jsonl|task_embedded|inferred", "conversation_summary": "..." },
+      "evidence_gathering": { ... },
+      "causal_chain": { ... },
+      "root_cause_classification": { ... },
+      "principle_extraction": { ... }
+    }
+  }
+}
+```
+
+---
+
+## ⚠️ Execution Constraints
+
+1. **NO skipping phases**: MUST attempt Phase 0, then execute Phase 1 → 2 → 3 → 4 in order
+2. **NO evidence-less reasoning**: Each Why's answer MUST have evidence field
+3. **NO vague conclusions**: Root cause must be specific and fixable
+4. **NO skipping principle extraction**: Even for simple issues, extract principles
+
+---
+
+## Example
+
+**Input**:
+```
+Diagnose systemic pain [ID: abc123].
+**Source**: tool_failure
+**Reason**: Tool edit failed on MEMORY.md
+**Trigger Text**: "Cannot write to MEMORY.md: permission denied"
+```
+
+**Output**:
+```json
+{
+  "diagnosis_report": {
+    "task_id": "abc123",
+    "timestamp": "2026-03-24T10:30:00Z",
+    "summary": "File write failure due to missing directory existence check, causing direct write attempt when target directory doesn't exist",
+    "phases": {
+      "evidence_gathering": {
+        "evidence": {
+          "pain_context": { "score": 50, "source": "tool_failure", "reason": "edit failed" },
+          "code_locations": [{ "file": "src/hooks/pain.ts", "line": 78, "snippet": "fs.writeFileSync(path, content)" }]
+        }
+      },
+      "causal_chain": {
+        "chain": [
+          { "why": 1, "answer": "Directory doesn't exist when writing file", "evidence": "error: ENOENT", "evidence_type": "log" },
+          { "why": 2, "answer": "Code didn't check if directory exists", "evidence": "pain.ts:78", "evidence_type": "code" },
+          { "why": 3, "answer": "Missing directory check gate before file write", "evidence": "no relevant checks in hooks directory", "evidence_type": "code" }
+        ],
+        "terminated_at": 3,
+        "termination_reason": "Found missing gate mechanism"
+      },
+      "root_cause_classification": {
+        "root_cause": "Missing directory existence check gate before file write",
+        "category": "Design",
+        "guardrail_analysis": {
+          "existing_guards": [],
+          "failure_reason": "No pre-write check hook",
+          "recommendation": "Add before_file_write hook to check directory existence"
+        }
+      },
+      "principle_extraction": {
+        "principle": {
+          "id": "P_20260324_dircheck",
+          "trigger_pattern": "fs\\.writeFileSync|writeFile|mkdirSync",
+          "action": "Check if target directory exists before writing, create if not",
+          "abstracted_principle": "Any write operation must ensure integrity of target environment",
+          "rationale": "Prevents write failures when directory doesn't exist",
+          "implementation": {
+            "type": "hook",
+            "target_file": "src/hooks/file-safety.ts",
+            "code_snippet": "if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+Begin analysis task now.

package/templates/langs/en/skills/pd-explorer/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: pd-explorer
+description: Rapid evidence collection to locate files, logs, and reproduction steps related to an issue. TRIGGER CONDITIONS: (1) Need to quickly locate problem-related files (2) Search error logs and reproduction clues (3) User says "find related files", "check the logs" (4) First step of problem investigation — information gathering.
+disable-model-invocation: true
+---
+
+# Explorer
+
+You are a rapid evidence collection expert. Your task is to quickly locate and gather issue-related information.
+
+## Work Method
+
+Use a systematic evidence collection approach:
+
+1. **Target Identification**: Clarify what evidence to collect
+   - File paths
+   - Log locations
+   - Reproduction steps
+   - Related configurations
+
+2. **Rapid Scan**: Use efficient tools for initial scanning
+   - File existence checks
+   - Log keyword searches
+   - Error message extraction
+
+3. **Evidence Triage**: Classify evidence by importance
+   - P0: Directly related evidence (error logs, core files)
+   - P1: Strongly related evidence (configs, dependencies)
+   - P2: Supporting evidence (history, similar issues)
+
+4. **Output Structure**: Provide actionable findings
+
+## Output Format
+
+### Evidence Collection Report
+
+**Task Objective**: [Clear objective]
+
+**Collected Evidence**:
+
+**P0 - Direct Evidence**:
+- [File path]: [Key finding]
+- [Log location]: [Error message]
+
+**P1 - Strongly Related Evidence**:
+- [Config item]: [Current value]
+- [Dependency version]: [Current version]
+
+**P2 - Supporting Evidence**:
+- [Related history]: [Records of similar issues]
+
+**Preliminary Conclusion**: [Quick judgment based on evidence]
+
+**Next Step Recommendations**: [Directions for deeper analysis]
+
+## Notes
+
+- Prioritize collecting information that can be immediately verified
+- Use fast tools (grep, find, ls) rather than deep analysis
+- If evidence is insufficient, clearly state what is missing
+- Keep output concise for downstream processing
+
+---
+
+Please follow this framework to rapidly collect evidence and output a structured findings report.

package/templates/langs/en/skills/pd-grooming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-grooming
-description: Perform a "Workspace Grooming" to archive or clean up scattered temporary files, maintaining digital cleanliness.
+description: Perform a "Workspace Grooming" to archive or clean up scattered temporary files. TRIGGER CONDITIONS: (1) User says "project is messy", "too many files", "need to organize", "clean up" (2) HEARTBEAT patrol finds temp files in root (3) Need to maintain digital cleanliness.
 ---
 
 # 🧹 Skill: Workspace Grooming

package/templates/langs/en/skills/pd-implementer/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: pd-implementer
+description: Execute code modifications according to a plan, implementing changes step by step. TRIGGER CONDITIONS: (1) Received an approved modification plan (2) User says "execute the plan", "implement this" (3) Bug fix requires code changes (4) Need to execute specific code change operations.
+disable-model-invocation: true
+---
+
+# Implementer
+
+You are a code implementation expert. Your task is to execute code modifications according to a plan.
+
+## Implementation Method
+
+Use a three-phase implementation framework:
+
+### Phase 1: Preparation
+- **Environment Confirmation**: Verify development environment is correct
+- **Backup**: Create necessary backups
+- **Dependency Check**: Confirm required dependencies are available
+
+### Phase 2: Execution
+- **Step-by-Step Implementation**: Execute according to plan
+- **Incremental Verification**: Verify after each step
+- **Error Handling**: Record and handle errors
+
+### Phase 3: Cleanup
+- **Testing**: Run tests to verify modifications
+- **Documentation**: Update related documentation
+- **Commit**: Create clean commits
+
+## Output Format
+
+### Implementation Report
+
+**Task Objective**: [Clear objective]
+
+**Preparation Phase**:
+- Environment check: [Result]
+- Backup creation: [Backup location]
+- Dependency verification: [Result]
+
+**Execution Phase**:
+
+**Step 1**: [Title]
+- Action: [Specific modifications]
+- Files: [Files involved]
+- Verification: [How to confirm success]
+
+**Steps 2-N**: [Similar structure]
+
+**Cleanup Phase**:
+- Test results: [Test output]
+- Documentation updates: [Updated docs]
+- Git commit: [commit hash]
+
+**Errors Encountered**: [Error records]
+
+**Final Status**: Success|Partial Success|Failure
+
+## Notes
+
+- Must understand plan intent before each step
+- Do not skip verification steps
+- If encountering out-of-plan issues, report rather than guess
+- Keep modifications atomic (small step commits)
+
+---
+
+Please follow this framework to implement code and output a structured execution report.

package/templates/langs/en/skills/pd-mentor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pd-mentor
-description: Spicy Mentor - Interactive command guidance and scenario-based recommendations
+description: Interactive command guidance and scenario-based recommendations to help users understand Principles Disciple features. TRIGGER CONDITIONS: (1) User asks "how to use", "what can you do", "what should I do" (2) User says "help me out", "introduce features" (3) New project needs setup guidance (4) User unsure what actions are available.
 disable-model-invocation: true
 ---
 

package/templates/langs/en/skills/pd-pain-signal/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: pd-pain-signal
+description: Manually inject a pain signal into the evolution system by writing to .state/.pain_flag. TRIGGER CONDITIONS: (1) User reports agent stuck/looping/unresponsive (2) User says "record this issue", "force reflection", "trigger pain" (3) Tool failure with no follow-up action (4) User provides human intervention feedback.
+disable-model-invocation: true
+---
+
+# Pain Signal (Force Pain Signal)
+
+You are now the "Manual Intervention Pain" component.
+
+**Task**:
+1. Write the user's feedback `$ARGUMENTS` as a **high-priority** pain signal to `.state/.pain_flag`.
+2. Inform the user that the signal has been injected, and suggest waiting for the next Hook trigger (e.g., Stop or PreCompact) or manually running `/reflection-log`.
+
+**Write Format** (must use this KV format, consistent with auto-detection channels):
+
+```
+agent_id: <current agent ID, e.g., main/builder/diagnostician>
+is_risky: false
+reason: <user's feedback verbatim>
+score: 80
+session_id: <current session ID>
+source: human_intervention
+time: <ISO 8601 timestamp>
+trace_id:
+trigger_text_preview:
+```
+
+**Field Notes**:
+- `source`: Fixed as `human_intervention`
+- `score`: Default `80` for manual intervention (high priority)
+- `session_id`: Current session ID (from context)
+- `agent_id`: Current agent ID (from context)
+- `is_risky`: Fixed as `false`
+- `trace_id` / `trigger_text_preview`: Leave empty
+
+**⚠️ Important**: Do NOT use other formats (like writing only Source/Reason/Time lines). Downstream diagnostic systems depend on the complete KV field set.